ASP.NET Core-navigering Blazor

Den här artikeln beskriver hur du utlöser och hanterar sidnavigering i Blazor. Användarna kan navigera mellan olika sidor med vanliga HTML-länkar, Blazor men förbättrar navigeringen i programmet för att undvika att hela sidan läses in igen och ger en smidigare upplevelse. Använd komponenten NavLink för att skapa navigeringslänkar som automatiskt får stil när länken matchar den aktuella sidan. För programmeringsnavigering och URI-hantering i C#-kod använder du NavigationManager tjänsten.

Viktigt!

Kodexempel i den här artikeln visar metoder som anropas på Navigation, som är en injicerad NavigationManager i klasser och komponenter.

NavLink komponent

Använd en NavLink komponent i stället för HTML-hyperlänkelement (<a>) när du skapar navigeringslänkar. En NavLink-komponent fungerar som ett <a>-element, förutom att den växlar en active CSS-klass baserat på om dess href matchar den aktuella URL:en. Klassen active hjälper en användare att förstå vilken sida som är den aktiva sidan bland de navigeringslänkar som visas. Du kan också tilldela ett CSS-klassnamn till NavLink.ActiveClass för att tillämpa en anpassad CSS-klass på den renderade länken när den aktuella vägen matchar href.

I komponenten NavMenu (NavMenu.razor) för en Blazor app som skapats från en Blazor projektmall:

<div class="nav-item px-3">
    <NavLink class="nav-link" href="" Match="NavLinkMatch.All">
        <span class="bi bi-house-door-fill-nav-menu" aria-hidden="true"></span> Home
    </NavLink>
</div>
<div class="nav-item px-3">
    <NavLink class="nav-link" href="counter">
        <span class="bi bi-plus-square-fill-nav-menu" aria-hidden="true"></span> Counter
    </NavLink>
</div>

I föregående exempel matchar HomeNavLinkhref="" hem-URL:en och tar bara emot active CSS-klassen på appens standardbassökväg (/). Den andra NavLink tar emot active klassen när användaren besöker komponenten Counter på /counter.

Det finns två NavLinkMatch alternativ som du kan tilldela till attributet Match för <NavLink>-elementet:

• NavLinkMatch.All: NavLink är aktiv när den matchar den aktuella URL:en och ignorerar frågesträngen och fragmentet. För att inkludera matchning av frågesträng/fragment, använd växel inställd på Microsoft.AspNetCore.Components.Routing.NavLink.EnableMatchAllForQueryStringAndFragment.
• NavLinkMatch.Prefix (standard): NavLink är aktiv när den matchar prefixet för den aktuella URL:en.

För att använda anpassad matchningslogik, skapa en underklass till NavLink och åsidosätt dess ShouldMatch-metod. Returnera true från metoden när du vill tillämpa active CSS-klassen:

public class CustomNavLink : NavLink
{
    protected override bool ShouldMatch(string currentUriAbsolute)
    {
        // Custom matching logic
    }
}

Ytterligare komponentattribut för NavLink skickas till den renderade ankartaggen. I följande exempel innehåller komponenten NavLink attributet target:

<NavLink href="example-page" target="_blank">Example page</NavLink>

Följande HTML-kod återges:

<a href="example-page" target="_blank">Example page</a>

Varning

På grund av hur Blazor renderar underordnat innehåll kräver att rendera NavLink-komponenter i en for-loop en lokal indexvariabel om den inkrementerande loopvariabeln används i NavLink-komponentens innehåll.

@for (int c = 1; c < 4; c++)
{
    var ct = c;
    <li ...>
        <NavLink ...>
            <span ...></span> Product #@ct
        </NavLink>
    </li>
}

Att använda en indexvariabel i det här scenariot är ett krav för vilken som helst underordnad komponent som använder en loopvariabel i sitt underordnade innehåll, inte bara för komponenten NavLink.

Du kan också använda en foreach-loop med Enumerable.Range:

@foreach (var c in Enumerable.Range(1, 3))
{
    <li ...>
        <NavLink ...>
            <span ...></span> Product #@c
        </NavLink>
    </li>
}

URI och navigationsstatushjälpare

Använd NavigationManager för att hantera URI:er och navigering i C#-kod. NavigationManager innehåller den händelse och de metoder som visas i följande tabell.

Medlem	Description
Uri	Hämtar den aktuella absoluta URI:n.
BaseUri	Hämtar bas-URI:n (med ett avslutande snedstreck) som kan läggas till relativa URI-sökvägar för att bilda en absolut URI. Normalt motsvarar BaseUri-attributet href i dokumentets <base>-element (platsen för <head>-innehåll).
NavigateTo	Navigerar till den angivna URI:n. Om forceLoad är false: Och förbättrad navigering är tillgänglig på den aktuella webbadressen, den förbättrade navigeringen för Blazoraktiveras. Annars utför Blazor en omladdning av hela sidan för den begärda URL:en. Om forceLoad är true: Routning på klientsidan kringgås. Webbläsaren tvingas läsa in den nya sidan från servern, oavsett om URI:n normalt hanteras av den interaktiva routern på klientsidan. Mer information finns i avsnittet Förbättrad navigering och formulärhantering. Om replace är trueersätts den aktuella URI:n i webbläsarhistoriken i stället för att skicka en ny URI till historikstacken.
LocationChanged	En händelse som utlöses när navigeringspositionen ändras. Mer information finns i avsnittet Platsändringar.
NotFound	Anropas för att hantera scenarier där en begärd resurs inte hittas. Mer information finns i avsnittet Ej hittade svar.
ToAbsoluteUri	Konverterar en relativ URI till en absolut URI.
ToBaseRelativePath	Baserat på appens bas-URI konverterar en absolut URI till en URI i förhållande till bas-URI-prefixet. Ett exempel finns i avsnittet Skapa en URI i förhållande till bas-URI-prefixet.
RegisterLocationChangingHandler	Registrerar en hanterare för att bearbeta inkommande navigeringshändelser. Att anropa NavigateTo utlöser alltid hanteraren.
GetUriWithQueryParameter	Returnerar en URI som skapats genom att uppdatera NavigationManager.Uri med en enskild parameter som har lagts till, uppdaterats eller tagits bort. Mer information finns i avsnittet Frågesträngar.

