Routing ASP.NET Core Blazor

W tym artykule opisano Blazor routing żądań aplikacji ze wskazówkami dotyczącymi routingu statycznego i interaktywnego, integracji z routingiem punktów końcowych ASP.NET Core, zdarzeń związanych z nawigacją, a także szablonów tras i ograniczeń dla składników Razor.

Routing na platformie Blazor jest realizowany poprzez podanie szablonu trasy do każdego osiągalnego składnika aplikacji za pomocą dyrektywy @page. Podczas kompilacji pliku Razor z dyrektywą @page generowana klasa otrzymuje parametr RouteAttribute określający szablon trasy. W czasie wykonywania router wyszukuje klasy składników z elementem RouteAttribute i renderuje dowolny składnik, który ma szablon trasy zgodny z żądanym adresem URL.

Poniższy składnik HelloWorld używa szablonu trasy /hello-world, a renderowana strona internetowa składnika jest dostępna pod względnym adresem URL /hello-world.

HelloWorld.razor:

@page "/hello-world"

<h1>Hello World!</h1>

Poprzedni składnik jest ładowany w przeglądarce /hello-world niezależnie od tego, czy składnik zostanie dodany do nawigacji interfejsu użytkownika aplikacji jako link.

Routing statyczny i interakcyjny

Ta sekcja dotyczy Blazor Web Appów.

Jeśli włączono prerendering, Blazor router (Router komponent <Router> w systemie Routes.razor) wykonuje routing statyczny do komponentów podczas renderowania statycznego po stronie serwera (statyczne SSR). Ten typ routingu jest nazywany routingiem statycznym.

Po przypisaniu interakcyjnego trybu renderowania do składnika Routes, router Blazor staje się interaktywny po statycznym SSR ze statycznym routingiem na serwerze. Ten typ routingu jest nazywany routingiem interaktywnym.

Routery statyczne używają routingu punktu końcowego i ścieżki żądania HTTP w celu określenia, który składnik ma być renderowany. Gdy router staje się interaktywny, używa adresu URL dokumentu (adresu URL na pasku adresu przeglądarki), aby określić, który składnik ma być renderowany. Oznacza to, że router interaktywny może dynamicznie zmieniać składnik renderowany, jeśli adres URL dokumentu dynamicznie zmienia się na inny prawidłowy wewnętrzny adres URL i może to zrobić bez wykonywania żądania HTTP w celu pobrania nowej zawartości strony.

Routing interaktywny również uniemożliwia prerenderowanie, ponieważ nowa zawartość strony nie jest żądana z serwera w ramach normalnego żądania strony. Aby uzyskać więcej informacji, zobacz ASP.NET Core prerendered state persistence (Trwałość stanu wstępnego) ASP.NET CoreBlazor.

integracja routingu punktów końcowych ASP.NET Core

Ta sekcja dotyczy Blazor Web Appdziałających nad obwodem.

Element Blazor Web App jest zintegrowany z routingiem punktów końcowych w ASP.NET Core. Aplikacja ASP.NET Core jest skonfigurowana z punktami końcowymi dla składników routingu i składnikiem głównym do renderowania dla tych punktów końcowych MapRazorComponents w Program pliku. Domyślny składnik główny (pierwszy załadowany składnik) to App składnik (App.razor):

app.MapRazorComponents<App>();

Szablony tras

Komponent Router umożliwia routing do komponentów Razor i znajduje się w komponencie Routes aplikacji (Components/Routes.razor).

Gdy kompilowany jest składnik (Razor) z dyrektywą .razor, wygenerowana klasa składnika jest dostarczana z @page określającym szablon trasy składnika.

Po uruchomieniu aplikacji zestaw określony jako Router AppAssembly jest skanowany w celu zebrania informacji o trasach dla składników aplikacji, które mają element RouteAttribute.

W czasie wykonywania RouteView komponent:

• Odbiera RouteData z Router wraz z parametrami trasy.
• Renderuje określony składnik z jego układem graficznym, w tym wszelkie dalsze zagnieżdżone układy.

Opcjonalnie określ parametr DefaultLayout z klasą układu dla składników, które nie określają układu za pomocą dyrektywy @layout. Szablony projektów platformyBlazorokreślają MainLayout składnik (MainLayout.razor) jako domyślny układ aplikacji. Aby uzyskać więcej informacji na temat układów, zobacz układy ASP.NET CoreBlazor.

Składniki obsługują wiele szablonów tras za pomocą wielu @page dyrektyw. Poniższy przykładowy składnik ładuje się na żądania dotyczące /blazor-route i /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>

Ważne

