ASP.NET základní Blazor směrování a navigace

  • Článek

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Tento článek vysvětluje, jak spravovat Blazor směrování žádostí o aplikaci a jak pomocí NavLink komponenty vytvářet navigační odkazy.

Důležité

Příklady kódu v tomto článku ukazují metody volané na Navigation, což je vložené NavigationManager do tříd a komponent.

Statické a interaktivní směrování

Tato část platí pro Blazor Web Apps.

Pokud není předběžné vykreslování zakázané, Blazor směrovač (Router součást <Router> , in Routes.razor) provádí statické směrování do komponent během statického vykreslování na straně serveru (statické SSR). Tento typ směrování se nazývá statické směrování.

Pokud je komponentě Routes přiřazen interaktivní režim vykreslení, Blazor směrovač se po statickém směrování na serveru stane interaktivním. Tento typ směrování se nazývá interaktivní směrování.

Statické směrovače používají směrování koncových bodů a cestu požadavku HTTP k určení, která komponenta se má vykreslit. Když se směrovač stane interaktivním, použije adresu URL dokumentu (adresu URL v adresní řádku prohlížeče) k určení, která komponenta se má vykreslit. To znamená, že interaktivní směrovač může dynamicky změnit, která komponenta se vykreslí, pokud se adresa URL dokumentu dynamicky změní na jinou platnou interní adresu URL, a to bez provedení požadavku HTTP na načtení nového obsahu stránky.

Interaktivní směrování také zabraňuje předkreslování, protože nový obsah stránky není požadován ze serveru s normálním požadavkem na stránku. Další informace naleznete v tématu Prerender ASP.NET Základní Razor komponenty.

Šablony tras

Tato Router komponenta umožňuje směrování do Razor komponent a nachází se v komponentě aplikace Routes (Components/Routes.razor).

Komponenta Router umožňuje směrování do Razor komponent. Komponenta Router se používá v komponentě App (App.razor).

Razor Při kompilaci komponenty (.razor) s direktivou@page je vygenerovaná třída komponenty poskytována RouteAttribute určení šablony trasy komponenty.

Když se aplikace spustí, sestavení určené při kontrole směrovače AppAssembly za účelem shromáždění informací o trasách pro součásti aplikace, které mají RouteAttribute.

Za běhu komponenta RouteView :

  • Přijme z parametru RouteDataRouter spolu s libovolnými parametry trasy.
  • Vykreslí zadanou komponentu s rozložením, včetně dalších vnořených rozložení.

Volitelně můžete zadat DefaultLayout parametr s třídou rozložení pro komponenty, které nezadávají rozložení s direktivou@layout. Šablony projektů architektury Blazor určují komponentu MainLayout (MainLayout.razor) jako výchozí rozložení aplikace. Další informace o rozloženích najdete v tématu ASP.NET Rozložení jádraBlazor.

Komponenty podporují více šablon tras pomocí více @page direktiv. Následující příklad komponenty načte požadavky pro /blazor-route a /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"

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

Důležité

Aby se adresy URL správně přeložily, musí aplikace obsahovat <base> značku (umístění <head> obsahu) se základní cestou aplikace zadanou v atributu href . Další informace najdete v tématu Hostitel a nasazení ASP.NET Core Blazor.

Interaguje Router s řetězcovými hodnotami dotazu. Pokud chcete pracovat s řetězci dotazů, přečtěte si část Řetězce dotazu.

Jako alternativu k určení šablony trasy jako řetězcového literálu @page s direktivou je možné zadat šablony tras založené na konstantách pomocí direktivy@attribute.

V následujícím příkladu se direktiva @page v komponentě nahrazuje @attribute direktivou a šablonou trasy založenou na konstantě, Constants.CounterRoutekterá je nastavena jinde v aplikaci na "/counter":

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

Poznámka:

S vydáním ASP.NET Core 5.0.1 a pro všechny další verze 5.x komponenta Router zahrnuje parametr PreferExactMatches nastavený na @true. Další informace najdete v tématu Migrace z ASP.NET Core 3.1 na verzi 5.0.

Zaostření elementu na navigaci

Komponenta FocusOnNavigate nastaví fokus uživatelského rozhraní na prvek založený na selektoru CSS po přechodu z jedné stránky na jinou.

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

Když komponenta Router přejde na novou stránku, FocusOnNavigate nastaví komponenta fokus na záhlaví nejvyšší úrovně stránky (<h1>). Jedná se o běžnou strategii pro zajištění, že při použití čtečky obrazovky bude čtečka obrazovky oznamovat navigaci na stránce.

Poskytnutí vlastního obsahu, když se obsah nenajde

Tato Router komponenta umožňuje aplikaci zadat vlastní obsah, pokud se pro požadovanou trasu nenajde obsah.

Nastavte vlastní obsah pro Router parametr komponenty NotFound :

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

Libovolné položky jsou podporovány jako obsah parametru NotFound , například jiné interaktivní komponenty. Pokud chcete pro obsah použít výchozí rozloženíNotFound, podívejte se na ASP.NET rozložení CoreBlazor.

Důležité

BlazorSlužba Web Apps parametr (revize) nepoužíváNotFound<NotFound>...</NotFound>, ale parametr je podporovaný kvůli zpětné kompatibilitě, aby se zabránilo zásadní změně v architektuře. Kanál middlewaru Core na straně serveru ASP.NET zpracovává požadavky na serveru. Ke zpracování chybných požadavků použijte techniky na straně serveru. Další informace najdete v tématu ASP.NET režimy vykreslování coreBlazor.

Směrování na komponenty z více sestavení

Tato část platí pro Blazor Web Apps.

Pomocí parametru RouterAdditionalAssemblies komponenty a tvůrce AddAdditionalAssemblies konvencí koncového bodu můžete zjistit směrovatelné komponenty v dalších sestaveních. Následující pododdíly vysvětlují, kdy a jak používat jednotlivá rozhraní API.

Statické směrování

Chcete-li zjistit směrovatelné komponenty z dalších sestavení pro statické vykreslování na straně serveru (statické SSR), i když se směrovač později stane interaktivním pro interaktivní vykreslování, musí být sestavení zpřístupněna rozhraní Blazor . Volejte metodu AddAdditionalAssemblies s dalšími sestaveními zřetězenými do MapRazorComponents souboru projektu Program serveru.

Následující příklad obsahuje směrovatelné komponenty v BlazorSample.Client sestavení projektu pomocí souboru projektu _Imports.razor :

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

Poznámka:

Předchozí pokyny platí také ve scénářích knihovny tříd komponent. Další důležité pokyny pro knihovny tříd a statické služby SSR najdete v knihovnách tříd ASP.NET Core Razor (RCLs) se statickým vykreslováním na straně serveru (statické SSR).