Platsändringar

För den LocationChanged händelsen innehåller LocationChangedEventArgs följande information om navigeringshändelser:

• Location: URL:en för den nya platsen.
• IsNavigationIntercepted: Om truehar Blazor fångat upp navigeringen från webbläsaren. Om falseeller NavigationManager.NavigateTo orsakade navigeringen.

Följande komponent:

• Navigerar till appens Counter komponent (Counter.razor) när knappen väljs med hjälp av NavigateTo.
• Hanterar platsändringshändelsen genom att lyssna på NavigationManager.LocationChanged.

  • Metoden HandleLocationChanged kopplas bort när Dispose anropas av ramverket. Genom att koppla bort metoden tillåts skräpinsamling för komponenten.

  • Loggningsimplementeringen loggar följande information när knappen väljs:

    BlazorSample.Pages.Navigate: Information: URL of new location: https://localhost:{PORT}/counter

Navigate.razor:

@page "/navigate"
@implements IDisposable
@inject ILogger<Navigate> Logger
@inject NavigationManager Navigation

<h1>Navigate Example</h1>

<button class="btn btn-primary" @onclick="NavigateToCounterComponent">
    Navigate to the Counter component
</button>

@code {
    private void NavigateToCounterComponent() => Navigation.NavigateTo("counter");

    protected override void OnInitialized() => 
        Navigation.LocationChanged += HandleLocationChanged;

    private void HandleLocationChanged(object? sender, LocationChangedEventArgs e) => 
        Logger.LogInformation("URL of new location: {Location}", e.Location);

    public void Dispose() => Navigation.LocationChanged -= HandleLocationChanged;
}

Mer information om bortskaffande av komponenter finns i ASP.NET Core Razor.

Omdirigeringsbeteende för Navigeringshanteraren under statisk återgivning på serversidan (statisk SSR)

För en omdirigering under statisk återgivning på serversidan (statisk SSR) NavigationManager förlitar sig på att generera en NavigationException som hämtas av ramverket, vilket konverterar felet till en omdirigering. Kod som finns efter anropet till NavigateTo anropas inte. När du använder Visual Studio bryts felsökningsprogrammet på undantaget, vilket kräver att du avmarkerar kryssrutan för Break när den här undantagstypen hanteras av användaren i Visual Studio-användargränssnittet för att undvika att felsökningsprogrammet stoppas för framtida omdirigeringar.

Du kan använda <BlazorDisableThrowNavigationException> egenskapen MSBuild inställd true på i appens projektfil för att välja att inte längre generera en NavigationException. Kod efter anropet till NavigateTo körs även när den inte skulle ha körts tidigare. Det här beteendet är aktiverat som standard i projektmallen .NET 10 eller senare Blazor Web App :

<BlazorDisableThrowNavigationException>true</BlazorDisableThrowNavigationException>

Svar hittades inte

NavigationManager tillhandahåller en NotFound metod för att hantera scenarier där en begärd resurs inte hittas under statisk återgivning på serversidan (statisk SSR) eller global interaktiv återgivning:

• Statisk SSR: Anrop NavigationManager.NotFound anger HTTP-statuskoden till 404.

• Interaktiv rendering: Signalerar Blazor routern (Router komponenten) att rendera innehåll som inte hittades.

• Återgivning av direktuppspelning: Om förbättrad navigering är aktiv återges innehåll som inte hittades utan att sidan läses in igen. När förbättrad navigering blockeras omdirigeras ramverket till Inte hittat innehåll med en siduppdatering.

Anmärkning

I följande diskussion nämns att en komponent som inte hittades Razor kan tilldelas till komponentens RouterNotFoundPage parameter. Parametern fungerar tillsammans med NavigationManager.NotFound och beskrivs mer detaljerat senare i det här avsnittet.

Strömmande rendering kan endast återge komponenter som har en rutt, till exempel en NotFoundPage tilldelning (NotFoundPage="...") eller en Status Code Pages Re-execution Middleware-sidtilldelning (UseStatusCodePagesWithReExecute). DefaultNotFound 404-innehåll ("Not found" oformaterad text) har ingen väg, så det kan inte användas under strömningsrendering.

Anmärkning

Återgivningsfragmentet Hittades inte (<NotFound>...</NotFound>) stöds inte i .NET 10 eller senare.

NavigationManager.NotFound innehållsåtergivning använder följande, oavsett om svaret har startat eller inte (i ordning):

• Om NotFoundEventArgs.Path har angetts återger du innehållet på den tilldelade sidan.
• Om Router.NotFoundPage har angetts återger du den tilldelade sidan.
• Om du har konfigurerat en statuskodsida kör du middleware-sidan igen.
• Ingen åtgärd om ingen av ovanstående metoder har antagits.

Statuskodssidor Återexekveringsmiddleware med UseStatusCodePagesWithReExecute prioriteras för webbläsarbaserade adresseringsproblem, såsom en felaktig URL som skrivits in i webbläsarens adressfält eller när en länk väljs som saknar en slutpunkt i appen.

När en komponent återges statiskt (statisk SSR) och NavigationManager.NotFound anropas anges statuskoden 404 på svaret:

@page "/render-not-found-ssr"
@inject NavigationManager Navigation

@code {
    protected override void OnInitialized()
    {
        Navigation.NotFound();
    }
}

Om du vill ange innehåll som inte hittades för global interaktiv återgivning använder du sidan Hittades inte (Razor komponent).

Anmärkning

Projektmallen Blazor innehåller en NotFound.razor sida. Den här sidan renderas automatiskt när NavigationManager.NotFound anropas, vilket gör det möjligt att hantera saknade rutter med en konsekvent användarupplevelse.

Pages/NotFound.razor:

@page "/not-found"
@layout MainLayout

<h3>Not Found</h3>
<p>Sorry, the content you are looking for does not exist.</p>

Komponenten NotFound tilldelas routerns NotFoundPage parameter. NotFoundPage stöder routning som kan användas på statuskodsidor Omkörning av mellanprogram, inklusive icke-mellanprogramBlazor .

I följande exempel finns den föregående NotFound-komponenten i appens Pages-mapp och skickas till parametern NotFoundPage.