Aby adresy URL były rozpoznawane poprawnie, aplikacja musi zawierać tag <base> (część <head> zawartości) ze ścieżką podstawową aplikacji określoną w atrybucie href. Aby uzyskać więcej informacji, zobacz ścieżka podstawowa aplikacji ASP.NET CoreBlazor.

Alternatywą dla określenia szablonu trasy jako literału ciągu z dyrektywą @page jest użycie szablonów tras opartych na stałych z dyrektywą @attribute.

W poniższym przykładzie dyrektywa @page w składniku jest zastępowana dyrektywą @attribute oraz szablonem trasy opartym na stałej w elemencie Constants.CounterRoute, który jest ustawiany gdzie indziej w aplikacji na "/counter".

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

Skoncentruj element w nawigacji

Składnik FocusOnNavigate ustawia fokus interfejsu użytkownika na element oparty na selektorze CSS po przejściu z jednej strony do innej.

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

Gdy składnik Router przejdzie do nowej strony, składnik FocusOnNavigate ustawia fokus na nagłówku najwyższego poziomu strony (<h1>). Jest to powszechna strategia zapewniania, że nawigacja po stronie jest ogłaszana podczas korzystania z czytnika zawartości ekranu.

Podaj zawartość niestandardową, gdy nie znaleziono zawartości

W przypadku żądań, w których nie można odnaleźć zawartości, składnik Razor można przypisać do parametru NotFoundPage składnika Router. Parametr działa w porozumieniu z NavigationManager.NotFound, metodą wywoływaną w kodzie deweloperskim, która wyzwala odpowiedź Nie znaleziono. jest opisany w następnym artykule nawigacja w ASP.NET Core.

Szablon Blazor projektu zawiera NotFound.razor stronę. Ta strona jest automatycznie generowana za każdym razem, gdy NavigationManager.NotFound jest wywoływana, co umożliwia obsługę brakujących tras przy użyciu spójnego doświadczenia użytkownika.

NotFound.razor:

@page "/not-found"
@layout MainLayout

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

Składnik NotFound jest przypisywany do parametru routera NotFoundPage . NotFoundPage obsługuje routing, który może być wykorzystywany w oprogramowaniu pośredniczącym do ponownego wykonywania dla stron kodu stanu, obejmując również middleware niezależne od Blazor.

W poniższym przykładzie poprzedni NotFound składnik znajduje się w folderze aplikacji Pages i jest przekazywany do parametru NotFoundPage.

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

Aby uzyskać więcej informacji, zobacz następny artykuł na temat nawigacji ASP.NET CoreBlazor.

Trasowanie do komponentów z wielu zestawów

Ta sekcja dotyczy Blazor Web Appów.

Użyj parametru Router składnika AdditionalAssemblies i konstruktora konwencji AddAdditionalAssemblies adresu końcowego, aby odnaleźć routowalne składniki w dodatkowych zestawach. W poniższych podsekcjach wyjaśniono, kiedy i jak używać każdego interfejsu API.

Routing statyczny

Aby odnaleźć składniki routowalne z dodatkowych zestawów na potrzeby statycznego renderowania po stronie serwera (statycznego SSR), nawet jeśli router później stanie się interaktywny dla renderowania interaktywnego, zestawy muszą zostać ujawnione w ramach Blazor. Wywołaj metodę AddAdditionalAssemblies z dodatkowymi zestawami dołączonymi do MapRazorComponents w pliku projektu Program serwera.

Poniższy przykład obejmuje routowalne komponenty w zestawieniu projektu BlazorSample.Client przy użyciu pliku projektu _Imports.razor.

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

Uwaga

Powyższe wskazówki dotyczą również scenariuszy biblioteki klas komponentów. Dodatkowe ważne wskazówki dotyczące bibliotek klas ASP.NET Core (RCLs) ze statycznym renderowaniem po stronie serwera (statycznym SSR) można znaleźć w .

Routing interaktywny

Interaktywny tryb renderowania można przypisać do Routes składnika (Routes.razor), co sprawia, że router Blazor staje się interaktywny po statycznym SSR i routingu na serwerze. Na przykład <Routes @rendermode="InteractiveServer" /> przypisuje interakcyjne renderowanie po stronie serwera (interakcyjne SSR) do składnika Routes. Składnik Router dziedziczy interaktywne renderowanie po stronie serwera (SSR) ze składnika Routes. Router staje się interaktywny po routingu statycznym na serwerze.

Nawigacja wewnętrzna na potrzeby routingu interakcyjnego nie obejmuje żądania nowej zawartości strony z serwera. W związku z tym wstępne renderowanie nie występuje w przypadku żądań stron wewnętrznych. Aby uzyskać więcej informacji, zobacz ASP.NET Core prerendered state persistence (Trwałość stanu wstępnego) ASP.NET CoreBlazor.

