Dela via

ASP.NET Core Blazor routning och navigering

Anteckning

Det här är inte den senaste versionen av den här artikeln. Den aktuella versionen finns i .NET 9-versionen av den här artikeln.

Varning

Den här versionen av ASP.NET Core stöds inte längre. Mer information finns i .NET och .NET Core Support Policy. Den aktuella versionen finns i .NET 9-versionen av den här artikeln.

Viktig

Den här informationen gäller en förhandsversionsprodukt som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som tillhandahålls här.

Den aktuella versionen finns i .NET 9-versionen av den här artikeln.

Den här artikeln beskriver hur du hanterar routning av Blazor appbegäran och hur du använder komponenten NavLink för att skapa navigeringslänkar.

Viktig

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

Statisk kontra interaktiv routning

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

Om prerendering är aktiveratutför Blazor routern (Router komponenten <Router> i Routes.razor) statisk routning till komponenter under statisk återgivning på serversidan (statisk SSR). Den här typen av routning kallas statisk routning.

När ett interaktivt återgivningsläge tilldelas till komponenten Routes blir routern Blazor interaktiv efter statisk SSR och statisk routing på servern. Den här typen av routning kallas interaktiv routning.

Statiska routrar använder slutpunktsroutning och HTTP-begärandesökvägen för att avgöra vilken komponent som ska återges. När routern blir interaktiv använder den dokumentets URL (URL:en i webbläsarens adressfält) för att avgöra vilken komponent som ska återges. Det innebär att den interaktiva routern dynamiskt kan ändra vilken komponent som återges om dokumentets URL ändras dynamiskt till en annan giltig intern URL, och den kan göra det utan att utföra en HTTP-begäran om att hämta nytt sidinnehåll.

Interaktiv routning förhindrar också prerendering eftersom nytt sidinnehåll inte begärs från servern med en normal sidbegäran. Mer information finns i Prerender ASP.NET Core Razor-komponenter.

Routningsmallar

Komponenten Router möjliggör routning till Razor komponenter och finns i appens Routes komponent (Components/Routes.razor).

Komponenten Router möjliggör routning till Razor komponenter. Komponenten Router används i komponenten App (App.razor).

När en Razor komponent (.razor) med ett @page direktiv kompileras, tillhandahålls den genererade komponentklassen en RouteAttribute som anger komponentens vägmall.

När appen startar genomsöks den sammansättning som anges som routerns AppAssembly för att samla in routningsinformation för appens komponenter som har en RouteAttribute.

Vid körning av RouteView-komponenten:

  • Tar emot RouteData från Router tillsammans med eventuella vägparametrar.
  • Renderar den angivna komponenten med sin layout, inklusive eventuella ytterligare kapslade layouter.

Du kan också ange en DefaultLayout parameter med en layoutklass för komponenter som inte anger en layout med @layout-direktivet. Ramverkets Blazor projektmallar ange MainLayout komponenten (MainLayout.razor) som appens standardlayout. Mer information om layouter finns i ASP.NET Core Blazor layouter.

Komponenter stöder flera vägmallar med flera @page-direktiv. Följande exempelkomponent läses in på begäranden för /blazor-route och /different-blazor-route.

BlazorRoute.razor:

@page "/blazor-route"
@page "/different-blazor-route"

<PageTitle>Routing</PageTitle>

<h1>Routing Example</h1>

<p>
    This page is reached at either <code>/blazor-route</code> or 
    <code>/different-blazor-route</code>.
</p>

@page "/blazor-route"
@page "/different-blazor-route"

<PageTitle>Routing</PageTitle>

<h1>Routing Example</h1>

<p>
    This page is reached at either <code>/blazor-route</code> or 
    <code>/different-blazor-route</code>.
</p>

@page "/blazor-route"
@page "/different-blazor-route"

<h1>Blazor routing</h1>

@page "/blazor-route"
@page "/different-blazor-route"

<h1>Blazor routing</h1>

@page "/blazor-route"
@page "/different-blazor-route"

<h1>Blazor routing</h1>

@page "/blazor-route"
@page "/different-blazor-route"

<h1>Blazor routing</h1>

Viktig

För att URL:er ska kunna lösas korrekt måste appen innehålla en <base>-tagg (plats för <head> innehåll) med den appbasväg som anges i attributet href. För mer information, se basvägen för ASP.NET Core-app Blazor.