<Router AppAssembly="@typeof(Program).Assembly" NotFoundPage="typeof(Pages.NotFound)">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" />
        <FocusOnNavigate RouteData="@routeData" Selector="h1" />
    </Found>
</Router>

När en komponent renderas med ett globalt interaktivt återgivningsläge anropar du NavigationManager.NotFound routern Blazor för att återge komponenten NotFound :

@page "/render-not-found-interactive"
@inject NavigationManager Navigation

@if (RendererInfo.IsInteractive)
{
    <button @onclick="TriggerNotFound">Trigger Not Found</button>
}

@code {
    private void TriggerNotFound()
    {
        Navigation.NotFound();
    }
}

Du kan använda OnNotFound-händelsen för meddelanden när NavigationManager.NotFound anropas. Händelsen utlöses endast när NavigationManager.NotFound anropas, inte för något 404-svar. Till exempel, att ställa in HttpContextAccessor.HttpContext.Response.StatusCode till 404 utlöser inte NavigationManager.NotFound/OnNotFound.

Appar som implementerar en anpassad router kan också använda NavigationManager.NotFound. Den anpassade routern kan återge innehåll som inte hittades från två källor, beroende på svarets tillstånd:

• Oavsett svarstillstånd kan återutföringsvägen till sidan användas genom att skicka den till UseStatusCodePagesWithReExecute:

  app.UseStatusCodePagesWithReExecute(
      "/not-found", createScopeForStatusCodePages: true);
  

• När svaret har startat kan NotFoundEventArgs.Path användas genom att prenumerera på OnNotFoundEvent i routern.

  @code {
      [CascadingParameter]
      public HttpContext? HttpContext { get; set; }
  
      private void OnNotFoundEvent(object sender, NotFoundEventArgs e)
      {
          // Only execute the logic if HTTP response has started,
          // because setting NotFoundEventArgs.Path blocks re-execution
          if (HttpContext?.Response.HasStarted == false)
          {
              return;
          }
  
          var type = typeof(CustomNotFoundPage);
          var routeAttributes = type.GetCustomAttributes<RouteAttribute>(inherit: true);
  
          if (routeAttributes.Length == 0)
          {
              throw new InvalidOperationException($"The type {type.FullName} " +
                  $"doesn't have a {nameof(RouteAttribute)} applied.");
          }
  
          var routeAttribute = (RouteAttribute)routeAttributes[0];
  
          if (routeAttribute.Template != null)
          {
              e.Path = routeAttribute.Template;
          }
      }
  }
  

I följande exempel för komponenter som använder interaktiv återgivning på serversidan (interaktiv SSR) återges anpassat innehåll beroende på var OnNotFound som anropas. Om händelsen utlöses av följande Movie komponent när en film inte hittas vid komponentinitiering visas ett anpassat meddelande om att den begärda filmen inte hittas. Om händelsen utlöses av komponenten User i följande exempel visas ett annat meddelande om att användaren inte hittas.

Följande NotFoundContext tjänst hanterar kontexten och meddelandet för när innehåll inte hittas av komponenter.

NotFoundContext.cs:

public class NotFoundContext
{
    public string? Heading { get; private set; }
    public string? Message { get; private set; }

    public void UpdateContext(string heading, string message)
    {
        Heading = heading;
        Message = message;
    }
}

Tjänsten är registrerad i filen på serversidan Program :

builder.Services.AddScoped<NotFoundContext>();

Sidan NotFound matar in NotFoundContext och visar rubriken och meddelandet.

Pages/NotFound.razor:

@page "/not-found"
@layout MainLayout
@inject NotFoundContext NotFoundContext

<h3>@NotFoundContext.Heading</h3>
<div>
    <p>@NotFoundContext.Message</p>
</div>

Komponenten Routes (Routes.razor) anger komponenten NotFound som sidan Hittades inte via parametern NotFoundPage :

<Router AppAssembly="typeof(Program).Assembly" NotFoundPage="typeof(Pages.NotFound)">
    ...
</Router>

I följande exempelkomponenter:

• Tjänsten NotFoundContext matas in tillsammans med NavigationManager.
• OnInitializedAsync I HandleNotFoundär en händelsehanterare tilldelad till OnNotFound händelsen. HandleNotFound anropar NotFoundContext.UpdateContext för att ange en rubrik och ett meddelande för Innehåll som inte hittades i komponenten NotFound .
• Komponenterna använder normalt ett ID från en vägparameter för att hämta en film eller användare från ett datalager, till exempel en databas. I följande exempel returneras ingen entitet (null) för att simulera vad som händer när en entitet inte hittas.
• När ingen entitet returneras till OnInitializedAsyncNavigationManager.NotFound anropas , vilket i sin tur utlöser OnNotFound händelsen och HandleNotFound händelsehanteraren. Innehållet "Ej hittat" visas av routern.
• Metoden HandleNotFound avlägsnas vid komponentens borttagning i IDisposable.Dispose.

Movie komponent (Movie.razor):

@page "/movie/{Id:int}"
@implements IDisposable
@inject NavigationManager NavigationManager
@inject NotFoundContext NotFoundContext

<div>
    No matter what ID is used, no matching movie is returned
    from the call to GetMovie().
</div>

@code {
    [Parameter]
    public int Id { get; set; }

    protected override async Task OnInitializedAsync()
    {
        NavigationManager.OnNotFound += HandleNotFound;

        var movie = await GetMovie(Id);

        if (movie == null)
        {
            NavigationManager.NotFound();
        }
    }

    private void HandleNotFound(object? sender, NotFoundEventArgs e)
    {
        NotFoundContext.UpdateContext("Movie Not Found",
            "Sorry! The requested movie wasn't found.");
    }

    private async Task<MovieItem[]?> GetMovie(int id)
    {
        // Simulate no movie with matching id found
        return await Task.FromResult<MovieItem[]?>(null);
    }

    void IDisposable.Dispose()
    {
        NavigationManager.OnNotFound -= HandleNotFound;
    }

    public class MovieItem
    {
        public int Id { get; set; }
        public string? Title { get; set; }
    }
}

User komponent (User.razor):

@page "/user/{Id:int}"
@implements IDisposable
@inject NavigationManager NavigationManager
@inject NotFoundContext NotFoundContext

<div>
    No matter what ID is used, no matching user is returned
    from the call to GetUser().
</div>