Jeśli składnik Routes jest zdefiniowany w projekcie serwera, parametr AdditionalAssemblies składnika Router powinien zawierać zestaw projektu .Client. Dzięki temu router działa prawidłowo podczas interaktywnego renderowania.

W poniższym przykładzie komponent Routes znajduje się w projekcie serwera, a plik _Imports.razor projektu BlazorSample.Client wskazuje zestaw do wyszukiwania routowalnych komponentów.

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

Dodatkowe zestawy są skanowane oprócz zestawu określonego w AppAssembly.

Uwaga

Powyższe wskazówki dotyczą również scenariuszy biblioteki klas komponentów.

Alternatywnie składniki routowalne istnieją tylko w projekcie .Client z globalnym interaktywnym lub automatycznym renderowaniem WebAssembly, a komponent Routes jest zdefiniowany w projekcie .Client, a nie w projekcie serwera. W takim przypadku nie ma zewnętrznych zestawów z routowalnymi składnikami, więc nie trzeba określać wartości dla AdditionalAssemblies elementu.

Parametry trasowania

Router używa parametrów tras, aby wypełnić odpowiednie parametry składnika o tej samej nazwie. Nazwy parametrów trasy są niewrażliwe na wielkość liter. W poniższym przykładzie text parametr przypisuje wartość segmentu trasy do właściwości składnika Text . Gdy zostanie złożone żądanie dla /route-parameter-1/amazing, zawartość jest renderowana 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; }
}

Parametry opcjonalne są obsługiwane. W poniższym przykładzie parametr opcjonalny text przypisuje wartość segmentu trasy do właściwości Text składnika. Jeśli segment nie jest dostępny, wartość Text jest ustawiona 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";
}

Kiedy używana jest metoda cyklu życia OnInitialized{Async} zamiast metody cyklu życia OnParametersSet{Async}, domyślne przypisanie właściwości Text do fantastic nie występuje, jeśli użytkownik nawigowanie odbywa się w obrębie tego samego składnika. Na przykład taka sytuacja pojawia się, gdy użytkownik przechodzi z adresu do /route-parameter-2/amazing/route-parameter-2. Gdy wystąpienie składnika trwa i akceptuje nowe parametry, metoda OnInitialized nie jest wywoływana ponownie.

Ograniczenia trasy

Ograniczenie trasy wymusza dopasowanie typu segmentu trasy do składnika.

W poniższym przykładzie trasa do komponentu User jest zgodna tylko jeśli:

• Segment Id trasy znajduje się w adresie URL żądania.
• Segment Id jest typem liczby całkowitej (int).

User.razor:

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

<h1>User Example</h1>

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

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

Dostępne są ograniczenia tras przedstawione w poniższej tabeli. Aby zapoznać się z ograniczeniami tras zgodnymi z kulturą niezmienną, zobacz ostrzeżenie poniżej tabeli.

Ograniczenie	Przykład	Przykładowe dopasowania	Niezmiennik kultura parowanie
bool	{active:bool}	true, FALSE	Nie.
datetime	{dob:datetime}	2016-12-31, 2016-12-31 7:32pm	Tak
decimal	{price:decimal}	49.99, -1,000.01	Tak
double	{weight:double}	1.234, -1,001.01e8	Tak
float	{weight:float}	1.234, -1,001.01e8	Tak
guid	{id:guid}	00001111-aaaa-2222-bbbb-3333cccc4444, {00001111-aaaa-2222-bbbb-3333cccc4444}	Nie.
int	{id:int}	123456789, -123456789	Tak
long	{ticks:long}	123456789, -123456789	Tak
nonfile	{parameter:nonfile}	Nie BlazorSample.styles.css, nie favicon.ico	Tak

Ostrzeżenie

Ograniczenia trasy, które weryfikują adres URL i są konwertowane na typ CLR (np. int lub DateTime) zawsze używają niezmiennej kultury. Te ograniczenia zakładają, że adres URL nie jest lokalizowalny.

Ograniczenia trasy działają również z parametrami opcjonalnymi. W poniższym przykładzie Id jest wymagany, ale Option jest opcjonalnym parametrem logicznym 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; }
}

Unikaj przechwytywania plików w parametrze trasy

Poniższy szablon trasy przypadkowo przechwytuje statyczne ścieżki zasobów w opcjonalnym parametrze trasy (Optional). Na przykład arkusz stylów aplikacji (.styles.css) jest przechwytywany, co powoduje podział stylów aplikacji:

@page "/{optional?}"

...

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

Aby ograniczyć parametr trasy do przechwytywania ścieżek innych niż pliki, użyj :nonfile ograniczenia w szablonie trasy:

@page "/{optional:nonfile?}"

Parametry trasy ogólne