Interaktivní směrování

Interaktivní režim vykreslení lze přiřadit komponentě Routes (Routes.razor), která směrovač Blazor stane interaktivním po statickém SSR a statickém směrování na serveru. Například <Routes @rendermode="InteractiveServer" /> přiřadí komponentě Routes interaktivní vykreslování na straně serveru (interaktivní SSR). Komponenta Router dědí z Routes komponenty interaktivní vykreslování na straně serveru (interaktivní SSR). Směrovač se po statickém směrování na serveru stane interaktivním.

Interní navigace pro interaktivní směrování nezahrnuje vyžádání nového obsahu stránky ze serveru. Proto u interních požadavků na stránku nedojde k předběžnému provedení. Další informace naleznete v tématu Prerender ASP.NET Základní Razor komponenty.

Pokud je komponenta Routes definovaná v serverovém projektu, AdditionalAssemblies měl by parametr Router komponenty obsahovat .Client sestavení projektu. To umožňuje, aby směrovač při interaktivním vykreslování fungoval správně.

V následujícím příkladu je komponenta Routes v projektu serveru a _Imports.razor soubor BlazorSample.Client projektu indikuje sestavení, které má vyhledat směrovatelné komponenty:

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

Další sestavení jsou kontrolována kromě sestavení určeného pro AppAssembly.

Poznámka:

Předchozí pokyny platí také ve scénářích knihovny tříd komponent.

Alternativně existují směrovatelné komponenty pouze v .Client projektu s globální interaktivní webAssembly nebo automatickým vykreslováním a Routes komponenta je definována v .Client projektu, nikoli v serverovém projektu. V tomto případě neexistují externí sestavení s směrovatelnými komponentami, takže není nutné zadat hodnotu pro AdditionalAssemblies.

Tato část se týká Blazor Server aplikací.

Pomocí parametru RouterAdditionalAssemblies komponenty a tvůrce AddAdditionalAssemblies konvencí koncového bodu můžete zjistit směrovatelné komponenty v dalších sestaveních.

V následujícím příkladu Component1 je směrovatelná komponenta definovaná v odkazované knihovně tříd komponent s názvem ComponentLibrary:

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

Další sestavení jsou kontrolována kromě sestavení určeného pro AppAssembly.

Parametry trasy

Směrovač používá parametry trasy k naplnění odpovídajících parametrů komponenty stejným názvem. Názvy parametrů trasy nerozlišují malá a velká písmena. V následujícím příkladu text parametr přiřadí hodnotu segmentu trasy vlastnosti komponenty Text . Při provedení požadavku na /route-parameter-1/amazingobsah se vykreslí jako 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}"

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

Podporují se volitelné parametry. V následujícím příkladu volitelný parametr text přiřadí vlastnosti Text komponenty hodnotu segmentu trasy. Pokud segment není k dispozici, je hodnota Text nastavena na fantastichodnotu .

Volitelné parametry nejsou podporované. V následujícím příkladu se použijí dvě @page direktivy . První direktiva umožňuje navigaci na komponentu bez parametru. Druhá direktiva přiřadí hodnotu parametru {text} trasy vlastnosti komponenty 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?}"

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

OnInitialized{Async} Pokud se metoda používá místo OnParametersSet, výchozí přiřazení Text vlastnosti fantastic k nedojde, pokud uživatel přejde v rámci stejné komponenty. Například tato situace nastane, když uživatel přejde z /route-parameter-2/amazing do /route-parameter-2. Vzhledem k tomu, že instance komponenty přetrvává a přijímá nové parametry, OnInitialized metoda se znovu nevyvolá.

Poznámka:

Parametry směrování nefungují s řetězcovými hodnotami dotazu. Pokud chcete pracovat s řetězci dotazů, přečtěte si část Řetězce dotazu.

Omezení trasy

Omezení trasy vynucuje porovnávání typů v segmentu trasy ke komponentě.

V následujícím příkladu trasa ke komponentě User odpovídá pouze v těchto případech:

  • Segment Id trasy se nachází v adrese URL požadavku.
  • Segment Id je celočíselnou (int) typ.

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

Poznámka:

Omezení směrování nefungují s řetězcovými hodnotami dotazu. Pokud chcete pracovat s řetězci dotazů, přečtěte si část Řetězce dotazu.

K dispozici jsou omezení trasy uvedená v následující tabulce. Další informace najdete v případě omezení tras, která odpovídají neutrální jazykové verzi, v upozornění pod tabulkou.

Omezení Příklad Příklady shod Invariantní
jazyková verze
shoda
bool {active:bool} true, FALSE No
datetime {dob:datetime} 2016-12-31, 2016-12-31 7:32pm Ano
decimal {price:decimal} 49.99, -1,000.01 Ano
double {weight:double} 1.234, -1,001.01e8 Ano
float {weight:float} 1.234, -1,001.01e8 Ano
guid {id:guid} CD2C1638-1638-72D5-1638-DEADBEEF1638, {CD2C1638-1638-72D5-1638-DEADBEEF1638} No
int {id:int} 123456789, -123456789 Ano
long {ticks:long} 123456789, -123456789 Ano

Upozorňující

Omezení směrování, která ověřují adresu URL a jsou převedena na typ CLR (například int ) DateTimevždy používají neutrální jazykovou verzi. Tato omezení předpokládají, že adresa URL není lokalizovatelná.

Omezení směrování také pracují s volitelnými parametry. V následujícím příkladu je povinný, Id ale Option jedná se o volitelný logický parametr trasy.

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

Směrování s adresami URL obsahujícími tečky

Výchozí šablona trasy na straně serveru předpokládá, že pokud poslední segment adresy URL požadavku obsahuje tečku (.), kterou vyžaduje soubor. Například relativní adresa URL /example/some.thing je interpretována směrovačem jako požadavek na soubor s názvem some.thing. Bez další konfigurace vrátí aplikace odpověď 404 – Nenalezena , pokud some.thing byla určena ke směrování do komponenty pomocí @page direktivy a some.thing je hodnotou parametru trasy. Pokud chcete použít trasu s jedním nebo více parametry, které obsahují tečku, musí aplikace nakonfigurovat trasu s vlastní šablonou.

Vezměte v úvahu následující Example komponentu, která může přijímat parametr trasy z posledního segmentu adresy URL.

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

Pokud chcete aplikaci hostovaného řešení povolit Server směrování požadavku tečkou v parametru param trasy, přidejte záložní šablonu trasy souboru s volitelným parametrem v Program souboru:Blazor WebAssembly

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