@code {
    [Parameter]
    public int Id { get; set; }

    protected override async Task OnInitializedAsync()
    {
        NavigationManager.OnNotFound += HandleNotFound;

        var user = await GetUser(Id);

        if (user == null)
        {
            NavigationManager.NotFound();
        }
    }

    private void HandleNotFound(object? sender, NotFoundEventArgs e)
    {
        NotFoundContext.UpdateContext("User Not Found",
            "Sorry! The requested user wasn't found.");
    }

    private async Task<UserItem[]?> GetUser(int id)
    {
        // Simulate no user with matching id found
        return await Task.FromResult<UserItem[]?>(null);
    }

    void IDisposable.Dispose()
    {
        NavigationManager.OnNotFound -= HandleNotFound;
    }

    public class UserItem
    {
        public int Id { get; set; }
        public string? Name { get; set; }
    }
}

Om du vill nå de föregående komponenterna i en lokal demonstration med en testapp skapar du poster i komponenten NavMenu (NavMenu.razor) för att nå komponenterna Movie och User . Entitets-ID:n, som skickas som vägparametrar, i följande exempel är falska värden som inte har någon effekt eftersom de faktiskt inte används av komponenter, som simulerar att de inte hittar en film eller en användare.

I NavMenu.razor:

<div class="nav-item px-3">
    <NavLink class="nav-link" href="movie/1">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Movie
    </NavLink>
</div>

<div class="nav-item px-3">
    <NavLink class="nav-link" href="user/2">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> User
    </NavLink>
</div>

Förbättrad navigering och formulärhantering

Det här avsnittet gäller för Blazor Web Apps.

Blazor Web Apps kan hantera två typer av routning för begäranden om sidnavigering och formulärhantering:

• Normal navigering (navigering mellan dokument): en fullsidesbelastning utlöses för begärande-URL:en.
• Förbättrad navigering (navigering i samma dokument): Blazor fångar upp begäran och utför en fetch begäran i stället. Blazor korrigerar sedan svarsinnehållet i sidans DOM. Blazor:s förbättrade navigering och formulärhantering undviker behovet av en fullständig sidinläsning och bevarar mer av sidans tillstånd, så att sidorna läses in snabbare, vanligtvis utan att förlora användarens rullningsposition på sidan.

Förbättrad navigering är tillgänglig när:

• Skriptet Blazor Web App (blazor.web.js) används, inte skriptet Blazor Server (blazor.server.js) eller Blazor WebAssembly skript (blazor.webassembly.js).
• Funktionen är inte uttryckligen inaktiverad.
• Mål-URL finns inom det interna bas-URI-utrymmet (appens bassökväg) och länken till sidan saknar attributet data-enhance-nav som är inställt på false.

Om routning på serversidan och förbättrad navigering är aktiverade anropas platsbyteshanterare endast för programmatisk navigering som initieras från en interaktiv körning. I framtida versioner kan ytterligare typer av navigering, till exempel att följa en länk, även anropa platsbyteshanterare.

När en förbättrad navigering sker anropas vanligtvis LocationChanged händelsehanterare, som är registrerade med Interactive Server och WebAssembly-körtider. Det finns fall då platsbyteshanterare kanske inte fångar upp en förbättrad navigering. Användaren kan till exempel växla till en annan sida innan en interaktiv användning blir tillgänglig. Därför är det viktigt att applogik inte förlitar sig på att anropa en platsbyteshanterare, eftersom det inte finns någon garanti för att hanteraren körs.

När du anropar NavigateTo:

• Om forceLoad är false, vilket är standard:
  • Och förbättrad navigering är tillgänglig på den aktuella webbadressen, den förbättrade navigeringen för Blazoraktiveras.
  • Annars utför Blazor en omladdning av hela sidan för den begärda URL:en.
• Om forceLoad är true: Blazor utför en fullsidesomläsning för den begärda URL:en, oavsett om förbättrad navigering är tillgänglig eller inte.

Du kan ladda om den aktuella sidan genom att anropa NavigationManager.Refresh(bool forceLoad = false), vilket alltid utför en förbättrad navigering, om det är tillgängligt. Om förbättrad navigering inte är tillgänglig utför Blazor en helomladdning av sidan.

Navigation.Refresh();

Skicka true till parametern forceLoad för att säkerställa att en fullständig sidinläsning alltid utförs, även om förbättrad navigering är tillgänglig:

Navigation.Refresh(true);

Förbättrad navigering är aktiverad som standard, men den kan styras hierarkiskt och per länk med hjälp av data-enhance-nav HTML-attribut.

Följande exempel inaktiverar förbättrad navigering:

<a href="redirect" data-enhance-nav="false">
    GET without enhanced navigation
</a>

<ul data-enhance-nav="false">
    <li>
        <a href="redirect">GET without enhanced navigation</a>
    </li>
    <li>
        <a href="redirect-2">GET without enhanced navigation</a>
    </li>
</ul>

Om destinationen är en icke-Blazor slutpunkt, gäller inte den förbättrade navigeringen, och klient-sidans JavaScript försöker igen som en fullständig sidladdning. Detta säkerställer att det inte uppstår förvirring i ramverket om externa sidor som inte ska integreras med en befintlig sida.

Om du vill aktivera förbättrad formulärhantering lägger du till parametern Enhance i EditForm formulär eller attributet data-enhance i HTML-formulär (<form>):

<EditForm ... Enhance ...>
    ...
</EditForm>

<form ... data-enhance ...>
    ...
</form>

Förbättrad formulärhantering är inte hierarkisk och flödar inte till barnformulär.

❌ Stöds inte: Du kan inte ange förbättrad navigering i ett formulärs överordnade element för att aktivera förbättrad navigering för formuläret.

<div ... data-enhance ...>
    <form ...>
        <!-- NOT enhanced -->
    </form>
</div>

Förbättrade formulärposter fungerar bara med Blazor ändpunkter. Om du publicerar ett förbättrat formulär till en slutpunkt som inte ärBlazor resulterar det i ett fel.

Så här inaktiverar du förbättrad navigering:

• För en EditFormtar du bort parametern Enhance från formulärelementet (eller ställer in den på false: Enhance="false").
• För en HTML-<form>tar du bort attributet data-enhance från formulärelementet (eller anger det till false: data-enhance="false").