Router interagerar inte med frågesträngsvärden. Information om hur du arbetar med frågesträngar finns i avsnittet Frågesträngar.

Som ett alternativ till att ange routningsmallen som en strängliteral med @page-direktivet kan konstantbaserade vägmallar anges med @attribute-direktivet.

I följande exempel ersätts @page-direktivet i en komponent med @attribute-direktivet och den konstantbaserade vägmallen i Constants.CounterRoute, som anges någon annanstans i appen till "/counter":

- @page "/counter"
+ @attribute [Route(Constants.CounterRoute)]

Anteckning

Med versionen av .NET 5.0.1 och för ytterligare 5.x-versioner innehåller komponenten Router parametern PreferExactMatches inställd på @true. Mer information finns i Migrera från ASP.NET Core 3.1 till .NET 5.

Fokusera ett element på navigering

Komponenten FocusOnNavigate anger användargränssnittets fokus till ett element baserat på en CSS-väljare när du har navigerat från en sida till en annan.

<FocusOnNavigate RouteData="routeData" Selector="h1" />

När Router-komponenten navigerar till en ny sida anger komponenten FocusOnNavigate fokus till sidans huvud på den översta nivån (<h1>). Det här är en vanlig strategi för att säkerställa att en sidnavigering meddelas när du använder en skärmläsare.

Ange anpassat innehåll när innehåll inte hittas

Med komponenten Router kan appen ange anpassat innehåll om innehållet inte hittas för den begärda vägen.

Ange anpassat innehåll för Router komponentens NotFound parameter:

<Router ...>
    ...
    <NotFound>
        ...
    </NotFound>
</Router>

Godtyckliga objekt, såsom andra interaktiva komponenter, stöds som innehåll i parametern NotFound. Om du vill använda en standardlayout för NotFound innehåll kan du läsa ASP.NET Core Blazor layouter.

Viktig

Blazor Web Appanvänder inte parametern NotFound (<NotFound>...</NotFound> markering), men parametern stöds† för bakåtkompatibilitet och för att undvika en ändring som skulle bryta ramverket. På serversidan hanterar ASP.NET Core-mellanprogramspipelinen begäranden på servern. Använd tekniker på serversidan för att hantera felaktiga begäranden.

I denna kontext innebär "Stöds" att placering av -markering inte resulterar i ett undantag, men att använda markeringen heller inte är effektivt.

Mer information, inklusive en rekommenderad metod för hantering av felaktiga begäranden, finns i ASP.NET Core Blazor renderingslägen.

Dirigera till komponenter från flera sammansättningar

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

Använd Router-komponentens AdditionalAssemblies-parameter och slutpunktskonventverktyget AddAdditionalAssemblies för att identifiera dirigerbara komponenter i ytterligare sammansättningar. Följande underavsnitt förklarar när och hur du använder varje API.

Statisk ruttning

För att identifiera dirigerbara komponenter från ytterligare sammansättningar för statisk återgivning på serversidan (statisk SSR), även om routern senare blir interaktiv för interaktiv rendering, måste sammansättningarna lämnas ut till Blazor ramverket. Anropa metoden AddAdditionalAssemblies med de ytterligare sammansättningarna länkade till MapRazorComponents i serverprojektets Program fil.

I följande exempel ingår de dirigerbara komponenterna i BlazorSample.Client-projektets sammansättning med hjälp av projektets _Imports.razor-fil:

app.MapRazorComponents<App>()
    .AddAdditionalAssemblies(typeof(BlazorSample.Client._Imports).Assembly);

Anteckning

Föregående vägledning gäller även i komponentklassbiblioteket scenarier. Ytterligare viktig vägledning för klassbibliotek och statisk SSR finns i ASP.NET Core Razor-klassbibliotek (RCL) med statisk återgivning på serversidan (statisk SSR).

Interaktiv routning

Ett interaktivt återgivningsläge kan tilldelas till komponenten Routes (Routes.razor) som gör Blazor routern interaktiv efter statisk SSR och statisk routning på servern. Till exempel tilldelar <Routes @rendermode="InteractiveServer" /> interaktiv återgivning på serversidan (interaktiv SSR) till komponenten Routes. Komponenten Router ärver interaktiv återgivning på serversidan (interaktiv SSR) från komponenten Routes. Routern blir interaktiv efter statisk routning på servern.

