diff --git a/aspnetcore/blazor/forms-and-input-components.md b/aspnetcore/blazor/forms-and-input-components.md index 5988da909481..4124f8cde26c 100644 --- a/aspnetcore/blazor/forms-and-input-components.md +++ b/aspnetcore/blazor/forms-and-input-components.md @@ -175,7 +175,7 @@ In the preceding `Starship1` component: * The component is an input component for editing string values. The `@bind-Value` directive attribute binds the `Model.Id` model property to the component's property. * The `Submit` method is registered as a handler for the callback. The handler is called when the form is submitted by the user. -Blazor enhances page navigation and form handling by intercepting the request in order to apply the response to the existing DOM, preserving as much of the rendered form as possible. The enhancement avoids the need to fully load the page and provides a much smoother user experience, similar to a single-page app (SPA), although the component is rendered on the server. +Blazor enhances page navigation and form handling by intercepting the request in order to apply the response to the existing DOM, preserving as much of the rendered form as possible. The enhancement avoids the need to fully load the page and provides a much smoother user experience, similar to a single-page app (SPA), although the component is rendered on the server. For more information, see . [Streaming rendering](xref:blazor/components/rendering#streaming-rendering) is supported with forms. For an example, see the [`StreamingRenderingForm` test asset (`dotnet/aspnetcore` GitHub repository)](https://github.com/dotnet/aspnetcore/blob/main/src/Components/test/testassets/Components.TestServer/RazorComponents/Pages/Forms/StreamingRenderingForm.razor). diff --git a/aspnetcore/blazor/fundamentals/routing.md b/aspnetcore/blazor/fundamentals/routing.md index 51caaee4cc99..15968b72f79d 100644 --- a/aspnetcore/blazor/fundamentals/routing.md +++ b/aspnetcore/blazor/fundamentals/routing.md @@ -458,7 +458,22 @@ Slashes and segments of the captured path are decoded. For a route template of ` Use to manage URIs and navigation in C# code. provides the event and methods shown in the following table. -:::moniker range=">= aspnetcore-7.0" +:::moniker range=">= aspnetcore-8.0" + +| Member | Description | +| ------ | ----------- | +| | Gets the current absolute URI. | +| | Gets the base URI (with a trailing slash) that can be prepended to relative URI paths to produce an absolute URI. Typically, corresponds to the `href` attribute on the document's `` element ([location of `` content](xref:blazor/project-structure#location-of-head-and-body-content)). | +| | Navigates to the specified URI. If `forceLoad` is `false`:
  • And enhanced navigation is available at the current URL, Blazor's enhanced navigation is activated.
  • Otherwise, Blazor performs a full-page reload for the requested URL.
If `forceLoad` is `true`:
  • Client-side routing is bypassed.
  • The browser is forced to load the new page from the server, whether or not the URI is normally handled by the client-side interactive router.

For more information, see the [Enhanced navigation and form handling](#enhanced-navigation-and-form-handling) section.

If `replace` is `true`, the current URI in the browser history is replaced instead of pushing a new URI onto the history stack.

| +| | An event that fires when the navigation location has changed. For more information, see the [Location changes](#location-changes) section. | +| | Converts a relative URI into an absolute URI. | +| | Based on the app's base URI, converts an absolute URI into a URI relative to the base URI prefix. For an example, see the [Produce a URI relative to the base URI prefix](#produce-a-uri-relative-to-the-base-uri-prefix) section. | +| [`RegisterLocationChangingHandler`](#handleprevent-location-changes) | Registers a handler to process incoming navigation events. Calling always invokes the handler. | +| | Returns a URI constructed by updating with a single parameter added, updated, or removed. For more information, see the [Query strings](#query-strings) section. | + +:::moniker-end + +:::moniker range=">= aspnetcore-7.0 < aspnetcore-8.0" | Member | Description | | ------ | ----------- | @@ -500,6 +515,48 @@ Use to manage URIs and :::moniker-end +:::moniker range=">= aspnetcore-8.0" + +## Enhanced navigation and form handling + +*This section applies to Blazor Web Apps.* + +Blazor Web Apps are capable of two types of routing for page navigation and form handling requests: + +* Normal navigation (cross-document navigation): a full-page reload is triggered for the request URL. +* Enhanced navigation (same-document navigation)†: Blazor intercepts the request and performs a `fetch` request instead. Blazor then patches the response content into the page's DOM. Blazor's enhanced navigation and form handling avoid the need for a full-page reload and preserves more of the page state, so pages load faster, usually without losing the user's scroll position on the page. + +†Enhanced navigation is available when: + +* The Blazor Web App script (`blazor.web.js`) is used, not the Blazor Server script (`blazor.server.js`) or Blazor WebAssembly script (`blazor.webassembly.js`). +* The feature isn't [explicitly disabled](xref:blazor/fundamentals/startup#enhanced-navigation-and-form-handling). +* The destination URL is within the internal base URI space (the app's base path). + +If enhanced navigation is available for interactive client routing, navigation always goes through the interactive client-side router. This point is only relevant in an uncommon scenario where an interactive `` is nested inside a server-side rendered ``. In that case, the interactive router takes priority when handling navigation, so enhanced navigation isn't used for navigation because it's a server-side routing feature. + +When calling : + +* If `forceLoad` is `false`, which is the default: + * And enhanced navigation is available at the current URL, Blazor's enhanced navigation is activated. + * Otherwise, Blazor performs a full-page reload for the requested URL. +* If `forceLoad` is `true`: Blazor performs a full-page reload for the requested URL, whether enhanced navigation is available or not. + +You can refresh the current page by calling `NavigationManager.Refresh(bool forceLoad = false)`, which always performs an enhanced navigation, if available. If enhanced navigation isn't available, Blazor performs a full-page reload. + +```csharp +Navigation.Refresh(); +``` + +Pass `true` to the `forceLoad` parameter to ensure a full-page reload is always performed, even if enhanced navigation is available: + +```csharp +Navigation.Refresh(true); +``` + +To disable enhanced navigation and form handling, see . + +:::moniker-end + ## Produce a URI relative to the base URI prefix Based on the app's base URI, converts an absolute URI into a URI relative to the base URI prefix. diff --git a/aspnetcore/blazor/fundamentals/startup.md b/aspnetcore/blazor/fundamentals/startup.md index fac7e0859e7e..d5a6c0ef62ab 100644 --- a/aspnetcore/blazor/fundamentals/startup.md +++ b/aspnetcore/blazor/fundamentals/startup.md @@ -462,7 +462,7 @@ In `wwwroot/index.html`, remove the default SVG round indicator in `
= aspnetcore-8.0" + +## Disable enhanced navigation and form handling + +*This section applies to Blazor Web Apps.* + +To disable enhanced navigation and form handling, set `disableDomPreservation` to `true` for `Blazor.start`: + +```html + + +``` + +In the preceding example, the `{BLAZOR SCRIPT}` placeholder is the Blazor script path and file name. + +:::moniker-end + ## Additional resources * [Environments: Set the app's environment](xref:blazor/fundamentals/environments) diff --git a/aspnetcore/release-notes/aspnetcore-8.0.md b/aspnetcore/release-notes/aspnetcore-8.0.md index 1cf1c23d218d..32385eb520a1 100644 --- a/aspnetcore/release-notes/aspnetcore-8.0.md +++ b/aspnetcore/release-notes/aspnetcore-8.0.md @@ -70,20 +70,9 @@ For more information, see . - ---> +For more information, see . ### Streaming rendering