Den förbättrade navigerings- och formulärhanteringen i Blazorkan återställa dynamiska ändringar i DOM om det uppdaterade innehållet inte ingår i rendering från servern. Om du vill bevara innehållet i ett element använder du attributet data-permanent.

I följande exempel uppdateras innehållet i <div>-elementet dynamiskt av ett skript när sidan läses in:

<div data-permanent>
    ...
</div>

När Blazor har startats på klienten kan du använda händelsen enhancedload för att lyssna efter förbättrade siduppdateringar. Detta gör det möjligt att tillämpa ändringar på DOM som kan ha ångrats av en förbättrad siduppdatering.

Blazor.addEventListener('enhancedload', () => console.log('Enhanced update!'));

Information om hur du inaktiverar förbättrad navigering och formulärhantering globalt finns i ASP.NET Core Blazor start.

Förbättrad navigering med statisk återgivning på serversidan (statisk SSR) kräver särskild uppmärksamhet vid inläsning av JavaScript. Mer information finns i ASP.NET Core Blazor JavaScript med statisk återgivning på serversidan (statisk SSR).

Skapa en URI i förhållande till bas-URI-prefixet

Baserat på appens bas-URI konverterar ToBaseRelativePath en absolut URI till en URI i förhållande till bas-URI-prefixet.

Tänk på följande exempel:

try
{
    baseRelativePath = Navigation.ToBaseRelativePath(inputURI);
}
catch (ArgumentException ex)
{
    ...
}

Om appens bas-URI är https://localhost:8000erhålls följande resultat:

• När man skickar https://localhost:8000/segment i inputURI resulterar det i en baseRelativePath av segment.
• När man skickar https://localhost:8000/segment1/segment2 i inputURI resulterar det i en baseRelativePath av segment1/segment2.

Om appens bas-URI inte matchar bas-URI:n för inputURIgenereras en ArgumentException.

Att skicka https://localhost:8001/segment i inputURI resulterar i följande undantag:

System.ArgumentException: 'The URI 'https://localhost:8001/segment' is not contained by the base URI 'https://localhost:8000/'.'

Tillstånd för navigeringshistorik

NavigationManager använder webbläsarens historia-API för att upprätthålla navigeringshistorikens tillstånd, som är associerat med varje platsändring som görs av appen. Att upprätthålla historiktillstånd är särskilt användbart i externa omdirigeringsscenarier, till exempel när autentiserar användare med externa identitetsleverantörer. Mer information finns i avsnittet Navigeringsalternativ.

Navigeringsalternativ

Skicka NavigationOptions till NavigateTo för att kontrollera följande beteenden:

• ForceLoad: Kringgå routning på klientsidan och tvinga webbläsaren att läsa in den nya sidan från servern, oavsett om URI:n hanteras av routern på klientsidan eller inte. Standardvärdet är false.
• ReplaceHistoryEntry: Ersätt den nuvarande posten i historikstacken. Om falselägger du till den nya posten i historikstacken. Standardvärdet är false.
• HistoryEntryState: Hämtar eller anger tillståndet som ska läggas till i historikposten.

Navigation.NavigateTo("/path", new NavigationOptions
{
    HistoryEntryState = "Navigation state"
});

För mer information om hur du får tillgång till den status som är associerad med målhistorikposten när du hanterar platsändringar, se avsnittet Hantera/förhindra platsändringar.

Förfrågningssträngar

Använd attributet [SupplyParameterFromQuery] för att ange att en komponentparameter kommer från frågesträngen.

Komponentparametrar som tillhandahålls från frågesträngen stöder följande typer:

• bool, DateTime, decimal, double, float, Guid, int, , long. string
• Nullbara varianter av ovanstående typer.
• Matriser av föregående typer, oavsett om de är nullbara eller inte nullbara.

Rätt kulturvariantformatering tillämpas för den angivna typen (CultureInfo.InvariantCulture).

Ange egenskapen [SupplyParameterFromQuery] för attributet Name för att använda ett frågeparameternamn som skiljer sig från komponentparameternamnet. I följande exempel är C#-namnet för komponentparametern {COMPONENT PARAMETER NAME}. Ett annat frågeparameternamn anges för platshållaren {QUERY PARAMETER NAME}:

Till skillnad från egenskaper för komponentparameter ([Parameter]) kan [SupplyParameterFromQuery] egenskaper markeras private utöver public.

[SupplyParameterFromQuery(Name = "{QUERY PARAMETER NAME}")]
private string? {COMPONENT PARAMETER NAME} { get; set; }

I följande exempel med en URL för /search?filter=scifi%20stars&page=3&star=LeVar%20Burton&star=Gary%20Oldman:

• Egenskapen Filter resulterar i scifi stars.
• Egenskapen Page resulterar i 3.
• Matrisen Stars fylls i från frågeparametrar med namnet star (Name = "star") och matchas till LeVar Burton och Gary Oldman.

Anmärkning

Frågesträngsparametrarna i följande dirigerbara sidkomponent fungerar också i en icke-dirigerbar komponent utan ett @page direktiv (till exempel Search.razor för en delad Search komponent som används i andra komponenter).

Search.razor:

@page "/search"

<h1>Search Example</h1>

<p>Filter: @Filter</p>

<p>Page: @Page</p>

@if (Stars is not null)
{
    <p>Stars:</p>

    <ul>
        @foreach (var name in Stars)
        {
            <li>@name</li>
        }
    </ul>
}

@code {
    [SupplyParameterFromQuery]
    private string? Filter { get; set; }

    [SupplyParameterFromQuery]
    private int? Page { get; set; }

    [SupplyParameterFromQuery(Name = "star")]
    private string[]? Stars { get; set; }
}

Använd GetUriWithQueryParameter för att lägga till, ändra eller ta bort en eller flera frågeparametrar på den aktuella URL:en:

@inject NavigationManager Navigation

...

Navigation.GetUriWithQueryParameter("{NAME}", {VALUE})

I föregående exempel:

• Platshållaren {NAME} anger frågeparameterns namn. Platshållaren {VALUE} anger värdet som en typ som stöds. Typer som stöds visas senare i det här avsnittet.
• En sträng returneras lika med den aktuella URL:en med en enda parameter:
  • Har lagts till om frågeparameternamnet inte finns i den aktuella URL:en.
  • Uppdaterad till det värde som anges om frågeparametern finns i den aktuella URL:en.
  • Tas bort om typen av angivet värde är null och värdet är null.