Intern navigering för interaktiv routning innebär inte att begära nytt sidinnehåll från servern. Därför sker inte prerendering för interna sidbegäranden. Mer information finns i Prerender ASP.NET Core Razor-komponenter.

Om Routes komponenten definieras i serverprojektet bör AdditionalAssemblies-parametern för komponenten Router innehålla .Client projektets sammansättning. På så sätt kan routern fungera korrekt när den återges interaktivt.

I följande exempel finns den Routes komponenten i serverprojektet, och _Imports.razor-filen i BlazorSample.Client-projektet anger sammansättningen för att söka efter dirigerbara komponenter:

<Router
    AppAssembly="..."
    AdditionalAssemblies="[ typeof(BlazorSample.Client._Imports).Assembly ]">
    ...
</Router>

Ytterligare sammansättningar genomsöks utöver den sammansättning som anges för AppAssembly.

Anteckning

Föregående vägledning gäller även i komponentklassbiblioteket scenarier.

Alternativt finns dirigerbara komponenter bara i .Client projekt med global interaktiv WebAssembly eller automatisk återgivning tillämpad, och Routes komponenten definieras i .Client projektet, inte serverprojektet. I det här fallet finns det inte externa sammansättningar med dirigerbara komponenter, så det är inte nödvändigt att ange ett värde för AdditionalAssemblies.

Det här avsnittet gäller för Blazor Server appar.

Använd Router-komponentens AdditionalAssemblies-parameter och slutpunktskonventverktyget AddAdditionalAssemblies för att identifiera dirigerbara komponenter i ytterligare sammansättningar.

I följande exempel är Component1 en dirigerbar komponent som definierats i ett refererat komponentklassbibliotek med namnet ComponentLibrary:

<Router
    AppAssembly="..."
    AdditionalAssemblies="new[] { typeof(ComponentLibrary.Component1).Assembly }">
    ...
</Router>

Ytterligare sammansättningar genomsöks utöver den sammansättning som anges för AppAssembly.

Routningsparametrar

Routern använder routningsparametrar för att fylla i motsvarande komponentparametrar med samma namn. Routparameternamn är skiftlägesokänsliga. I följande exempel tilldelar parametern text värdet för routningssegmentet till komponentens egenskap Text. När en begäran görs för /route-parameter-1/amazingåterges innehållet som Blazor is amazing!.

RouteParameter1.razor:

@page "/route-parameter-1/{text}"

<PageTitle>Route Parameter 1</PageTitle>

<h1>Route Parameter Example 1</h1>

<p>Blazor is @Text!</p>

@code {
    [Parameter]
    public string? Text { get; set; }
}

@page "/route-parameter-1/{text}"

<PageTitle>Route Parameter 1</PageTitle>

<h1>Route Parameter Example 1</h1>

<p>Blazor is @Text!</p>

@code {
    [Parameter]
    public string? Text { get; set; }
}

@page "/route-parameter-1/{text}"

<h1>Blazor is @Text!</h1>

@code {
    [Parameter]
    public string? Text { get; set; }
}

@page "/route-parameter-1/{text}"

<h1>Blazor is @Text!</h1>

@code {
    [Parameter]
    public string? Text { get; set; }
}

@page "/route-parameter-1/{text}"

<h1>Blazor is @Text!</h1>

@code {
    [Parameter]
    public string Text { get; set; }
}

@page "/route-parameter-1/{text}"

<h1>Blazor is @Text!</h1>

@code {
    [Parameter]
    public string Text { get; set; }
}

Valfria parametrar stöds. I följande exempel tilldelar den valfria parametern text värdet för routningssegmentet till komponentens Text egenskap. Om segmentet inte finns anges värdet för Text till fantastic.

Valfria parametrar stöds inte. I följande exempel tillämpas två @page direktiv. Det första direktivet tillåter navigering till komponenten utan en parameter. Det andra direktivet tilldelar värdet av ruttparametern {text} till komponentens egenskap Text.

RouteParameter2.razor:

@page "/route-parameter-2/{text?}"

<PageTitle>Route Parameter 2</PageTitle>

<h1>Route Parameter Example 2</h1>

<p>Blazor is @Text!</p>

@code {
    [Parameter]
    public string? Text { get; set; }

    protected override void OnParametersSet() => Text = Text ?? "fantastic";
}

@page "/route-parameter-2/{text?}"

<PageTitle>Route Parameter 2</PageTitle>

<h1>Route Parameter Example 2</h1>