Pokud chcete nakonfigurovat aplikaci pro směrování Blazor Server požadavku tečkou v parametru param trasy, přidejte šablonu trasy náhradní stránky s volitelným parametrem v Program souboru:

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

Další informace najdete v tématu Směrování v ASP.NET Core.

Pokud chcete aplikaci hostovaného řešení povolit Server směrování požadavku tečkou v parametru param trasy, přidejte záložní šablonu trasy souboru s volitelným parametrem v Startup.Configure souboru .Blazor WebAssembly

Startup.cs:

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

Pokud chcete nakonfigurovat aplikaci pro směrování Blazor Server požadavku tečkou v parametru param trasy, přidejte náhradní šablonu trasy stránky s volitelným parametrem v Startup.Configuresouboru .

Startup.cs:

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

Další informace najdete v tématu Směrování v ASP.NET Core.

Parametry trasy pro zachytávání všech

V komponentách jsou podporovány všechny parametry trasy, které zachycují cesty přes více hranic složek.

Parametry trasy pro zachytávání jsou:

  • Název je pojmenovaný tak, aby odpovídal názvu segmentu trasy. Pojmenování nerozlišuje malá a velká písmena.
  • Typ string . Architektura neposkytuje automatické přetypování.
  • Na konci adresy URL.

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

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

Pro adresu URL /catch-all/this/is/a/test se šablonou /catch-all/{*pageRoute}trasy je hodnota PageRoute nastavena na this/is/a/testhodnotu .

Lomítka a segmenty zachycené cesty jsou dekódovány. Pro šablonu trasy adresy /catch-all/{*pageRoute}URL /catch-all/this/is/a%2Ftest%2A se vynese this/is/a/test*.

Pomocné rutiny URI a navigačního stavu

Slouží NavigationManager ke správě identifikátorů URI a navigace v kódu jazyka C#. NavigationManager poskytuje události a metody uvedené v následující tabulce.

Člen Popis
Uri Získá aktuální absolutní identifikátor URI.
BaseUri Získá základní identifikátor URI (s koncovým lomítkem), který lze předpendovat k relativním cestám URI k vytvoření absolutního identifikátoru URI. Obvykle BaseUri odpovídá href atributu elementu dokumentu <base> (umístění <head> obsahu).
NavigateTo Přejde na zadaný identifikátor URI. Pokud forceLoad je:false
  • Vylepšená navigace je k dispozici na aktuální adrese URL, Blazorje aktivována vylepšená navigace.
  • Blazor V opačném případě se pro požadovanou adresu URL znovu načte celá stránka.
Pokud forceLoad je:true
  • Směrování na straně klienta se vynechá.
  • Prohlížeč je nucen načíst novou stránku ze serveru bez ohledu na to, jestli je identifikátor URI obvykle zpracován interaktivním směrovačem na straně klienta.

Další informace najdete v části Rozšířená navigace a zpracování formulářů.

Pokud replace ano true, nahradí se aktuální identifikátor URI v historii prohlížeče místo vložení nového identifikátoru URI do zásobníku historie.
LocationChanged Událost, která se aktivuje při změně umístění navigace. Další informace najdete v části Změny polohy.
ToAbsoluteUri Převede relativní identifikátor URI na absolutní identifikátor URI.
ToBaseRelativePath Na základě základního identifikátoru URI aplikace převede absolutní identifikátor URI na identifikátor URI vzhledem k předponě základního identifikátoru URI. Příklad najdete v části Vytvoření identifikátoru URI vzhledem k oddílu předpony základního identifikátoru URI.
RegisterLocationChangingHandler Zaregistruje obslužnou rutinu pro zpracování příchozích navigačních událostí. Volání NavigateTo vždy vyvolá obslužnou rutinu.
GetUriWithQueryParameter Vrátí identifikátor URI vytvořený aktualizací NavigationManager.Uri s jedním přidaným, aktualizovaným nebo odebraným parametrem. Další informace najdete v části Řetězce dotazů.
Člen Popis
Uri Získá aktuální absolutní identifikátor URI.
BaseUri Získá základní identifikátor URI (s koncovým lomítkem), který lze předpendovat k relativním cestám URI k vytvoření absolutního identifikátoru URI. Obvykle BaseUri odpovídá href atributu elementu dokumentu <base> (umístění <head> obsahu).
NavigateTo Přejde na zadaný identifikátor URI. Pokud forceLoad je:true
  • Směrování na straně klienta se vynechá.
  • Prohlížeč je nucen načíst novou stránku ze serveru bez ohledu na to, jestli je identifikátor URI obvykle zpracován směrovačem na straně klienta.
Pokud replace ano true, nahradí se aktuální identifikátor URI v historii prohlížeče místo vložení nového identifikátoru URI do zásobníku historie.
LocationChanged Událost, která se aktivuje při změně umístění navigace. Další informace najdete v části Změny polohy.
ToAbsoluteUri Převede relativní identifikátor URI na absolutní identifikátor URI.
ToBaseRelativePath Na základě základního identifikátoru URI aplikace převede absolutní identifikátor URI na identifikátor URI vzhledem k předponě základního identifikátoru URI. Příklad najdete v části Vytvoření identifikátoru URI vzhledem k oddílu předpony základního identifikátoru URI.
RegisterLocationChangingHandler Zaregistruje obslužnou rutinu pro zpracování příchozích navigačních událostí. Volání NavigateTo vždy vyvolá obslužnou rutinu.
GetUriWithQueryParameter Vrátí identifikátor URI vytvořený aktualizací NavigationManager.Uri s jedním přidaným, aktualizovaným nebo odebraným parametrem. Další informace najdete v části Řetězce dotazů.
Člen Popis
Uri Získá aktuální absolutní identifikátor URI.
BaseUri Získá základní identifikátor URI (s koncovým lomítkem), který lze předpendovat k relativním cestám URI k vytvoření absolutního identifikátoru URI. Obvykle BaseUri odpovídá href atributu elementu dokumentu <base> (umístění <head> obsahu).
NavigateTo Přejde na zadaný identifikátor URI. Pokud forceLoad je:true
  • Směrování na straně klienta se vynechá.
  • Prohlížeč je nucen načíst novou stránku ze serveru bez ohledu na to, jestli je identifikátor URI obvykle zpracován směrovačem na straně klienta.