• Rätt kulturvariantformatering tillämpas för den angivna typen (CultureInfo.InvariantCulture).
• Frågeparameterns namn och värde är URL-kodade.
• Alla värden med det matchande frågeparameternamnet ersätts om det finns flera instanser av typen.

Anropa GetUriWithQueryParameters för att skapa en URI som skapats från Uri med flera parametrar som har lagts till, uppdaterats eller tagits bort. För varje värde använder ramverket value?.GetType() för att fastställa körningstidstypen för varje frågeparameter och väljer rätt kulturinvariant formatering. Ramverket genererar ett fel för typer som inte stöds.

@inject NavigationManager Navigation

...

Navigation.GetUriWithQueryParameters({PARAMETERS})

Platshållaren {PARAMETERS} är en IReadOnlyDictionary<string, object>.

Skicka en URI-sträng till GetUriWithQueryParameters för att generera en ny URI från en angivet URI med flera parametrar som har lagts till, uppdaterats eller tagits bort. För varje värde använder ramverket value?.GetType() för att fastställa körningstidstypen för varje frågeparameter och väljer rätt kulturinvariant formatering. Ramverket genererar ett fel för typer som inte stöds. Typer som stöds visas senare i det här avsnittet.

@inject NavigationManager Navigation

...

Navigation.GetUriWithQueryParameters("{URI}", {PARAMETERS})

• Platshållaren {URI} är URI:n med eller utan en frågesträng.
• Platshållaren {PARAMETERS} är en IReadOnlyDictionary<string, object>.

Typer som stöds är identiska med typer som stöds för routningsbegränsningar:

• bool
• DateOnly
• DateTime
• decimal
• double
• float
• Guid
• int
• long
• string
• TimeOnly

Exempel på typer som stöds är:

• Nullbara varianter av ovanstående typer.
• Matriser av föregående typer, oavsett om de är nullbara eller inte nullbara.

Varning

Med komprimering, som är aktiverad som standard, undviker du att skapa säkra (autentiserade/auktoriserade) interaktiva komponenter på serversidan som återger data från ej betrodda källor. Ej betrodda källor omfattar routningsparametrar, frågesträngar, data från JS interop och alla andra datakällor som en användare från tredje part kan kontrollera (databaser, externa tjänster). Mer information finns i vägledningen för ASP.NET Core BlazorSignalR och vägledning för hotreducering för ASP.NET Core Blazor interaktiv server-sidesrendering.

Ersätt ett frågeparametervärde när parametern finns

Navigation.GetUriWithQueryParameter("full name", "Morena Baccarin")

Aktuell URL	Genererad URL
scheme://host/?full%20name=David%20Krumholtz&age=42	scheme://host/?full%20name=Morena%20Baccarin&age=42
scheme://host/?fUlL%20nAmE=David%20Krumholtz&AgE=42	scheme://host/?full%20name=Morena%20Baccarin&AgE=42
scheme://host/?full%20name=Jewel%20Staite&age=42&full%20name=Summer%20Glau	scheme://host/?full%20name=Morena%20Baccarin&age=42&full%20name=Morena%20Baccarin
scheme://host/?full%20name=&age=42	scheme://host/?full%20name=Morena%20Baccarin&age=42
scheme://host/?full%20name=	scheme://host/?full%20name=Morena%20Baccarin

Lägg till en frågeparameter och ett värde när parametern inte finns

Navigation.GetUriWithQueryParameter("name", "Morena Baccarin")

Aktuell URL	Genererad URL
scheme://host/?age=42	scheme://host/?age=42&name=Morena%20Baccarin
scheme://host/	scheme://host/?name=Morena%20Baccarin
scheme://host/?	scheme://host/?name=Morena%20Baccarin

Ta bort en frågeparameter när parametervärdet är null

Navigation.GetUriWithQueryParameter("full name", (string)null)

Aktuell URL	Genererad URL
scheme://host/?full%20name=David%20Krumholtz&age=42	scheme://host/?age=42
scheme://host/?full%20name=Sally%20Smith&age=42&full%20name=Summer%20Glau	scheme://host/?age=42
scheme://host/?full%20name=Sally%20Smith&age=42&FuLl%20NaMe=Summer%20Glau	scheme://host/?age=42
scheme://host/?full%20name=&age=42	scheme://host/?age=42
scheme://host/?full%20name=	scheme://host/

Lägga till, uppdatera och ta bort frågeparametrar

I följande exempel:

• name tas bort om det finns.
• age läggs till med värdet 25 (int), om det inte finns. Om det finns uppdateras age till värdet 25.
• eye color läggs till eller uppdateras till värdet green.

Navigation.GetUriWithQueryParameters(
    new Dictionary<string, object?>
    {
        ["name"] = null,
        ["age"] = (int?)25,
        ["eye color"] = "green"
    })

Aktuell URL	Genererad URL
scheme://host/?name=David%20Krumholtz&age=42	scheme://host/?age=25&eye%20color=green
scheme://host/?NaMe=David%20Krumholtz&AgE=42	scheme://host/?age=25&eye%20color=green
scheme://host/?name=David%20Krumholtz&age=42&keepme=true	scheme://host/?age=25&keepme=true&eye%20color=green
scheme://host/?age=42&eye%20color=87	scheme://host/?age=25&eye%20color=green
scheme://host/?	scheme://host/?age=25&eye%20color=green
scheme://host/	scheme://host/?age=25&eye%20color=green

Stöd för uppräkningsbara värden

I följande exempel:

• full name läggs till eller uppdateras till Morena Baccarin, ett enda värde.
• ping parametrar läggs till eller ersätts med 35, 16, 87 och 240.

Navigation.GetUriWithQueryParameters(
    new Dictionary<string, object?>
    {
        ["full name"] = "Morena Baccarin",
        ["ping"] = new int?[] { 35, 16, null, 87, 240 }
    })