<p>Blazor is @Text!</p>

@code {
    [Parameter]
    public string? Text { get; set; }

    protected override void OnParametersSet() => Text = Text ?? "fantastic";
}

@page "/route-parameter-2/{text?}"

<h1>Blazor is @Text!</h1>

@code {
    [Parameter]
    public string? Text { get; set; }

    protected override void OnParametersSet()
    {
        Text = Text ?? "fantastic";
    }
}

@page "/route-parameter-2/{text?}"

<h1>Blazor is @Text!</h1>

@code {
    [Parameter]
    public string? Text { get; set; }

    protected override void OnParametersSet()
    {
        Text = Text ?? "fantastic";
    }
}

@page "/route-parameter-2/{text?}"

<h1>Blazor is @Text!</h1>

@code {
    [Parameter]
    public string Text { get; set; }

    protected override void OnParametersSet()
    {
        Text = Text ?? "fantastic";
    }
}

@page "/route-parameter-2"
@page "/route-parameter-2/{text}"

<h1>Blazor is @Text!</h1>

@code {
    [Parameter]
    public string Text { get; set; }

    protected override void OnParametersSet()
    {
        Text = Text ?? "fantastic";
    }
}

När OnInitialized{Async} livscykelmetod används i stället för OnParametersSet{Async} livscykelmetodsker standardtilldelningen av egenskapen Text till fantastic inte om användaren navigerar inom samma komponent. Den här situationen uppstår till exempel när användaren navigerar från /route-parameter-2/amazing till /route-parameter-2. Eftersom komponentinstansen bevaras och accepterar nya parametrar anropas inte metoden OnInitialized igen.

Anteckning

Routningsparametrar fungerar inte med frågesträngsvärden. Information om hur du arbetar med frågesträngar finns i avsnittet Frågesträngar.

Vägbegränsningar

En routningsbegränsning tillämpar typmatchning på ett routningssegment till en komponent.

I följande exempel matchar vägen till den User komponenten endast om:

  • Ett Id vägsegment finns i begärande-URL:en.
  • Segmentet Id är av typen heltal (int).

User.razor:

@page "/user/{Id:int}"

<PageTitle>User</PageTitle>

<h1>User Example</h1>

<p>User Id: @Id</p>

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

Anteckning

Routningsbegränsningar fungerar inte med frågesträngsvärden. Information om hur du arbetar med frågesträngar finns i avsnittet Frågesträngar.

De vägbegränsningar som visas i följande tabell är tillgängliga. Mer information finns i varningen under tabellen för de routningsbegränsningar som matchar den invarianta kulturen.

Tvång Exempel Exempelmatchningar Invariant
kultur
matchande
bool {active:bool} true, FALSE Nej
datetime {dob:datetime} 2016-12-31, 2016-12-31 7:32pm Ja
decimal {price:decimal} 49.99, -1,000.01 Ja
double {weight:double} 1.234, -1,001.01e8 Ja
float {weight:float} 1.234, -1,001.01e8 Ja
guid {id:guid} 00001111-aaaa-2222-bbbb-3333cccc4444, {00001111-aaaa-2222-bbbb-3333cccc4444} Nej
int {id:int} 123456789, -123456789 Ja
long {ticks:long} 123456789, -123456789 Ja
nonfile {parameter:nonfile} Inte BlazorSample.styles.css, inte favicon.ico Ja

Varning

Routningsbegränsningar som verifierar URL:en och konverteras till en CLR-typ (till exempel int eller DateTime) använder alltid den invarianta kulturen. Dessa begränsningar förutsätter att URL:en inte kan lokaliseras.

Routbegränsningar fungerar också med valfria parametrar. I följande exempel krävs Id, men Option är en valfri boolesk vägparameter.

User.razor:

@page "/user/{id:int}/{option:bool?}"

<p>
    Id: @Id
</p>

<p>
    Option: @Option
</p>

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

    [Parameter]
    public bool Option { get; set; }
}

Undvik filinfångning i en ruttparameter

Följande routemall fångar oavsiktligt upp statiska resurssökvägar i sin valfria routeparameter (Optional). Till exempel avbildas appens formatmall (.styles.css) som bryter appens format:

@page "/{optional?}"

...

@code {
    [Parameter]
    public string? Optional { get; set; }
}

Om du vill begränsa en routningsparameter till att samla in sökvägar som inte är filer använder du :nonfile-begränsningen i routningsmallen:

@page "/{optional:nonfile?}"

Routning med URL:er som innehåller punkter

En standardvägsmall på serversidan förutsätter att om det sista segmentet i en begärande-URL innehåller en punkt (.) som en fil begärs. Till exempel tolkas den relativa URL-/example/some.thing av routern som en begäran om en fil med namnet some.thing. Utan ytterligare konfiguration returnerar en app ett 404 – Hittades inte svar om some.thing var tänkt att dirigeras till en komponent med ett @page-direktiv och some.thing är ett vägparametervärde. Om du vill använda en väg med en eller flera parametrar som innehåller en punkt måste appen konfigurera vägen med en anpassad mall.

Tänk på följande Example komponent som kan ta emot en vägparameter från det sista segmentet av URL:en.

Example.razor:

@page "/example/{param?}"

<p>
    Param: @Param
</p>

@code {
    [Parameter]
    public string? Param { get; set; }
}

@page "/example/{param?}"

<p>
    Param: @Param
</p>

@code {
    [Parameter]
    public string? Param { get; set; }
}

@page "/example/{param?}"

<p>
    Param: @Param
</p>

@code {
    [Parameter]
    public string Param { get; set; }
}

@page "/example"
@page "/example/{param}"

<p>
    Param: @Param
</p>

@code {
    [Parameter]
    public string Param { get; set; }
}

Om du vill tillåta Server app av en värdbaserad Blazor WebAssemblylösning att dirigera en begäran med en punkt i param routparameter lägger du till en mall för återställningsfilväg med en valfri parameter i filen Program.

app.MapFallbackToFile("/example/{param?}", "index.html");

Om du vill konfigurera en Blazor Server app för att dirigera en begäran med en punkt i ruttparametern lägger du till en återfallssidemall med den valfria parametern i param-filen:

app.MapFallbackToPage("/example/{param?}", "/_Host");

Mer information finns i Routning i ASP.NET Core.

Om du vill tillåta Server app i en värdbaserad Blazor WebAssemblylösning att dirigera begäran med en punkt i param routparameter, lägger du till en fallback-filvägsmall med den valfria parametern i Startup.Configure.

Startup.cs:

endpoints.MapFallbackToFile("/example/{param?}", "index.html");

För att konfigurera en Blazor Server-applikation för att dirigera begäran med en punkt i param-rutningsparametern, lägg till en standard sidvägsmall med den valfria parametern i Startup.Configure.

Startup.cs:

endpoints.MapFallbackToPage("/example/{param?}", "/_Host");

Mer information finns i Routning i ASP.NET Core.

Allomfattande vägparametrar

Catch-all-vägparametrar, som fångar upp sökvägar över flera mappgränser, stöds av komponenter.

Parametrar för allt-i-allo-routning är:

  • Namnges för att matcha ruttsegmentets namn. Namngivning är inte fallkänslig.
  • En typ av string. Ramverket tillhandahåller inte automatisk gjutning.
  • I slutet av URL:en.

CatchAll.razor:

@page "/catch-all/{*pageRoute}"

<PageTitle>Catch All</PageTitle>

<h1>Catch All Parameters Example</h1>

<p>Add some URI segments to the route and request the page again.</p>

<p>
    PageRoute: @PageRoute
</p>

@code {
    [Parameter]
    public string? PageRoute { get; set; }
}

@page "/catch-all/{*pageRoute}"

<PageTitle>Catch All</PageTitle>

<h1>Catch All Parameters Example</h1>

<p>Add some URI segments to the route and request the page again.</p>

<p>
    PageRoute: @PageRoute
</p>

@code {
    [Parameter]
    public string? PageRoute { get; set; }
}

@page "/catch-all/{*pageRoute}"

@code {
    [Parameter]
    public string? PageRoute { get; set; }
}

@page "/catch-all/{*pageRoute}"

@code {
    [Parameter]
    public string? PageRoute { get; set; }
}

@page "/catch-all/{*pageRoute}"

@code {
    [Parameter]
    public string PageRoute { get; set; }
}

För URL-/catch-all/this/is/a/test med en vägmall med /catch-all/{*pageRoute}anges värdet för PageRoute till this/is/a/test.