Pokud replace ano true, nahradí se aktuální identifikátor URI v historii prohlížeče místo vložení nového identifikátoru URI do zásobníku historie.
LocationChanged Událost, která se aktivuje při změně umístění navigace. Další informace najdete v části Změny polohy.
ToAbsoluteUri Převede relativní identifikátor URI na absolutní identifikátor URI.
ToBaseRelativePath Na základě základního identifikátoru URI aplikace převede absolutní identifikátor URI na identifikátor URI vzhledem k předponě základního identifikátoru URI. Příklad najdete v části Vytvoření identifikátoru URI vzhledem k oddílu předpony základního identifikátoru URI.
GetUriWithQueryParameter Vrátí identifikátor URI vytvořený aktualizací NavigationManager.Uri s jedním přidaným, aktualizovaným nebo odebraným parametrem. Další informace najdete v části Řetězce dotazů.
Člen Popis
Uri Získá aktuální absolutní identifikátor URI.
BaseUri Získá základní identifikátor URI (s koncovým lomítkem), který lze předpendovat k relativním cestám URI k vytvoření absolutního identifikátoru URI. Obvykle BaseUri odpovídá href atributu elementu dokumentu <base> (umístění <head> obsahu).
NavigateTo Přejde na zadaný identifikátor URI. Pokud forceLoad je:true
  • Směrování na straně klienta se vynechá.
  • Prohlížeč je nucen načíst novou stránku ze serveru bez ohledu na to, jestli je identifikátor URI obvykle zpracován směrovačem na straně klienta.
LocationChanged Událost, která se aktivuje při změně umístění navigace.
ToAbsoluteUri Převede relativní identifikátor URI na absolutní identifikátor URI.
ToBaseRelativePath Na základě základního identifikátoru URI aplikace převede absolutní identifikátor URI na identifikátor URI vzhledem k předponě základního identifikátoru URI. Příklad najdete v části Vytvoření identifikátoru URI vzhledem k oddílu předpony základního identifikátoru URI.

Změny umístění

LocationChanged Pro událost LocationChangedEventArgs poskytuje následující informace o navigačních událostech:

Následující komponenta:

  • Při výběru tlačítka přejde na komponentu aplikace Counter (Counter.razor) pomocí NavigateTo.
  • Zpracovává změněnou událost umístění přihlášením k odběru NavigationManager.LocationChanged.

    • Metoda HandleLocationChanged není vyvolána, pokud Dispose je volána architekturou. Zrušením použití metody lze uvolnění paměti komponenty.

    • Implementace protokolovacího nástroje zaznamená při výběru tlačítka následující informace:

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

Další informace o odstranění součástí najdete v tématu ASP.NET životní Razor cyklus základních komponent.

Vylepšená navigace a zpracování formulářů

Tato část platí pro Blazor Web Apps.

Blazor Služba Web Apps dokáže směrovat dva typy směrování pro navigaci na stránce a žádosti o zpracování formulářů:

  • Normální navigace (navigace napříč dokumenty): Pro adresu URL požadavku se aktivuje opětovné načtení celé stránky.
  • Vylepšená navigace (navigace ve stejném dokumentu): Blazor zachytí požadavek a místo toho žádost provede fetch . Blazor pak opraví obsah odpovědi do modelu DOM stránky. BlazorVylepšená navigace a zpracování formulářů se vyhněte nutnosti opětovného načítání na celou stránku a zachovává více stavu stránky, takže stránky se načítají rychleji, obvykle bez ztráty pozice posouvání uživatele na stránce.

Vylepšená navigace je dostupná v případech:

  • Skript Blazor webové aplikace (blazor.web.js) se používá, ne Blazor Server skript (blazor.server.js) ani Blazor WebAssembly skript (blazor.webassembly.js).
  • Tato funkce není explicitně zakázaná.
  • Cílová adresa URL je v prostoru interního základního identifikátoru URI (základní cesta aplikace).

Pokud je povolené směrování na straně serveru a vylepšená navigace, budou obslužné rutiny pro změnu umístění vyvolány pouze pro programovou navigaci iniciovanou z interaktivního modulu runtime. V budoucích verzích můžou další typy navigace, například sledování odkazu, vyvolat také obslužné rutiny pro změnu umístění.

Když dojde k rozšířené navigaci, LocationChanged obslužné rutiny událostí zaregistrované v interaktivním serveru a modulu runtime WebAssembly se obvykle vyvolávají. Existují případy, kdy obslužné rutiny pro změnu polohy nemusí zachytit vylepšenou navigaci. Uživatel může například přepnout na jinou stránku, než bude k dispozici interaktivní modul runtime. Proto je důležité, aby logika aplikace nespoléhala na vyvolání obslužné rutiny změny umístění, protože neexistuje žádná záruka provádění obslužné rutiny.

Při volání NavigateTo:

  • Pokud forceLoad je false, což je výchozí:
    • Vylepšená navigace je k dispozici na aktuální adrese URL, Blazorje aktivována vylepšená navigace.
    • Blazor V opačném případě se pro požadovanou adresu URL znovu načte celá stránka.
  • Pokud forceLoad je : Blazortrueprovede opětovné načtení celé stránky pro požadovanou adresu URL bez ohledu na to, jestli je vylepšená navigace k dispozici, nebo ne.

Aktuální stránku můžete aktualizovat voláním NavigationManager.Refresh(bool forceLoad = false), která vždy provádí vylepšenou navigaci, pokud je k dispozici. Pokud není vylepšená navigace dostupná, Blazor provede opětovné načtení celé stránky.

Navigation.Refresh();

Předejte true parametru forceLoad , aby se zajistilo, že se vždy provede opětovné načítání celé stránky, i když je k dispozici vylepšená navigace:

Navigation.Refresh(true);

Vylepšená navigace je ve výchozím nastavení povolená, ale lze ji řídit hierarchicky a na základě odkazu pomocí atributu data-enhance-nav HTML.

Následující příklady zakazují rozšířenou navigaci:

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

Pokud je cílem jinýBlazor koncový bod, rozšířená navigace se nepoužije a JavaScript na straně klienta se pokusí načíst celou stránku. Tím se zajistí, že rozhraní nebude nejasné o externích stránkách, které by se neměly opravovat na existující stránku.

Pokud chcete povolit rozšířené zpracování formulářů, přidejte Enhance parametr do EditForm formulářů nebo data-enhance atributu do formulářů HTML (<form>):

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

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

Vylepšené zpracování formulářů není hierarchické a neprovádí tok do podřízených formulářů:

Rozšířenou navigaci u nadřazeného prvku formuláře nelze nastavit, aby byla pro formulář rozšířená navigace.

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

Vylepšené příspěvky formulářů fungují jenom s Blazor koncovými body. Publikování rozšířeného formuláře do jinéhoBlazor koncového bodu způsobí chybu.

Zakázání rozšířené navigace:

  • Pro parametr odeberte EditFormEnhance z elementu formuláře parametr (nebo ho nastavte na false: Enhance="false").
  • Pro HTML <form>odeberte data-enhance atribut z elementu formuláře (nebo ho nastavte na false: data-enhance="false").