Aktuell URL	Genererad URL
scheme://host/?full%20name=David%20Krumholtz&ping=8&ping=300	scheme://host/?full%20name=Morena%20Baccarin&ping=35&ping=16&ping=87&ping=240
scheme://host/?ping=8&full%20name=David%20Krumholtz&ping=300	scheme://host/?ping=35&full%20name=Morena%20Baccarin&ping=16&ping=87&ping=240
scheme://host/?ping=8&ping=300&ping=50&ping=68&ping=42	scheme://host/?ping=35&ping=16&ping=87&ping=240&full%20name=Morena%20Baccarin

Navigera med en tillagd eller ändrad frågesträng

Om du vill navigera med en tillagd eller modifierad frågesträng skickar du en genererad URL till NavigateTo.

Följande exempelanrop:

• GetUriWithQueryParameter för att lägga till eller ersätta frågeparametern name med värdet Morena Baccarin.
• Anropar NavigateTo för att utlösa navigering till den nya URL:en.

Navigation.NavigateTo(
    Navigation.GetUriWithQueryParameter("name", "Morena Baccarin"));

Navigera till namngivna element

Navigera till ett namngivet element med hjälp av följande metoder med en hash-referens (#) till elementet. Vägar till element i komponenten och vägar till element i externa komponenter använder rotrelativa sökvägar. Ett inledande snedstreck (/) är valfritt.

Exempel på varje av följande metoder visar hur man navigerar till ett element med id av targetElement i Counter-komponenten.

• Fästelement (<a>) med ett href:

  <a href="/counter#targetElement">
  

• NavLink komponent med en href:

  <NavLink href="/counter#targetElement">
  

• NavigationManager.NavigateTo skicka den relativa URL:en:

  Navigation.NavigateTo("/counter#targetElement");
  

I följande exempel visas hur du navigerar till namngivna H2-rubriker i en komponent och till externa komponenter.

I komponenterna Home (Home.razor) och Counter (Counter.razor) placerar du följande markering längst ned i den befintliga komponentmarkeringen för att fungera som navigeringsmål. <div> skapar artificiellt lodrätt utrymme för att demonstrera webbläsarens rullningsbeteende:

<div class="border border-info rounded bg-info" style="height:500px"></div>

<h2 id="targetElement">Target H2 heading</h2>
<p>Content!</p>

Lägg till följande FragmentRouting komponent i appen.

FragmentRouting.razor:

@page "/fragment-routing"
@inject NavigationManager Navigation

<PageTitle>Fragment routing</PageTitle>

<h1>Fragment routing to named elements</h1>

<ul>
    <li>
        <a href="/fragment-routing#targetElement">
            Anchor in this component
        </a>
    </li>
    <li>
        <a href="/#targetElement">
            Anchor to the <code>Home</code> component
        </a>
    </li>
    <li>
        <a href="/counter#targetElement">
            Anchor to the <code>Counter</code> component
        </a>
    </li>
    <li>
        <NavLink href="/fragment-routing#targetElement">
            Use a `NavLink` component in this component
        </NavLink>
    </li>
    <li>
        <button @onclick="NavigateToElement">
            Navigate with <code>NavigationManager</code> to the 
            <code>Counter</code> component
        </button>
    </li>
</ul>

<div class="border border-info rounded bg-info" style="height:500px"></div>

<h2 id="targetElement">Target H2 heading</h2>
<p>Content!</p>

@code {
    private void NavigateToElement()
    {
        Navigation.NavigateTo("/counter#targetElement");
    }
}

Hantera/förhindra platsändringar

RegisterLocationChangingHandler registrerar en hanterare för att bearbeta inkommande navigeringshändelser. Hanterarens kontext som tillhandahålls av LocationChangingContext innehåller följande egenskaper:

• TargetLocation: Hämtar målpositionen.
• HistoryEntryState: Hämtar tillståndet som är kopplat till den aktuella historikposten.
• IsNavigationIntercepted: Hämtar om navigeringen har avbrutits från en länk.
• CancellationToken: Hämtar en CancellationToken för att avgöra om navigeringen avbröts, till exempel för att avgöra om användaren utlöste en annan navigering.
• PreventNavigation: Anropas för att förhindra att navigeringen fortsätter.

En komponent kan registrera flera platsbyteshanterare i OnAfterRender{Async} livscykelmetod. Navigeringen anropar alla platsbyteshanterare som registrerats i hela appen (över flera komponenter) och all intern navigering kör dem alla parallellt. Förutom att NavigateTo-hanterare anropas:

• När du väljer interna länkar, som är länkar som pekar på URL:er under appens bassökväg.
• När du navigerar med knapparna framåt och bakåt i en webbläsare.

Hanteringsfunktioner körs endast för intern navigering i appen. Om användaren väljer en länk som navigerar till en annan webbplats eller ändrar adressfältet till en annan webbplats manuellt, körs inte platsbyteshanterare.

Implementera IDisposable och ta bort registrerade hanterare för att avregistrera dem. Mer information finns i ASP.NET Core Razor komponenthantering.

Viktigt!

Försök inte köra DOM-rensningsuppgifter via JavaScript (JS) interop när du hanterar platsändringar. Använd MutationObserver-mönstret i JS på klienten. Mer information finns i ASP.NET Core Blazor JavaScript-samverkan (JS interop).

I följande exempel registreras en platsändringshanterare för navigeringshändelser.

NavHandler.razor:

@page "/nav-handler"
@implements IDisposable
@inject NavigationManager Navigation

<p>
    <button @onclick="@(() => Navigation.NavigateTo("/"))">
        Home (Allowed)
    </button>
    <button @onclick="@(() => Navigation.NavigateTo("/counter"))">
        Counter (Prevented)
    </button>
</p>

@code {
    private IDisposable? registration;

    protected override void OnAfterRender(bool firstRender)
    {
        if (firstRender)
        {
            registration = 
                Navigation.RegisterLocationChangingHandler(OnLocationChanging);
        }
    }

    private ValueTask OnLocationChanging(LocationChangingContext context)
    {
        if (context.TargetLocation == "/counter")
        {
            context.PreventNavigation();
        }

        return ValueTask.CompletedTask;
    }

    public void Dispose() => registration?.Dispose();
}

Eftersom intern navigering kan avbrytas asynkront kan flera överlappande anrop till registrerade hanterare inträffa. Till exempel kan flera hanterare anropas när användaren snabbt väljer bakåtknappen på en sida eller väljer flera länkar innan en navigering körs. Följande är en sammanfattning av den asynkrona navigeringslogik:

• Om någon platsbyteshanterare har registrerats återställs all navigering till en början och spelas sedan upp igen om navigeringen inte avbryts.
• Om överlappande navigeringsbegäranden görs avbryter den senaste begäran alltid tidigare begäranden, vilket innebär följande:
  • Appen kan behandla flera knappval för bakåt och framåt som en enda markering.
  • Om användaren väljer flera länkar innan navigeringen slutförs avgör den senaste länk som valts navigeringen.

Mer information om hur du skickar NavigationOptions till NavigateTo för att styra poster och status för navigeringshistorikstacken finns i avsnittet Navigeringsalternativ.

Mer exempelkod finns i NavigationManagerComponent i BasicTestApp (dotnet/aspnetcore referenskälla).

Anmärkning

Dokumentationslänkar till .NET-referenskällan läser vanligtvis in lagringsplatsens standardgren, vilket representerar den aktuella utvecklingen för nästa version av .NET. Om du vill välja en tagg för en specifik version använder du listrutan Välj bland grenar eller taggar. Mer information finns i Så här väljer du en versionstagg för ASP.NET Core-källkod (dotnet/AspNetCore.Docs #26205).

Komponenten NavigationLock fångar upp navigeringshändelser så länge den återges, vilket i praktiken "låser" en viss navigering tills ett beslut fattas om att antingen fortsätta eller avbryta. Använd NavigationLock när navigeringsavlyssning kan begränsas till en komponents livslängd.

NavigationLock parametrar:

• ConfirmExternalNavigation anger en webbläsardialogruta för att uppmana användaren att antingen bekräfta eller avbryta extern navigering. Standardvärdet är false. För att kunna visa bekräftelsedialogrutan krävs inledande användarinteraktion med sidan innan extern navigering utlöses med URL:en i webbläsarens adressfält. Mer information om interaktionskravet finns i Fönster: beforeunload händelse.
• OnBeforeInternalNavigation anger en callback-funktion för interna navigeringshändelser.

I den följande NavLock-komponenten:

• Ett försök att följa länken till Microsofts webbplats måste bekräftas av användaren innan navigeringen till https://www.microsoft.com lyckas.
• PreventNavigation anropas för att förhindra att navigering sker om användaren avböjer att bekräfta navigeringen via ett JavaScript (JS) interop-anrop som skapar dialogrutan JSconfirm.

NavLock.razor:

@page "/nav-lock"
@inject IJSRuntime JSRuntime
@inject NavigationManager Navigation

<NavigationLock ConfirmExternalNavigation="true" 
    OnBeforeInternalNavigation="OnBeforeInternalNavigation" />

<p>
    <button @onclick="Navigate">Navigate</button>
</p>

<p>
    <a href="https://www.microsoft.com">Microsoft homepage</a>
</p>

@code {
    private void Navigate()
    {
        Navigation.NavigateTo("/");
    }

    private async Task OnBeforeInternalNavigation(LocationChangingContext context)
    {
        var isConfirmed = await JSRuntime.InvokeAsync<bool>("confirm", 
            "Are you sure you want to navigate to the root page?");

        if (!isConfirmed)
        {
            context.PreventNavigation();
        }
    }
}

Mer exempelkod finns i komponenten ConfigurableNavigationLock i BasicTestApp (dotnet/aspnetcore referenskälla).

Dynamiskt genererade NavLink komponenter via reflektion

NavLink-komponentposter kan skapas dynamiskt från appens komponenter via reflection. I följande exempel visas den allmänna metoden för ytterligare anpassning.

För följande demonstration används en konsekvent standardnamnkonvention för appens komponenter:

• Dirigerbara komponentfilnamn använder Pascal-notation†, till exempel Pages/ProductDetail.razor.
• Sökvägar för dirigerbara komponentfiler matchar deras URL:er i kebab-stil‡ med bindestreck som visas mellan ord i en komponents ruttmall. Till exempel begärs en komponent ProductDetail med routemallen /product-detail (@page "/product-detail") i en webbläsare på den relativa URL:en /product-detail.

†Pascal case (upper camel case) är en namngivningskonvention utan blanksteg och skiljetecken, där varje ord börjar med stor bokstav, inklusive det första ordet.
‡Kebab case är en namngivningskonvention utan mellanslag och skiljetecken som använder gemener och bindestreck mellan ord.

I Razor-markering för komponenten NavMenu (NavMenu.razor) under standardsidan för Home läggs NavLink komponenter till från en samling:

<div class="nav-scrollable" 
    onclick="document.querySelector('.navbar-toggler').click()">
    <nav class="flex-column">
        <div class="nav-item px-3">
            <NavLink class="nav-link" href="" Match="NavLinkMatch.All">
                <span class="bi bi-house-door-fill-nav-menu" 
                    aria-hidden="true"></span> Home
            </NavLink>
        </div>

+       @foreach (var name in GetRoutableComponents())
+       {
+           <div class="nav-item px-3">
+               <NavLink class="nav-link" 
+                       href="@Regex.Replace(name, @"(\B[A-Z]|\d+)", "-$1").ToLower()">
+                   @Regex.Replace(name, @"(\B[A-Z]|\d+)", " $1")
+               </NavLink>
+           </div>
+       }

    </nav>
</div>

Metoden GetRoutableComponents i block @code:

public IEnumerable<string> GetRoutableComponents() => 
    Assembly.GetExecutingAssembly()
        .ExportedTypes
        .Where(t => t.IsSubclassOf(typeof(ComponentBase)))
        .Where(c => c.GetCustomAttributes(inherit: true)
                     .OfType<RouteAttribute>()
                     .Any())
        .Where(c => c.Name != "Home" && c.Name != "Error")
        .OrderBy(o => o.Name)
        .Select(c => c.Name);

Föregående exempel innehåller inte följande sidor i den renderade listan med komponenter:

• Home sida: Sidan visas separat från de automatiskt genererade länkarna eftersom den ska visas överst i listan och ange parametern Match.
• Error sida: Felsidan navigeras bara till av ramverket och bör inte visas.

För en demonstration av föregående kod i en exempelapp hämtar du exempelappenBlazor Web App eller Blazor WebAssembly.