Snedstreck och segment i den fångade sökvägen avkodas. För en vägprofil med /catch-all/{*pageRoute}resulterar URL:en /catch-all/this/is/a%2Ftest%2A i this/is/a/test*.

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 Beskrivning
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.
Medlem Beskrivning
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.
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.
Medlem Beskrivning
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 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 routern på klientsidan.
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.
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.
Medlem Beskrivning
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 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 routern på klientsidan.
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.
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.
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.
Medlem Beskrivning
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 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 routern på klientsidan.
LocationChanged En händelse som utlöses när navigeringspositionen ändras.
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.

Platsändringar

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

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

<PageTitle>Navigate</PageTitle>

<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;
}

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

<PageTitle>Navigate</PageTitle>

<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;
}

@page "/navigate"
@using Microsoft.Extensions.Logging 
@implements IDisposable
@inject ILogger<Navigate> Logger
@inject NavigationManager Navigation

<h1>Navigate in component code 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;
    }
}

@page "/navigate"
@using Microsoft.Extensions.Logging 
@implements IDisposable
@inject ILogger<Navigate> Logger
@inject NavigationManager Navigation

<h1>Navigate in component code 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;
    }
}

@page "/navigate"
@using Microsoft.Extensions.Logging 
@implements IDisposable
@inject ILogger<Navigate> Logger
@inject NavigationManager Navigation

<h1>Navigate in component code 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;
    }
}

@page "/navigate"
@using Microsoft.Extensions.Logging 
@implements IDisposable
@inject ILogger<Navigate> Logger
@inject NavigationManager Navigation

<h1>Navigate in component code 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.

Svar hittades inte

I .NET 10 Preview 4 är inte hittade svar endast tillgängliga för statisk SSR och global interaktiv återgivning. Stöd för återgivning per sida/komponent planeras för förhandsversion 5 i juni 2025.

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 NotFound anger HTTP-statuskoden till 404.
  • Återgivning av direktuppspelning: Utlöser ett undantag om svaret redan har startat.
  • Interaktiv rendering: Signalerar Blazor routern (Router komponenten) att rendera innehåll som inte hittades.

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).

Anteckning

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

NotFound.razor:

<h1>Not Found</h1>

<p>Sorry! Nothing to show.</p>

Tilldela komponenten NotFound till routerns NotFoundPage parameter. NotFoundPage stöder routning som kan användas i omkörnings-mellanprogram, inklusive icke-Blazor-mellanprogram. Om återgivningsfragmentet NotFound definieras tillsammans med NotFoundPagehar sidan högre prioritet.

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 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 NotFound anropas. Händelsen utlöses endast när NotFound anropas, inte för något 404-svar. Till exempel, att ställa in HttpContextAccessor.HttpContext.Response.StatusCode till 404 utlöser inte NotFound/OnNotFound.

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 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; } = "Not Found";
    public string Message { get; private set; } = 
        "Sorry, the page that you requested couldn't be found.";

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

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

builder.Services.AddScoped<NotFoundContext>();

Komponenten Routes (Routes.razor):

  • Infogar NotFoundContext tjänsten.
  • Visar rubriken (Heading) och meddelandet (Message) när OnNotFound utlöses av ett anrop till NotFound.
@inject NotFoundContext NotFoundContext

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
        <FocusOnNavigate RouteData="routeData" Selector="h1" />
    </Found>
    <NotFound>
        <LayoutView Layout="typeof(Layout.MainLayout)">
            <h1>@NotFoundContext.Heading</h1> 
            <div>
                <p>@NotFoundContext.Message</p>
            </div>
        </LayoutView>
    </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 som visas av komponenten Router i komponenten Routes (Routes.razor).
  • 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:en finns inom det interna bas-URI-utrymmet (appens bassökväg).

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.

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ärinlägg 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/'.'

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.

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.

Frågesträngar

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

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

Anteckning

Komponentparametrar kan bara ta emot frågeparametervärden i dirigerbara komponenter med ett @page-direktiv.

Endast dirigerbara komponenter tar direkt emot frågeparametrar för att undvika att omstörta informationsflödet uppifrån och ned och för att göra parameterbearbetningsordningen tydlig, både av ramverket och av appen. Den här designen undviker subtila buggar i appkoden som skrevs med en specifik parameterbearbetningsordning. Du kan definiera anpassade sammanhängande parametrar eller direkt tilldela till vanliga komponentparametrar för att skicka frågeparametervärden till icke-dirigerbara komponenter.

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; }