BlazorVylepšená navigace a předávání formulářů můžou vrátit dynamické změny modelu DOM, pokud aktualizovaný obsah není součástí vykreslování serveru. Chcete-li zachovat obsah elementu, použijte data-permanent atribut.

V následujícím příkladu se obsah elementu <div> dynamicky aktualizuje skriptem při načtení stránky:

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

Po Blazor spuštění klienta můžete událost použít enhancedload k naslouchání rozšířeným aktualizacím stránky. To umožňuje opětovné použití změn v systému DOM, které mohly být vráceny vylepšenou aktualizací stránky.

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

Pokud chcete zakázat rozšířenou navigaci a zpracování formulářů globálně, přečtěte si informace o spuštění ASP.NET CoreBlazor.

Vylepšená navigace se statickým vykreslováním na straně serveru (static SSR) vyžaduje při načítání JavaScriptu zvláštní pozornost. Další informace najdete v tématu ASP.NET Core Blazor JavaScript se statickým vykreslováním na straně serveru (statické SSR).

Vytvoření identifikátoru URI vzhledem k předponě základního identifikátoru URI

Na základě základního identifikátoru URI ToBaseRelativePath aplikace převede absolutní identifikátor URI na identifikátor URI vzhledem k předponě základního identifikátoru URI.

Představte si následující příklad:

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

Pokud je https://localhost:8000základní identifikátor URI aplikace, získáte následující výsledky:

  • Předání https://localhost:8000/segment výsledků ve výsledku baseRelativePath .segmentinputURI
  • Předání https://localhost:8000/segment1/segment2 výsledků ve výsledku baseRelativePath .segment1/segment2inputURI

Pokud základní identifikátor URI aplikace neodpovídá základnímu identifikátoru inputURIURI , ArgumentException vyvolá se.

inputURI Předání https://localhost:8001/segment vede k následující výjimce:

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

Rozhraní NavigationManager API historie prohlížeče používá k udržování stavu historie navigace přidruženého ke každé změně umístění provedené aplikací. Udržování stavu historie je zvlášť užitečné ve scénářích externího přesměrování, například při ověřování uživatelů s externími zprostředkovateli identit. Další informace najdete v části Možnosti navigace.

Předat NavigationOptions do NavigateTo řízení následující chování:

  • ForceLoad: Vynechat směrování na straně klienta a vynutit, aby prohlížeč načetl novou stránku ze serveru, ať už je identifikátor URI zpracován směrovačem na straně klienta. Výchozí hodnota je false.
  • ReplaceHistoryEntry: Nahraďte aktuální položku v zásobníku historie. Pokud false, připojte novou položku do zásobníku historie. Výchozí hodnota je false.
  • HistoryEntryState: Získá nebo nastaví stav pro připojení k položce historie.
Navigation.NavigateTo("/path", new NavigationOptions
{
    HistoryEntryState = "Navigation state"
});

Další informace o získání stavu přidruženého k položce historie cíle při zpracování změn umístění najdete v části Popisovač/zabránit změnám umístění.

Řetězce dotazů

Pomocí atributu [SupplyParameterFromQuery] určete, že parametr komponenty pochází z řetězce dotazu.

[SupplyParameterFromQuery] Atribut s atributem[Parameter] slouží k určení, že parametr komponenty směrovatelné komponenty pochází z řetězce dotazu.

Poznámka:

Parametry komponenty mohou přijímat pouze hodnoty parametrů dotazu v směrovatelných komponentách pomocí direktivy @page .

Pouze směrovatelné komponenty přímo přijímají parametry dotazu, aby se zabránilo převrácení toku informací shora dolů a aby pořadí zpracování parametrů bylo jasné, a to jak podle architektury, tak aplikace. Tento návrh zabraňuje drobným chybám v kódu aplikace, který byl napsán za předpokladu konkrétního pořadí zpracování parametrů. Můžete definovat vlastní kaskádové parametry nebo přímo přiřadit k běžným parametrům komponent, abyste mohli předávat hodnoty parametrů dotazu nesměrovatelným komponentám.

Parametry komponenty zadané z řetězce dotazu podporují následující typy:

  • bool, DateTime, , decimal, double, Guidfloat, int, longstring.
  • Varianty s možnou hodnotou null předchozích typů
  • Pole předchozích typů, bez ohledu na to, jestli mají hodnotu null, nebo ne.

Správné formátování invariantní jazykové verze se použije pro daný typ (CultureInfo.InvariantCulture).

Zadejte vlastnost atributu [SupplyParameterFromQuery]Name pro použití názvu parametru dotazu, který se liší od názvu parametru komponenty. V následujícím příkladu je {COMPONENT PARAMETER NAME}název jazyka C# parametru komponenty . Pro zástupný symbol se zadává jiný název parametru {QUERY PARAMETER NAME} dotazu:

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

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

V následujícím příkladu s adresou URL /search?filter=scifi%20stars&page=3&star=LeVar%20Burton&star=Gary%20Oldman:

  • Vlastnost Filter se přeloží na scifi stars.
  • Vlastnost Page se přeloží na 3.
  • Pole Stars se vyplní z parametrů dotazu s názvem star (Name = "star") a přeloží na LeVar Burton a Gary Oldman.

Poznámka:

Parametry řetězce dotazu v následující směrovatelné komponentě stránky fungují také v nesměrovatelné komponentě bez direktivy @page (například Search.razor pro sdílenou Search komponentu použitou v jiných součástech).

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

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

    [SupplyParameterFromQuery(Name = "star")]
    public 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; }
}

Slouží NavigationManager.GetUriWithQueryParameter k přidání, změně nebo odebrání jednoho nebo více parametrů dotazu na aktuální adrese URL:

@inject NavigationManager Navigation

...

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

Pro předchozí příklad:

  • Zástupný {NAME} symbol určuje název parametru dotazu. Zástupný {VALUE} symbol určuje hodnotu jako podporovaný typ. Podporované typy jsou uvedeny dále v této části.
  • Řetězec se vrátí se stejnou aktuální adresou URL s jedním parametrem:
    • Přidání, pokud název parametru dotazu v aktuální adrese URL neexistuje.
    • Aktualizace na hodnotu zadanou v případě, že parametr dotazu existuje v aktuální adrese URL.
    • Byla odebrána, pokud je typ poskytnuté hodnoty null a hodnota je null.
  • Správné formátování invariantní jazykové verze se použije pro daný typ (CultureInfo.InvariantCulture).
  • Název a hodnota parametru dotazu jsou kódované adresou URL.
  • Všechny hodnoty s odpovídajícím názvem parametru dotazu se nahradí, pokud existuje více instancí typu.

