ASP.NET Core Blazor směrování

Tento článek vysvětluje Blazor směrování požadavků aplikací s pokyny ke statickému a interaktivnímu směrování, integraci směrování koncových bodů ASP.NET Core, navigační události a šablony tras a omezení pro Razor komponenty.

Směrování v architektuře Blazor se zajišťuje zadáním šablony trasy ke každé přístupné komponentě v aplikaci pomocí direktivy @page. Když se vygeneruje soubor Razor s direktivou @page, vygenerované třídě se přidělí atribut RouteAttribute s šablonou trasy. Za běhu směrovač prohledá třídy komponent s atributem RouteAttribute a vykreslí komponentu s šablonou trasy, která odpovídá požadované adrese URL.

Následující HelloWorld komponenta používá šablonu trasy /hello-world, a vykreslená webová stránka pro komponentu je dostupná na relativní URL /hello-world.

HelloWorld.razor:

@page "/hello-world"

<h1>Hello World!</h1>

Předchozí komponenta se v prohlížeči /hello-world načte bez ohledu na to, jestli komponentu přidáte do navigace v uživatelském rozhraní aplikace jako odkaz.

Statické a interaktivní směrování

Tato část se vztahuje na Blazor Web Apps.

Pokud je povoleno předběžné vykreslování, Blazor směrovač (Router součást, <Router> v 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í, směrovač Blazor se po statickém SSR a 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 najdete v tématu ASP.NET Blazor trvalost stavu předsekutného jádra.

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

Tato část se vztahuje na zařízení Blazor Web App, která fungují přes okruh.

Blazor Web App je integrován do systému směrování koncových bodů ASP.NET Core. Aplikace ASP.NET Core je nakonfigurovaná s koncovými body pro směrovatelné komponenty a kořenovou komponentu pro vykreslení těchto koncových bodů v MapRazorComponentsProgram souboru. Výchozí kořenová komponenta (první načtená komponenta) je komponenta App (App.razor):

app.MapRazorComponents<App>();

Šablony tras

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

Razor Při kompilaci komponenty (.razor) s direktivou @page je vygenerovaná třída komponenty zajištěna RouteAttribute, která určuje šablonu trasy komponenty.

Když se aplikace spustí, je naskenováno sestavení specifikované jako AppAssembly směrovače, aby se shromáždily informace o trasách pro součásti aplikace, které mají RouteAttribute.

Při spuštění komponenty RouteView:

• Přijímá RouteData z Router spolu s jakýmkoli parametrem trasy.
• Vykreslí zadanou komponentu s jejím rozložením, včetně všech dalších vnořených rozložení.

Volitelně můžete zadat parametr DefaultLayout s třídou rozložení pro komponenty, které nepoužívají direktivu @layout k určení rozložení. Šablony projektů frameworku určují komponentu () jako výchozí rozložení aplikace. Další informace o rozloženích najdete v tématu ASP.NET Core rozložení.

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"

<h1>Routing Example</h1>

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

Důležité

Aby byly adresy URL správně vyřešeny, musí aplikace obsahovat značku <base> (umístění obsahu <head>) se základní cestou aplikace uvedenou v atributu href. Další informace najdete v ASP.NET Core Blazor základní cestě aplikace.

Jako alternativu k určení šablony trasy jako řetězcového literálu pomocí direktivy @page je možné definovat š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)]

Zaměř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

U požadavků, kde se obsah nenajde, lze komponentu Razor přiřadit k parametru RouterNotFoundPage komponenty. Parametr funguje společně s NavigationManager.NotFoundmetodou volanou v kódu vývojáře, která aktivuje odpověď Nenalezena. NavigationManager.NotFound je popsáno v dalším článku ASP.NET Core Blazor navigace.

Šablona Blazor projektu obsahuje NotFound.razor stránku. Tato stránka se automaticky vykreslí, jakmile je zavolána funkce NavigationManager.NotFound, což umožňuje zpracovat chybějící trasy s konzistentním uživatelským prostředím.

NotFound.razor:

@page "/not-found"
@layout MainLayout

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

Komponenta NotFound je přiřazena k parametru NotFoundPage směrovače. NotFoundPage podporuje směrování, které lze použít v rámci middlewaru pro opětovné provádění stránek stavových kódů, včetně ne-middlewaruBlazor.

V následujícím příkladu je předchozí komponenta NotFound umístěna ve složce aplikace Pages a je předána parametru NotFoundPage.

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

Další informace najdete v dalším článku o navigaci v ASP.NET CoreBlazor.

Směrování na komponenty z různých sestavení

Tato část se vztahuje na Blazor Web Apps.