Precis som egenskaper för komponentparameter ([Parameter]) är [SupplyParameterFromQuery] egenskaper alltid public egenskaper i .NET 6/7. I .NET 8 eller senare kan [SupplyParameterFromQuery]-egenskaper markeras public eller private.

[Parameter]
[SupplyParameterFromQuery(Name = "{QUERY PARAMETER NAME}")]
public 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.

Anteckning

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; }
}

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 {
    [Parameter]
    [SupplyParameterFromQuery]
    public string? Filter { get; set; }

    [Parameter]
    [SupplyParameterFromQuery]
    public int? Page { get; set; }

    [Parameter]
    [SupplyParameterFromQuery(Name = "star")]
    public 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 ASP.NET Core BlazorSignalR-vägledning och Vägledning för hotreducering för interaktiv server-side rendering i ASP.NET Core Blazor.

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

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"));

Frågesträngen för en begäran hämtas från egenskapen NavigationManager.Uri:

@inject NavigationManager Navigation

...

var query = new Uri(Navigation.Uri).Query;

För att parsa en frågesträngs parametrar är en metod att använda URLSearchParams med JavaScript (JS) interop:

export createQueryString = (string queryString) => new URLSearchParams(queryString);

Mer information om JavaScript-isolering med JavaScript-moduler finns i Anropa JavaScript-funktioner från .NET-metoder i ASP.NET Core Blazor.

Hashad routning 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 hash-routning 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 HashedRouting komponent i appen.

HashedRouting.razor:

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

<PageTitle>Hashed routing</PageTitle>

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

<ul>
    <li>
        <a href="/hashed-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="/hashed-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");
    }
}

Användarinteraktion med <Navigating> innehåll

Om det uppstår en betydande fördröjning under navigeringen, såsom när lazy-loading assemblies i en Blazor WebAssembly-app eller för en långsam nätverksanslutning till en serverside-applikation Blazor, kan komponenten Router indikera för användaren att en sidövergång pågår.

Överst i komponenten som anger den Router komponenten lägger du till ett @using-direktiv för Microsoft.AspNetCore.Components.Routing-namnområdet:

@using Microsoft.AspNetCore.Components.Routing

Ange innehåll till parametern Navigating för visning under sidövergångshändelser.

I innehållet i routerelementet (<Router>...</Router>):

<Navigating>
    <p>Loading the requested page&hellip;</p>
</Navigating>

Ett exempel som använder egenskapen Navigating finns i Lazy load assemblies in ASP.NET Core Blazor WebAssembly.

Hantera asynkrona navigeringshändelser med OnNavigateAsync

Komponenten Router stöder en OnNavigateAsync funktion. OnNavigateAsync-hanteraren anropas när användaren:

  • Besöker en väg för första gången genom att navigera till den direkt i webbläsaren.
  • Navigerar till en ny väg med hjälp av en länk eller ett NavigationManager.NavigateTo anrop.
<Router AppAssembly="typeof(App).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext args)
    {
        ...
    }
}

<Router AppAssembly="typeof(Program).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext args)
    {
        ...
    }
}

Ett exempel som använder OnNavigateAsyncfinns i Lazy Load-sammansättningar i ASP.NET Core Blazor WebAssembly.

Vid förrendering på servern körs OnNavigateAsynctvå gånger:

  • En gång när den begärda slutpunktskomponenten ursprungligen återges statiskt.
  • En andra gång när webbläsaren återger slutpunktskomponenten.

För att förhindra att utvecklarkod i OnNavigateAsync körs två gånger kan komponenten Routes lagra NavigationContext för användning i OnAfterRender{Async} livscykelmetod, där firstRender kan kontrolleras. För mer information, se Prerendering med JavaScript interop.

För att förhindra att utvecklarkod i OnNavigateAsync körs två gånger kan App-komponenten lagra NavigationContext för användning i OnAfterRender{Async}, där firstRender kan kontrolleras. För mer information, se Prerendering med JavaScript interop.

Hantera annulleringar i OnNavigateAsync

Det objekt NavigationContext som skickas till OnNavigateAsync-återanropet innehåller en CancellationToken som anges när en ny händelse för navigation inträffar. Det OnNavigateAsync återanropet måste utlösas när den här annulleringstoken är inställd för att undvika att fortsätta köra OnNavigateAsync återanrop i en inaktuell navigering.