Volání NavigationManager.GetUriWithQueryParameters pro vytvoření identifikátoru URI vytvořeného z Uri více parametrů přidaných, aktualizovaných nebo odebraných. Pro každou hodnotu architektura používá value?.GetType() k určení typu modulu runtime pro každý parametr dotazu a vybere správné formátování invariantní jazykové verze. Architektura vyvolá chybu pro nepodporované typy.

@inject NavigationManager Navigation

...

Navigation.GetUriWithQueryParameters({PARAMETERS})

Zástupný {PARAMETERS} symbol je .IReadOnlyDictionary<string, object>

Předejte řetězec URI, který GetUriWithQueryParameters vygeneruje nový identifikátor URI ze zadaného identifikátoru URI s více přidanými, aktualizovanými nebo odebranými parametry. Pro každou hodnotu architektura používá value?.GetType() k určení typu modulu runtime pro každý parametr dotazu a vybere správné formátování invariantní jazykové verze. Architektura vyvolá chybu pro nepodporované typy. Podporované typy jsou uvedeny dále v této části.

@inject NavigationManager Navigation

...

Navigation.GetUriWithQueryParameters("{URI}", {PARAMETERS})
  • Zástupný {URI} symbol je identifikátor URI s řetězcem dotazu nebo bez.
  • Zástupný {PARAMETERS} symbol je .IReadOnlyDictionary<string, object>

Podporované typy jsou stejné jako podporované typy omezení trasy:

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

Mezi podporované typy patří:

  • Varianty s možnou hodnotou null předchozích typů
  • Pole předchozích typů, bez ohledu na to, jestli mají hodnotu null, nebo ne.

Upozorňující

Díky kompresi, která je ve výchozím nastavení povolená, se vyhněte vytváření zabezpečených (ověřených/autorizovaných) interaktivních komponent na straně serveru, které vykreslují data z nedůvěryhodných zdrojů. Mezi nedůvěryhodné zdroje patří parametry směrování, řetězce dotazů, data z JS interoperability a jakýkoli jiný zdroj dat, který může uživatel třetí strany řídit (databáze, externí služby). Další informace najdete v pokynech k ASP.NET CoreSignalRBlazora pokyny ke zmírnění hrozeb pro interaktivní vykreslování na straně serveru ASP.NET Core.Blazor

Nahrazení hodnoty parametru dotazu, pokud parametr existuje

Navigation.GetUriWithQueryParameter("full name", "Morena Baccarin")
Aktuální adresa URL Vygenerovaná adresa 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

Připojení parametru dotazu a hodnoty, pokud parametr neexistuje

Navigation.GetUriWithQueryParameter("name", "Morena Baccarin")
Aktuální adresa URL Vygenerovaná adresa 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

Odebrání parametru dotazu, pokud je hodnota parametru null

Navigation.GetUriWithQueryParameter("full name", (string)null)
Aktuální adresa URL Vygenerovaná adresa 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/

Přidání, aktualizace a odebrání parametrů dotazu

V následujícím příkladu:

  • name pokud je k dispozici, odebere se.
  • age je přidána s hodnotou 25 (int), pokud není k dispozici. Pokud je k dispozici, age aktualizuje se na hodnotu 25.
  • eye color je přidána nebo aktualizována na hodnotu green.
Navigation.GetUriWithQueryParameters(
    new Dictionary<string, object?>
    {
        ["name"] = null,
        ["age"] = (int?)25,
        ["eye color"] = "green"
    })
Aktuální adresa URL Vygenerovaná adresa 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

Podpora výčtových hodnot

V následujícím příkladu:

  • full name je přidána nebo aktualizována do Morena Baccarinjedné hodnoty.
  • pingparametry jsou přidány nebo nahrazeny 35, 1687 a 240.
Navigation.GetUriWithQueryParameters(
    new Dictionary<string, object?>
    {
        ["full name"] = "Morena Baccarin",
        ["ping"] = new int?[] { 35, 16, null, 87, 240 }
    })
Aktuální adresa URL Vygenerovaná adresa 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

K navigaci s přidaným nebo upraveným řetězcem dotazu předejte vygenerovanou adresu URL NavigateTo.

Následující příklad volání:

  • GetUriWithQueryParameter přidání nebo nahrazení parametru name dotazu pomocí hodnoty Morena Baccarin.
  • Volání NavigateTo pro aktivaci navigace na novou adresu URL
Navigation.NavigateTo(
    Navigation.GetUriWithQueryParameter("name", "Morena Baccarin"));

Řetězec dotazu požadavku se získá z NavigationManager.Uri vlastnosti:

@inject NavigationManager Navigation

...

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

Pokud chcete parsovat parametry řetězce dotazu, jedním z přístupů je použití URLSearchParams s interoperabilitou JavaScriptu (JS):

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

Další informace o izolaci JavaScriptu pomocí modulů JavaScriptu najdete v tématu Volání funkcí JavaScriptu z metod .NET v ASP.NET Core Blazor.

Směrování s hodnotou hash na pojmenované elementy

Pomocí následujících přístupů s odkazem na element přejděte na pojmenovaný element s odkazem na hodnotu hash (#). Trasy k prvkům v rámci komponenty a trasy k prvkům v externích komponentách používají kořenové relativní cesty. Počáteční lomítko (/) je volitelné.

Příklady pro každý z následujících přístupů ukazují navigaci na prvek s prvkem idtargetElement v komponentě Counter :

  • Ukotvení elementu href(<a>) s :

    <a href="/counter#targetElement">

  • NavLink součást s href:

    <NavLink href="/counter#targetElement">

  • NavigationManager.NavigateTo předání relativní adresy URL:

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

Následující příklad ukazuje hashované směrování na pojmenované nadpisy H2 v rámci komponenty a externí komponenty.

V komponentách Home (Home.razor) a Counter (Counter.razor) umístěte následující značky na konec existující značky komponenty, které slouží jako cíle navigace. Vytvoří <div> umělou svislou mezeru, která demonstruje chování při posouvání v prohlížeči:

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

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

Do aplikace přidejte následující HashedRouting komponentu.

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

Interakce uživatelů s obsahem <Navigating>

Pokud během navigace dochází k významnému zpoždění, například při opožděné načítání sestavení v Blazor WebAssembly aplikaci nebo pomalého síťového připojení k Blazor aplikaci na straně serveru, může tato komponenta označit uživateli, Router že dochází k přechodu stránky.

V horní části komponenty, která určuje komponentu Router , přidejte direktivu @usingMicrosoft.AspNetCore.Components.Routing pro obor názvů:

@using Microsoft.AspNetCore.Components.Routing

Zadejte obsah parametru Navigating pro zobrazení během událostí přechodu stránky.

Obsah elementu směrovače (<Router>...</Router>):

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

Příklad, který používá Navigating vlastnost, viz Lazy načtení sestavení v ASP.NET Core Blazor WebAssembly.

Zpracování asynchronních navigačních událostí pomocí OnNavigateAsync

Komponenta Router podporuje OnNavigateAsync funkci. Obslužná rutina OnNavigateAsync se vyvolá, když uživatel:

  • Poprvé navštíví trasu tak, že na ni přejdete přímo v prohlížeči.
  • Přejde na novou trasu pomocí odkazu nebo NavigationManager.NavigateTo vyvolání.
<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)
    {
        ...
    }
}