Parametry ogólne trasy, które przechwytują ścieżki w wielu granicach folderów, są obsługiwane w komponentach.

Parametry trasy catch-all (uniwersalne) to:

• Nazwany, aby odpowiadać nazwie segmentu trasy. Nazwy nie są rozróżniane pod względem wielkości liter.
• Typ string. Framework nie zapewnia automatycznego rzutowania.
• Na końcu adresu 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; }
}

W przypadku adresu URL /catch-all/this/is/a/test z szablonem trasy /catch-all/{*pageRoute}, wartość PageRoute jest ustawiona na this/is/a/test.

Ukośniki i segmenty przechwyconej ścieżki są odkodowywane. W przypadku szablonu trasy /catch-all/{*pageRoute}, adres URL /catch-all/this/is/a%2Ftest%2A zwraca this/is/a/test*.

Obsługuj asynchroniczne zdarzenia nawigacyjne za pomocą OnNavigateAsync

Składnik Router obsługuje OnNavigateAsync funkcję. Procedura obsługi OnNavigateAsync jest wywoływana, gdy użytkownik:

• Odwiedza trasę po raz pierwszy, przechodząc do niej bezpośrednio w przeglądarce.
• Nawiguje do nowej ścieżki za pomocą linku lub wywołania NavigationManager.NavigateTo, które jest używane w kodzie dewelopera do przejścia do identyfikatora URI (Uniform Resource Identifier). [NavigationManager Interfejs API został opisany w następnym artykule, ASP.NET Core Blazor nawigacja.]

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

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

Aby zapoznać się z przykładem, który używa OnNavigateAsync, zobacz Ładowanie z opóźnieniem zestawów w ASP.NET Core Blazor WebAssembly.

Podczas prerenderingu na serwerze OnNavigateAsync jest wykonywane dwa razy:

• Raz, gdy żądany komponent punktu końcowego jest początkowo renderowany statycznie.
• Drugi raz, gdy przeglądarka renderuje komponent punktu końcowego.

Aby zapobiec dwukrotnemu wykonaniu kodu OnNavigateAsync dewelopera, Routes komponent może przechowywać NavigationContext zmienną do użycia w metodzie OnAfterRender{Async} cyklu życia, gdzie firstRender można to sprawdzić. Aby uzyskać więcej informacji, zobacz Wstępne renderowanie przy użyciu interakcji z językiem JavaScript.

Obsługa anulowań w OnNavigateAsync

Obiekt NavigationContext przekazany do wywołania zwrotnego OnNavigateAsync zawiera element CancellationToken, który jest ustawiany, gdy wystąpi nowe zdarzenie nawigacji. Wywołanie OnNavigateAsync powinno zakończyć działanie, gdy ten token anulowania zostanie ustawiony, aby uniknąć kontynuowania uruchamiania OnNavigateAsync wywołania zwrotnego podczas nieaktualnej nawigacji.

Jeśli użytkownik przejdzie do punktu końcowego, ale natychmiast przejdzie do nowego punktu końcowego, aplikacja nie powinna kontynuować uruchamiania OnNavigateAsync wywołania zwrotnego dla pierwszego punktu końcowego.

W poniższym przykładzie:

• Token anulowania jest przekazywany w wywołaniu PostAsJsonAsync, co może anulować żądanie POST, jeśli użytkownik przejdzie z dala od punktu końcowego /about.
• Token anulowania jest ustawiany podczas operacji pobierania wstępnego produktu, jeśli użytkownik opuszcza punkt końcowy /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);
            }
        }
    }
}

Uwaga

Brak rzucania wyjątku, kiedy token anulowania w NavigationContext jest anulowany, może prowadzić do niezamierzonego zachowania, takiego jak renderowanie składnika z poprzedniej nawigacji.

Interakcja użytkownika z zawartością <Navigating>

Jeśli podczas nawigacji występuje znaczne opóźnienie, na przykład podczas leniwego ładowania zestawów w Blazor WebAssembly aplikacji lub w przypadku powolnego połączenia sieciowego z Blazor aplikacją po stronie serwera, Router składnik może informować użytkownika o zachodzącym przejściu między stronami.

Na górze składnika, który określa komponent Router, dodaj dyrektywę @using dla przestrzeni nazw Microsoft.AspNetCore.Components.Routing.

@using Microsoft.AspNetCore.Components.Routing

Podaj zawartość dla parametru Navigating do wyświetlenia podczas zdarzeń przejścia strony.

W elemencie routera (<Router>...</Router>) zawartość:

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

Aby zapoznać się z przykładem użycia właściwości Navigating, zobacz w sekcji Ładowanie zestawów z opóźnieniem w programie ASP.NET Core Blazor WebAssembly.