Om en användare navigerar till en slutpunkt men sedan omedelbart navigerar till en ny slutpunkt bör appen inte fortsätta att köra OnNavigateAsync återanrop för den första slutpunkten.

I följande exempel:

  • Annulleringstoken skickas i anropet till PostAsJsonAsync, vilket kan avbryta POST om användaren navigerar bort från /about slutpunkten.
  • Avbokningstoken sätts under en produktprefetch-åtgärd om användaren navigerar bort från slutpunkten /store.
@inject HttpClient Http
@inject ProductCatalog Products

<Router AppAssembly="typeof(App).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext context)
    {
        if (context.Path == "/about") 
        {
            var stats = new Stats { Page = "/about" };
            await Http.PostAsJsonAsync("api/visited", stats, 
                context.CancellationToken);
        }
        else if (context.Path == "/store")
        {
            var productIds = new[] { 345, 789, 135, 689 };

            foreach (var productId in productIds) 
            {
                context.CancellationToken.ThrowIfCancellationRequested();
                Products.Prefetch(productId);
            }
        }
    }
}

@inject HttpClient Http
@inject ProductCatalog Products

<Router AppAssembly="typeof(Program).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext context)
    {
        if (context.Path == "/about") 
        {
            var stats = new Stats { Page = "/about" };
            await Http.PostAsJsonAsync("api/visited", stats, 
                context.CancellationToken);
        }
        else if (context.Path == "/store")
        {
            var productIds = new[] { 345, 789, 135, 689 };

            foreach (var productId in productIds) 
            {
                context.CancellationToken.ThrowIfCancellationRequested();
                Products.Prefetch(productId);
            }
        }
    }
}

Anteckning

Att inte kasta om annulleringstoken i NavigationContext annulleras kan resultera i oönskad effekt, till exempel rendering av en komponent från en tidigare navigering.

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:

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.

Viktig

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).

Anteckning

Dokumentationslänkar till .NET-referenskällan läser vanligtvis in lagringsplatsens standardgren, vilket representerar den aktuella utvecklingen för nästa version av .NET. För att välja en tagg för en specifik version, använd rullgardinsmenyn Växla 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).

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.

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.

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

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 klassen active när användaren besöker en URL med ett component prefix (till exempel /component och /component/another-segment).

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>
}

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 ProductDetail-komponent med en vägmall på /product-detail (@page "/product-detail") i en webbläsare vid 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-skrivsätt är en namngivningskonvention som saknar blanksteg och skiljetecken och 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.

Om du vill ha ett exempel på föregående kod i en exempelapp som du kan köra lokalt hämtar du Blazor Web App eller Blazor WebAssembly exempelappen.

ASP.NET Core-slutpunktsroutningsintegrering

Det här avsnittet gäller för Blazor Web App som fungerar via en krets.

Det här avsnittet gäller för Blazor Server appar.

En Blazor Web App är integrerad i ASP.NET Core Endpoint Routing. En ASP.NET Core-app är konfigurerad för att acceptera inkommande anslutningar för interaktiva komponenter med MapRazorComponents i Program-filen. Standardrotkomponenten (den första komponenten som läses in) är komponenten App (App.razor):

app.MapRazorComponents<App>();

Blazor Server är integrerat i ASP.NET Core Endpoint Routing. En ASP.NET Core-app har konfigurerats för att acceptera inkommande anslutningar för interaktiva komponenter med MapBlazorHub i filen Program:

app.UseRouting();

app.MapBlazorHub();
app.MapFallbackToPage("/_Host");

Blazor Server är integrerat i ASP.NET Core Endpoint Routing. En ASP.NET Core-app är konfigurerad för att acceptera inkommande anslutningar för interaktiva komponenter med MapBlazorHub i Startup.Configure.

Den vanliga konfigurationen är att dirigera alla begäranden till en Razor sida, som fungerar som värd för serverdelen av Blazor Server-appen. Enligt konventionen heter värd-sidan vanligtvis _Host.cshtml i appens Pages mapp.

Den väg som anges i värdfilen kallas för en återställningsväg eftersom den fungerar med låg prioritet vid vägmatchning. Återställningsvägen används när andra vägar inte matchar. På så sätt kan appen använda andra kontrollanter och sidor utan att störa komponentroutning i Blazor Server-appen.

Information om hur du konfigurerar MapFallbackToPage för icke-root URL-servervärdskap finns i ASP.NET Core-appens basvägBlazor.