Příklad, který používá OnNavigateAsync, viz Lazy načtení sestavení v ASP.NET Core Blazor WebAssembly.

Při předběžném vyřazování na serveru OnNavigateAsync se spustí dvakrát:

  • Jakmile se požadovaná součást koncového bodu zpočátku vykreslí staticky.
  • Podruhé, když prohlížeč vykreslí komponentu koncového bodu.

Pokud chcete zabránit tomu, aby se kód OnNavigateAsync vývojáře spouštěl dvakrát, Routes může komponenta NavigationContext uložit pro použití v OnAfterRender{Async}umístění , kde firstRender se dá zkontrolovat. Další informace naleznete v tématu Prerendering with JavaScript interop in the Blazor Lifecycle article.

Pokud chcete zabránit tomu, aby se kód OnNavigateAsync vývojáře spouštěl dvakrát, App může komponenta NavigationContext uložit pro použití v OnAfterRender{Async}umístění , kde firstRender se dá zkontrolovat. Další informace naleznete v tématu Prerendering with JavaScript interop in the Blazor Lifecycle article.

Zpracování zrušení v OnNavigateAsync

Objekt NavigationContext předaný zpětnému OnNavigateAsync volání obsahuje nastavenou CancellationToken , když dojde k nové události navigace. Zpětné OnNavigateAsync volání musí vyvolat, pokud je tento token zrušení nastavený, aby se zabránilo pokračování ve spouštění zpětného OnNavigateAsync volání v zastaralé navigaci.

Pokud uživatel přejde na koncový bod, ale okamžitě přejde na nový koncový bod, aplikace by neměla pokračovat ve spouštění zpětného OnNavigateAsync volání prvního koncového bodu.

V následujícím příkladu:

  • Token zrušení se předá ve volání PostAsJsonAsync, což může zrušit POST, pokud uživatel přejde mimo /about koncový bod.
  • Token zrušení se nastaví během operace předběžného /store načtení produktu, pokud uživatel přejde mimo koncový bod.
@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);
            }
        }
    }
}

Poznámka:

Pokud dojde ke zrušení tokenu NavigationContext zrušení, může dojít k neočekávanému chování, jako je například vykreslení komponenty z předchozí navigace.

Zpracování nebo zabránění změnám umístění

RegisterLocationChangingHandler zaregistruje obslužnou rutinu pro zpracování příchozích navigačních událostí. Kontext obslužné rutiny poskytovaný následujícími vlastnostmi LocationChangingContext :

Komponenta může ve svých OnAfterRender metodách OnAfterRenderAsynczaregistrovat několik obslužných rutin pro změnu umístění. Navigace vyvolá všechny obslužné rutiny pro změnu umístění zaregistrované v celé aplikaci (napříč více komponentami) a všechny interní navigace je spustí paralelně. Kromě NavigateTo obslužných rutin jsou vyvolány:

  • Při výběru interních odkazů, což jsou odkazy odkazující na adresy URL v základní cestě aplikace.
  • Při navigaci pomocí tlačítek vpřed a zpět v prohlížeči.

Obslužné rutiny se spouští jenom pro interní navigaci v aplikaci. Pokud uživatel vybere odkaz, který přejde na jiný web nebo změní adresní řádek na jiný web ručně, nespustí se obslužné rutiny pro změnu umístění.

Implementujte a odstraňte IDisposable registrované obslužné rutiny k jejich zrušení registrace. Další informace najdete v tématu Životní cyklus komponent ASP.NET Core Razor.

Důležité

Při zpracování změn umístění se nepokoušejte spouštět úlohy čištění DOM prostřednictvím interoperability JavaScriptu (JS). MutationObserver Použijte vzor v JS klientovi. Další informace najdete v tématu ASP.NET Interoperabilita Core Blazor JavaScriptu (JSinteroperabilita).

V následujícím příkladu je obslužná rutina změny umístění registrována pro události navigace.

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

Vzhledem k tomu, že interní navigaci je možné zrušit asynchronně, může dojít k několika překrývajícím se voláním registrovaných obslužných rutin. Například více volání obslužné rutiny může nastat, když uživatel rychle vybere tlačítko Zpět na stránce nebo vybere více odkazů před spuštěním navigace. Následuje souhrn asynchronní navigační logiky:

  • Pokud jsou zaregistrované nějaké obslužné rutiny pro změnu umístění, vrátí se veškerá navigace na začátku a pak se přehraje, pokud se navigace nezruší.
  • Pokud se provádějí překrývající se navigační požadavky, nejnovější požadavek vždy zruší dřívější požadavky, což znamená následující:
    • Aplikace může zacházet s několika výběry tlačítek zpět a vpřed jako s jedním výběrem.
    • Pokud uživatel vybere více odkazů před dokončením navigace, určuje poslední vybraný odkaz navigaci.

Další informace o předávání NavigationOptionsNavigateTo položkám a stavu zásobníku historie navigace najdete v části Možnosti navigace.

Další příklad kódu naleznete NavigationManagerComponent v BasicTestApp (dotnet/aspnetcore referenční zdroj).

Poznámka:

Odkazy na dokumentaci k referenčnímu zdroji .NET obvykle načítají výchozí větev úložiště, která představuje aktuální vývoj pro příští verzi .NET. Pokud chcete vybrat značku pro konkrétní verzi, použijte rozevírací seznam pro přepnutí větví nebo značek. Další informace najdete v tématu Jak vybrat značku verze zdrojového kódu ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Komponenta NavigationLock zachytí navigační události, pokud se vykresluje, a efektivně "uzamkne" všechny dané navigace, dokud se nezruší rozhodnutí o pokračování nebo zrušení. Slouží NavigationLock k určení rozsahu navigačního průsečíku na dobu životnosti komponenty.