Pomocí parametru RouterAdditionalAssemblies komponenty a tvůrce konvencí pro koncové body AddAdditionalAssemblies lze 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 v dalších sestaveních pro statické vykreslování na straně serveru (statické SSR), a to i když se směrovač později stane interaktivním pro interaktivní vykreslování, musí být sestavení registrována u frameworku 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 sestavení projektu BlazorSample.Client využívající soubor _Imports.razor projektu:

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), díky čemuž se 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 vykreslení. Další informace najdete v tématu ASP.NET Blazor trvalost stavu předsekutného jádra.

Pokud je komponenta Routes definována v serverovém projektu, parametr AdditionalAssemblies komponenty Router by měl obsahovat sestavení projektu .Client. 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="[ 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.

V projektu .Client, kde je aplikováno globální interaktivní WebAssembly nebo automatické vykreslování, existují směrovatelné komponenty pouze alternativně a komponenta Routes je definována v projektu .Client, 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.

There are no improvements needed.

Směrovač používá parametry trasy k naplnění odpovídajících parametrů komponenty se stejným názvem. Názvy parametrů na trase 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}"

<h1>Route Parameter Example 1</h1>

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

@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í přítomen, je hodnota Text nastavena na fantastic.

RouteParameter2.razor:

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

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

Pokud se místo metody životního cyklu použije metoda životního cyklu OnInitialized{Async}, nedojde k výchozímu přiřazení OnParametersSet{Async} vlastnosti , pokud uživatel naviguje ve stejné komponentě. 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á.

Omezení trasy

Omezení trasy vynucuje, aby segment trasy typově odpovídal 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 typu celočíselný (int).

User.razor:

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

<h1>User Example</h1>

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

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

K dispozici jsou omezení trasy uvedená v následující tabulce. Pokud jde o omezení tras, která odpovídají invariantní kultuře, podívejte se na upozornění pod tabulkou pro další informace.

Omezení	Příklad	Příklady shod	Invariant jazyková verze párování
bool	{active:bool}	true, FALSE	Ne
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}	00001111-aaaa-2222-bbbb-3333cccc4444, {00001111-aaaa-2222-bbbb-3333cccc4444}	Ne
int	{id:int}	123456789, -123456789	Ano
long	{ticks:long}	123456789, -123456789	Ano
nonfile	{parameter:nonfile}	Ne BlazorSample.styles.css, ne favicon.ico	Ano

Upozornění

Omezení směrování, která ověřují adresu URL a jsou převedena na typ CLR (například int nebo DateTime), vždy používají invariantní kulturní nastavení. 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; }
}

Vyhněte se zachytávání souborů v parametru trasy

Následující šablona trasy neúmyslně zachycuje cesty statických prostředků v jeho volitelném parametru trasy (Optional). Například šablona stylů aplikace (.styles.css) je zachycena, což naruší styly aplikace.

@page "/{optional?}"

...

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

Pokud chcete omezit parametr trasy na zachytávání cest, které nejsou soubory, použijte :nonfile omezení v šabloně trasy:

@page "/{optional:nonfile?}"

Univerzální parametry trasy

V komponentách jsou podporovány zastřešující parametry trasy, které zachycují cesty přes hranice více složek.

Parametry všeobecné trasy jsou:

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

CatchAll.razor:

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

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

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 /catch-all/{*pageRoute} generuje URL /catch-all/this/is/a%2Ftest%2A výsledek this/is/a/test*.

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řejdou přímo ve svém prohlížeči.
• Přejde na novou trasu pomocí odkazu nebo NavigationManager.NavigateTo volání, které je využito v kódu vývojáře k přesměrování na URI. NavigationManager Rozhraní API je popsáno v dalším článku navigace v ASP.NET CoreBlazor.

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

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

Příklad, který používá OnNavigateAsync, najdete v části Méně vytěžovaná načítání sestavení v ASP.NET Core Blazor WebAssembly.

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

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

Aby se zabránilo spuštění kódu OnNavigateAsync vývojáře dvakrát, komponenta Routes může uložit NavigationContext pro použití v metodě OnAfterRender{Async} životního cyklu, kde firstRender lze zkontrolovat. Další informace naleznete v tématu Prerendering s javascriptovou interoperabilitou.

Řešení zrušení v OnNavigateAsync

Objekt NavigationContext, který je předán jako parametr zpětnému OnNavigateAsync volání, obsahuje CancellationToken, která je nastavena, když dojde k nové navigační události. 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í je předán ve volání na PostAsJsonAsync, což může zrušit POST, pokud uživatel opustí koncový bod /about.
• Token zrušení se nastaví během operace přednačítání produktu, pokud uživatel opustí koncový bod /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);
            }
        }
    }
}

Poznámka:

Nezahodí-li se, když je zrušen token NavigationContext, může dojít k neočekávanému chování, například k vykreslení komponenty z předchozí navigace.

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 @using pro obor názvů Microsoft.AspNetCore.Components.Routing.

@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á vlastnost Navigating, viz Líné načítání sestavení v ASP.NET Core Blazor WebAssembly.