NavigationLock Parametry:

  • ConfirmExternalNavigation nastaví dialogové okno prohlížeče, které uživatele vyzve k potvrzení nebo zrušení externí navigace. Výchozí hodnota je false. Zobrazení potvrzovacího dialogového okna vyžaduje počáteční interakci uživatele se stránkou před aktivací externí navigace s adresou URL v adresovém řádku prohlížeče. Další informace o požadavku na interakci najdete v tématu Okno: beforeunload událost (dokumentace k MDN).
  • OnBeforeInternalNavigation nastaví zpětné volání pro interní navigační události.

V následující komponentě NavLock:

  • Než bude navigace https://www.microsoft.com úspěšná, musí uživatel potvrdit pokus o sledování odkazu na web společnosti Microsoft.
  • PreventNavigationje volána, aby se zabránilo výskytu navigace, pokud uživatel odmítne potvrdit navigaci prostřednictvím volání zprostředkovatele komunikace JavaScriptu (JS), které vytvoříJSconfirm dialogové okno.

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

Další příklad kódu naleznete v ConfigurableNavigationLock komponentě BasicTestApp (dotnet/aspnetcore referenční zdroj).

NavLink Při vytváření navigačních odkazů použijte součást místo elementů hypertextového odkazu HTML (<a>). Komponenta NavLink se chová jako <a> prvek, s výjimkou toho, že přepíná active třídu CSS na základě toho, jestli odpovídá href aktuální adrese URL. Třída active pomáhá uživateli pochopit, která stránka je aktivní stránkou mezi zobrazenými navigačními odkazy. Volitelně můžete přiřadit název třídy CSS k NavLink.ActiveClass použití vlastní třídy CSS na vykreslený odkaz, pokud aktuální trasa odpovídá href.

K atributu elementu Match<NavLink> můžete přiřadit dvě NavLinkMatch možnosti:

V předchozím příkladu odpovídá HomeNavLinkhref="" domovské adrese URL a přijímá active třídu CSS pouze ve výchozí základní cestě aplikace ()./ NavLink Druhá obdrží active třídu, když uživatel navštíví libovolnou adresu URL s předponou component (například /component a /component/another-segment).

Další NavLink atributy komponent se předávají do vykreslené značky ukotvení. V následujícím příkladu NavLink komponenta target obsahuje atribut:

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

Zobrazí se následující kód HTML:

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

Upozorňující

Vzhledem k tomu, jak Blazor vykresluje podřízený obsah, vyžaduje vykreslování NavLink součástí uvnitř for smyčky místní indexovou proměnnou, pokud se v obsahu komponenty (podřízené) používá NavLink proměnná inkrementační smyčky:

@for (int c = 0; c < 10; c++)
{
    var current = c;
    <li ...>
        <NavLink ... href="product-number/@c">
            <span ...></span> Product #@current
        </NavLink>
    </li>
}

Použití proměnné indexu v tomto scénáři je požadavek na libovolnou podřízenou komponentu, která používá proměnnou smyčky v podřízeného obsahu, nejen komponentu NavLink .

Alternativně použijte smyčku foreach s Enumerable.Range:

@foreach (var c in Enumerable.Range(0,10))
{
    <li ...>
        <NavLink ... href="product-number/@c">
            <span ...></span> Product #@c
        </NavLink>
    </li>
}

NavLink položky komponent lze dynamicky vytvářet z komponent aplikace prostřednictvím reflexe. Následující příklad ukazuje obecný přístup k dalšímu přizpůsobení.

Pro následující ukázku se pro komponenty aplikace používá konzistentní standardní zásady vytváření názvů:

  • Názvy souborů komponent směrovatelné používají například písmena Pascal† například Pages/ProductDetail.razor.
  • Cesty k souborům komponent směrovatelné odpovídají jejich adresám URL v případě kebabu s pomlčkami, které se zobrazují mezi slovy v šabloně trasy komponenty. Například komponenta ProductDetail s šablonou trasy /product-detail (@page "/product-detail") je přístupná v prohlížeči na relativní adrese URL /product-detail.

† PascalCase (UpperCamelCase) je konvence vytváření názvů bez mezer a interpunkce a s velkým počátečním písmenem každého slova, včetně prvního.
{Kebab case je konvence pojmenování bez mezer a interpunkce, která používá malá písmena a pomlčky mezi slovy.

Razor V kódu NavMenu komponenty (NavMenu.razor) pod výchozí Home stránkou NavLink se komponenty přidají z kolekce:

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

Metoda GetRoutableComponents v @code bloku:

public IEnumerable<string> GetRoutableComponents()
{
    return 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);
}

Předchozí příklad neobsahuje následující stránky v vykresleného seznamu komponent:

  • Home page: Stránka je uvedena odděleně od automaticky generovaných odkazů, protože by se měla zobrazit v horní části seznamu a nastavit Match parametr.
  • Error page: Chybová stránka se přechází jenom podle architektury a neměla by být uvedená.

Příklad předchozího kódu v ukázkové aplikaci, kterou můžete spustit místně, získáte Blazor webovou aplikaci nebo Blazor WebAssembly ukázkovou aplikaci.

integrace směrování koncových bodů ASP.NET Core

Tato část se vztahuje na Blazor webové aplikace provozující přes okruh.

Tato část se týká Blazor Server aplikací.

Blazor Webová aplikace je integrovaná do směrování základního koncového bodu ASP.NET. Aplikace ASP.NET Core je nakonfigurovaná tak, aby přijímala příchozí připojení pro interaktivní komponenty v MapRazorComponentsProgram souboru. Výchozí kořenová komponenta (první načtená komponenta) je komponenta App (App.razor):

app.MapRazorComponents<App>();

Blazor Server je integrovaný do směrování základního koncového bodu ASP.NET. Aplikace ASP.NET Core je nakonfigurovaná tak, aby přijímala příchozí připojení pro interaktivní komponenty v MapBlazorHubProgram souboru:

app.UseRouting();

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

Blazor Server je integrovaný do směrování základního koncového bodu ASP.NET. Aplikace ASP.NET Core je nakonfigurovaná tak, aby přijímala příchozí připojení pro interaktivní komponenty s MapBlazorHub in Startup.Configure.

Typická konfigurace je směrovat všechny požadavky na Razor stránku, která funguje jako hostitel pro serverovou část Blazor Server aplikace. Podle konvence se hostitelská stránka obvykle jmenuje _Host.cshtml ve Pages složce aplikace.

Trasa zadaná v souboru hostitele se nazývá náhradní trasa , protože v porovnání tras funguje s nízkou prioritou. Náhradní trasa se používá, když se jiné trasy neshodují. Aplikace tak může používat jiné kontrolery a stránky, aniž by v aplikaci zasahovala do směrování Blazor Server komponent.

Informace o konfiguraci hostování MapFallbackToPage jiného než kořenového serveru URL naleznete v tématu Hostitel a nasazení ASP.NET Core Blazor.