ASP.NET Core Blazor routingu i nawigacji

Artykuł
11/12/2024

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

W tym artykule wyjaśniono, jak zarządzać Blazor routingiem żądań aplikacji i jak używać NavLink składnika do tworzenia linków nawigacji.

Ważne

Przykłady kodu w tym artykule pokazują metody o nazwie , Navigationktóra jest wstrzykiwana NavigationManager w klasach i składnikach.

Routing statyczny i interakcyjny

Ta sekcja dotyczy s Blazor Web App.

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

Po przypisaniu interakcyjnego Routes trybu renderowania do składnika Blazor router staje się interaktywny po statycznym routingu 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 uniemożliwia również wstępne przetwarzanie, ponieważ nowa zawartość strony nie jest żądana z serwera z normalnym żądaniem strony. Aby uzyskać więcej informacji, zobacz Razor prerender ASP.NET Core).

Szablony tras

Składnik Router umożliwia routing do Razor składników i znajduje się w składniku Routes aplikacji (Components/Routes.razor).

Składnik Router umożliwia routing do Razor składników. Składnik Router jest używany w składniku App (App.razor).

Razor Gdy składnik (.razor) z dyrektywą @page jest kompilowany, wygenerowana klasa składników jest dostarczana przy RouteAttribute użyciu szablonu trasy składnika.

Po uruchomieniu aplikacji zestaw określony jako router AppAssembly jest skanowany w celu zebrania informacji o trasie dla składników aplikacji, które mają RouteAttributeelement .

W czasie wykonywania RouteView składnik:

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

Opcjonalnie określ DefaultLayout parametr z klasą układu dla składników, które nie określają układu z dyrektywą@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 Blazor podstawowe.

Składniki obsługują wiele szablonów tras przy użyciu wielu @page dyrektyw. Poniższy przykładowy składnik ładuje żądania dla /blazor-route elementów i /different-blazor-route.

BlazorRoute.razor:

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

<PageTitle>Routing</PageTitle>

<h1>Routing Example</h1>

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

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

<PageTitle>Routing</PageTitle>

<h1>Routing Example</h1>

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

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

<h1>Blazor routing</h1>

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

<h1>Blazor routing</h1>

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

<h1>Blazor routing</h1>

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

<h1>Blazor routing</h1>

Ważne

Aby adresy URL rozpoznawały poprawnie, aplikacja musi zawierać <base> tag (lokalizację <head> zawartości) ze ścieżką podstawową aplikacji określoną w atrybucie href . Aby uzyskać więcej informacji, zobacz Host and deploy ASP.NET Core Blazor.

Element Router nie wchodzi w interakcję z wartościami ciągu zapytania. Aby pracować z ciągami zapytania, zobacz sekcję Ciągi zapytania.

Alternatywą dla określenia szablonu trasy jako literału ciągu z @page dyrektywą można określić szablony tras opartych na stałe z dyrektywą@attribute.

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

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

Uwaga

Od wydania wersji ASP.NET Core 5.0.1 i w przypadku wszelkich dodatkowych wydań 5.x składnik Router zawiera parametr PreferExactMatches ustawiony na wartość @true. Aby uzyskać więcej informacji, zobacz Migracja z platformy ASP.NET Core w wersji 3.1 do wersji 5.0.

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

Router Gdy składnik przejdzie do nowej strony, FocusOnNavigate składnik ustawia fokus na nagłówek 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

Składnik Router umożliwia aplikacji określanie zawartości niestandardowej, jeśli nie można odnaleźć zawartości dla żądanej trasy.

Ustaw zawartość niestandardową dla parametru Router NotFound składnika:

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

Dowolne elementy są obsługiwane jako zawartość parametru NotFound , na przykład inne składniki interakcyjne. Aby zastosować układ domyślny do NotFound zawartości, zobacz Blazor podstawowe.

Ważne

Blazor Web Appnie używają parametru NotFound (znaczników<NotFound>...</NotFound>), ale parametr jest obsługiwany† w celu zapewnienia zgodności z poprzednimi wersjami, aby uniknąć zmiany powodującej niezgodność w frameworku. Potok oprogramowania pośredniczącego ASP.NET Core po stronie serwera przetwarza żądania na serwerze. Użyj technik po stronie serwera do obsługi nieprawidłowych żądań.

†Obsługiwane w tym kontekście oznacza, że umieszczenie <NotFound>...</NotFound> znacznika nie powoduje wyjątku, ale jego użycie również nie jest skuteczne.

Aby uzyskać więcej informacji, w tym zalecane podejście do obsługi nieprawidłowych żądań, zobacz ASP.NET Core Blazor tryby renderowania.

Kierowanie do składników z wielu zestawów

Ta sekcja dotyczy s Blazor Web App.

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

Routing statyczny

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

Poniższy przykład obejmuje składniki routingu w BlazorSample.Client zestawie projektu 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 składników. Dodatkowe ważne wskazówki dotyczące bibliotek klas i statycznego przewodnika SSR można znaleźć w ASP.NET bibliotekach klas podstawowych Razor (RCLS) ze statycznym renderowaniem po stronie serwera (statycznym SSR).

Routing interaktywny

Interakcyjny tryb renderowania można przypisać do Routes składnika (Routes.razor), który sprawia Blazor , że router staje się interaktywny po statycznym routingu SSR i routingu statycznym na serwerze. Na przykład <Routes @rendermode="InteractiveServer" /> przypisuje do składnika interakcyjne renderowanie po stronie serwera (interakcyjne SSR).Routes Składnik Router dziedziczy interakcyjne renderowanie po stronie serwera (interakcyjne SSR) ze Routes składnika. 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 przetwarzanie nie występuje w przypadku żądań stron wewnętrznych. Aby uzyskać więcej informacji, zobacz Razor prerender ASP.NET Core).

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

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

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

Dodatkowe zestawy są skanowane oprócz zestawu określonego dla AppAssemblyelementu .

Uwaga

Powyższe wskazówki dotyczą również scenariuszy biblioteki klas składników.

Alternatywnie składniki routingu istnieją tylko w .Client projekcie z globalnym interakcyjnym zestawem WebAssembly lub Automatycznym renderowaniem, a Routes składnik jest zdefiniowany w .Client projekcie, a nie w projekcie serwera. W takim przypadku nie ma zestawów zewnętrznych ze składnikami routingu, więc nie trzeba określać wartości dla AdditionalAssemblieselementu .

Ta sekcja dotyczy Blazor Server aplikacji.

Użyj parametru Router AdditionalAssemblies składnika i konstruktora AddAdditionalAssemblies konwencji punktu końcowego, aby odnaleźć składniki routingu w dodatkowych zestawach.

W poniższym przykładzie Component1 jest składnikiem routingu zdefiniowanym w przywoływanej bibliotece klas składników o nazwie ComponentLibrary:

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

Dodatkowe zestawy są skanowane oprócz zestawu określonego dla AppAssemblyelementu .

Parametry tras

Router używa parametrów trasy, 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 . Po wysłaniu żądania dla /route-parameter-1/amazingelementu zawartość jest renderowana 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}"

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

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 obecny, wartość parametru jest ustawiona Text na fantasticwartość .

Parametry opcjonalne nie są obsługiwane. W poniższym przykładzie zastosowano dwie @page dyrektywy . Pierwsza dyrektywa zezwala na nawigację do składnika bez parametru. Druga dyrektywa przypisuje wartość parametru {text} trasy do właściwości składnika Text .

RouteParameter2.razor:

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

<PageTitle>Route Parameter 2</PageTitle>

<h1>Route Parameter Example 2</h1>

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

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

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

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

<PageTitle>Route Parameter 2</PageTitle>

<h1>Route Parameter Example 2</h1>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

OnInitialized{Async} Gdy metoda cyklu życia jest używana zamiast OnParametersSet{Async} cyklu życia, domyślne przypisanie Text właściwości do fantastic nie występuje, jeśli użytkownik przechodzi 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 będzie się powtarzać i akceptuje nowe parametry, OnInitialized metoda nie jest wywoływana ponownie.

Uwaga

Parametry trasy nie działają z wartościami ciągu zapytania. Aby pracować z ciągami zapytania, zobacz sekcję Ciągi zapytania.

Ograniczenia trasy

Ograniczenie trasy wymusza dopasowywanie typów w segmencie trasy do składnika.

W poniższym przykładzie trasa do składnika jest zgodna User tylko w następujących przypadkach:

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

User.razor:

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

<PageTitle>User</PageTitle>

<h1>User Example</h1>

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

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

Uwaga

Ograniczenia trasy nie działają z wartościami ciągu zapytania. Aby pracować z ciągami zapytania, zobacz sekcję Ciągi zapytania.

Dostępne są ograniczenia tras przedstawione w poniższej tabeli. Aby uzyskać więcej informacji, zobacz ostrzeżenie poniżej tabeli, aby uzyskać więcej informacji, aby zapoznać się z ograniczeniami tras, które są zgodne z kulturą niezmienną.

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 trasy logicznej.

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

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

Routing z adresami URL zawierającymi kropki

Domyślny szablon trasy po stronie serwera zakłada, że jeśli ostatni segment adresu URL żądania zawiera kropkę (.), która jest żądana przez plik. Na przykład względny adres URL /example/some.thing jest interpretowany przez router jako żądanie dla pliku o nazwie some.thing. Bez dodatkowej konfiguracji aplikacja zwraca odpowiedź 404 — Nie znaleziono , jeśli some.thing została przeznaczona do kierowania do składnika z dyrektywą @page i some.thing jest wartością parametru trasy. Aby użyć trasy z co najmniej jednym parametrem zawierającym kropkę, aplikacja musi skonfigurować trasę przy użyciu szablonu niestandardowego.

Rozważmy następujący Example składnik, który może odbierać parametr trasy z ostatniego segmentu adresu 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; }
}

Aby zezwolić Server aplikacji hostowanego Blazor WebAssemblyrozwiązania na kierowanie żądania kropką w parametrze param trasy, dodaj szablon trasy pliku rezerwowego z opcjonalnym parametrem Program w pliku:

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

Aby skonfigurować aplikację Blazor Server do kierowania żądania kropką w parametrze param trasy, dodaj szablon trasy strony rezerwowej z opcjonalnym parametrem Program w pliku:

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

Aby uzyskać więcej informacji, zobacz Routing na platformie ASP.NET Core.

Aby zezwolić Server aplikacji hostowanego Blazor WebAssemblyrozwiązania na kierowanie żądania kropką w parametrze param trasy, dodaj szablon trasy rezerwowego pliku z opcjonalnym parametrem w Startup.Configurepliku .

Startup.cs:

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

Aby skonfigurować aplikację Blazor Server do kierowania żądania kropką w parametrze param trasy, dodaj szablon trasy strony rezerwowej z opcjonalnym parametrem w pliku Startup.Configure.

Startup.cs:

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

Aby uzyskać więcej informacji, zobacz Routing na platformie ASP.NET Core.

Parametry trasy catch-all

Parametry trasy catch-all, które przechwytują ścieżki w wielu granicach folderów, są obsługiwane w składnikach.

Parametry trasy catch-all to:

Nazwane w celu dopasowania nazwy segmentu trasy. Nazewnictwo nie uwzględnia wielkości liter.
string Typ. Struktura nie zapewnia automatycznego rzutu.
Na końcu adresu 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}"

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

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

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

Służy NavigationManager do zarządzania identyfikatorami URI i nawigacją w kodzie języka C#. NavigationManager Zawiera zdarzenia i metody pokazane w poniższej tabeli.

Element członkowski	opis
Uri	Pobiera bieżący bezwzględny identyfikator URI.
BaseUri	Pobiera podstawowy identyfikator URI (z ukośnikiem końcowym), który można poprzedzać względnymi ścieżkami identyfikatora URI w celu utworzenia bezwzględnego identyfikatora URI. BaseUri Zazwyczaj odpowiada atrybutowi `href` elementu dokumentu `<base>` (lokalizacji `<head>` zawartości).
NavigateTo	Przechodzi do określonego identyfikatora URI. Jeśli `forceLoad` ma wartość `false`: Ulepszona nawigacja jest dostępna pod bieżącym adresem URL, Blazora ulepszona nawigacja jest aktywowana. Blazor W przeciwnym razie wykonuje ponowne ładowanie pełnej strony dla żądanego adresu URL. Jeśli `forceLoad` ma wartość `true`: Routing po stronie klienta jest pomijany. Przeglądarka jest zmuszona do załadowania nowej strony z serwera, niezależnie od tego, czy identyfikator URI jest zwykle obsługiwany przez router interaktywny po stronie klienta. Aby uzyskać więcej informacji, zobacz sekcję Rozszerzona nawigacja i obsługa formularzy . Jeśli `replace` ma `true`wartość , bieżący identyfikator URI w historii przeglądarki zostanie zastąpiony zamiast wypchnąć nowy identyfikator URI do stosu historii.
LocationChanged	Zdarzenie uruchamiane po zmianie lokalizacji nawigacji. Aby uzyskać więcej informacji, zobacz sekcję Zmiany lokalizacji .
ToAbsoluteUri	Konwertuje względny identyfikator URI na bezwzględny identyfikator URI.
ToBaseRelativePath	Na podstawie podstawowego identyfikatora URI aplikacji konwertuje bezwzględny identyfikator URI na identyfikator URI względem prefiksu podstawowego identyfikatora URI. Przykład można znaleźć w sekcji Tworzenie identyfikatora URI względem prefiksu podstawowego identyfikatora URI.
`RegisterLocationChangingHandler`	Rejestruje program obsługi w celu przetwarzania przychodzących zdarzeń nawigacji. Wywołanie NavigateTo zawsze wywołuje procedurę obsługi.
GetUriWithQueryParameter	Zwraca identyfikator URI utworzony przez aktualizację NavigationManager.Uri za pomocą pojedynczego parametru dodanego, zaktualizowanego lub usuniętego. Aby uzyskać więcej informacji, zobacz sekcję Ciągi zapytania.

Element członkowski	opis
Uri	Pobiera bieżący bezwzględny identyfikator URI.
BaseUri	Pobiera podstawowy identyfikator URI (z ukośnikiem końcowym), który można poprzedzać względnymi ścieżkami identyfikatora URI w celu utworzenia bezwzględnego identyfikatora URI. BaseUri Zazwyczaj odpowiada atrybutowi `href` elementu dokumentu `<base>` (lokalizacji `<head>` zawartości).
NavigateTo	Przechodzi do określonego identyfikatora URI. Jeśli `forceLoad` ma wartość `true`: Routing po stronie klienta jest pomijany. Przeglądarka jest zmuszona do załadowania nowej strony z serwera, niezależnie od tego, czy identyfikator URI jest zwykle obsługiwany przez router po stronie klienta. Jeśli `replace` ma `true`wartość , bieżący identyfikator URI w historii przeglądarki zostanie zastąpiony zamiast wypchnąć nowy identyfikator URI do stosu historii.
LocationChanged	Zdarzenie uruchamiane po zmianie lokalizacji nawigacji. Aby uzyskać więcej informacji, zobacz sekcję Zmiany lokalizacji .
ToAbsoluteUri	Konwertuje względny identyfikator URI na bezwzględny identyfikator URI.
ToBaseRelativePath	Na podstawie podstawowego identyfikatora URI aplikacji konwertuje bezwzględny identyfikator URI na identyfikator URI względem prefiksu podstawowego identyfikatora URI. Przykład można znaleźć w sekcji Tworzenie identyfikatora URI względem prefiksu podstawowego identyfikatora URI.
`RegisterLocationChangingHandler`	Rejestruje program obsługi w celu przetwarzania przychodzących zdarzeń nawigacji. Wywołanie NavigateTo zawsze wywołuje procedurę obsługi.
GetUriWithQueryParameter	Zwraca identyfikator URI utworzony przez aktualizację NavigationManager.Uri za pomocą pojedynczego parametru dodanego, zaktualizowanego lub usuniętego. Aby uzyskać więcej informacji, zobacz sekcję Ciągi zapytania.

Element członkowski	opis
Uri	Pobiera bieżący bezwzględny identyfikator URI.
BaseUri	Pobiera podstawowy identyfikator URI (z ukośnikiem końcowym), który można poprzedzać względnymi ścieżkami identyfikatora URI w celu utworzenia bezwzględnego identyfikatora URI. BaseUri Zazwyczaj odpowiada atrybutowi `href` elementu dokumentu `<base>` (lokalizacji `<head>` zawartości).
NavigateTo	Przechodzi do określonego identyfikatora URI. Jeśli `forceLoad` ma wartość `true`: Routing po stronie klienta jest pomijany. Przeglądarka jest zmuszona do załadowania nowej strony z serwera, niezależnie od tego, czy identyfikator URI jest zwykle obsługiwany przez router po stronie klienta. Jeśli `replace` ma `true`wartość , bieżący identyfikator URI w historii przeglądarki zostanie zastąpiony zamiast wypchnąć nowy identyfikator URI do stosu historii.
LocationChanged	Zdarzenie uruchamiane po zmianie lokalizacji nawigacji. Aby uzyskać więcej informacji, zobacz sekcję Zmiany lokalizacji .
ToAbsoluteUri	Konwertuje względny identyfikator URI na bezwzględny identyfikator URI.
ToBaseRelativePath	Na podstawie podstawowego identyfikatora URI aplikacji konwertuje bezwzględny identyfikator URI na identyfikator URI względem prefiksu podstawowego identyfikatora URI. Przykład można znaleźć w sekcji Tworzenie identyfikatora URI względem prefiksu podstawowego identyfikatora URI.
GetUriWithQueryParameter	Zwraca identyfikator URI utworzony przez aktualizację NavigationManager.Uri za pomocą pojedynczego parametru dodanego, zaktualizowanego lub usuniętego. Aby uzyskać więcej informacji, zobacz sekcję Ciągi zapytania.

Element członkowski	opis
Uri	Pobiera bieżący bezwzględny identyfikator URI.
BaseUri	Pobiera podstawowy identyfikator URI (z ukośnikiem końcowym), który można poprzedzać względnymi ścieżkami identyfikatora URI w celu utworzenia bezwzględnego identyfikatora URI. BaseUri Zazwyczaj odpowiada atrybutowi `href` elementu dokumentu `<base>` (lokalizacji `<head>` zawartości).
NavigateTo	Przechodzi do określonego identyfikatora URI. Jeśli `forceLoad` ma wartość `true`: Routing po stronie klienta jest pomijany. Przeglądarka jest zmuszona do załadowania nowej strony z serwera, niezależnie od tego, czy identyfikator URI jest zwykle obsługiwany przez router po stronie klienta.
LocationChanged	Zdarzenie uruchamiane po zmianie lokalizacji nawigacji.
ToAbsoluteUri	Konwertuje względny identyfikator URI na bezwzględny identyfikator URI.
ToBaseRelativePath	Na podstawie podstawowego identyfikatora URI aplikacji konwertuje bezwzględny identyfikator URI na identyfikator URI względem prefiksu podstawowego identyfikatora URI. Przykład można znaleźć w sekcji Tworzenie identyfikatora URI względem prefiksu podstawowego identyfikatora URI.

Zmiany lokalizacji

W przypadku LocationChanged zdarzenia LocationChangedEventArgs zawiera następujące informacje o zdarzeniach nawigacji:

Location: adres URL nowej lokalizacji.
IsNavigationIntercepted: Jeśli true, Blazor przechwycił nawigację z przeglądarki. Jeśli falseelement , NavigationManager.NavigateTo spowodował wystąpienie nawigacji.

Następujący składnik:

Przechodzi do składnika aplikacji Counter (Counter.razor) po wybraniu przycisku przy użyciu polecenia NavigateTo.
Obsługuje zdarzenie zmienionej lokalizacji, subskrybując element NavigationManager.LocationChanged.
- Metoda HandleLocationChanged jest nieprzyznana, gdy Dispose jest wywoływana przez platformę. Odłączanie metody umożliwia odzyskiwanie pamięci składnika.
- Implementacja rejestratora rejestruje następujące informacje po wybraniu przycisku:
  
  BlazorSample.Pages.Navigate: Information: URL of new location: https://localhost:{PORT}/counter

Navigate.razor:

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

<PageTitle>Navigate</PageTitle>

<h1>Navigate Example</h1>

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

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

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

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

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

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

<PageTitle>Navigate</PageTitle>

<h1>Navigate Example</h1>

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

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

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

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

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

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

<h1>Navigate in component code example</h1>

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

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

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

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

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

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

<h1>Navigate in component code example</h1>

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

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

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

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

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

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

<h1>Navigate in component code example</h1>

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

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

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

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

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

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

<h1>Navigate in component code example</h1>

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

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

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

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

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

Aby uzyskać więcej informacji na temat usuwania składników, zobacz Razor składnika podstawowego ASP.NET).

Ta sekcja dotyczy s Blazor Web App.

Blazor Web AppS są w stanie obsługiwać dwa typy routingu dla nawigacji stron i obsługi formularzy żądania:

Normalna nawigacja (nawigacja między dokumentami): ponowne ładowanie pełnostronicowe jest wyzwalane dla adresu URL żądania.
Ulepszona nawigacja (nawigacja w tym samym dokumencie): Blazor przechwytuje żądanie i wykonuje zamiast tego fetch żądanie. Blazor następnie wprowadza poprawki do zawartości odpowiedzi w modelu DOM strony. BlazorUlepszona nawigacja i obsługa formularzy pozwalają uniknąć konieczności ponownego ładowania pełnej strony i zachowania większej ilości stanu strony, dzięki czemu strony są ładowane szybciej, zwykle bez utraty położenia przewijania użytkownika na stronie.

Ulepszona nawigacja jest dostępna, gdy:

Skrypt Blazor Web App (blazor.web.js) jest używany, a nie Blazor Server skrypt (blazor.server.js) ani Blazor WebAssembly skrypt (blazor.webassembly.js).
Ta funkcja nie jest jawnie wyłączona.
Docelowy adres URL znajduje się w wewnętrznej przestrzeni podstawowego identyfikatora URI (ścieżka podstawowa aplikacji).

Jeśli włączono routing po stronie serwera i rozszerzoną nawigację, programy obsługi zmieniające lokalizacje są wywoływane tylko w przypadku nawigacji programowej inicjowanej przez interakcyjne środowisko uruchomieniowe. W przyszłych wersjach dodatkowe typy nawigacji, takie jak poniżej linku, mogą również wywoływać programy obsługi zmieniające lokalizacje.

W przypadku rozszerzonej nawigacji LocationChanged programy obsługi zdarzeń zarejestrowane w środowiskach uruchomieniowych Interactive Server i WebAssembly są zwykle wywoływane. Istnieją przypadki, gdy zmiany lokalizacji programów obsługi mogą nie przechwytywać rozszerzonej nawigacji. Na przykład użytkownik może przełączyć się na inną stronę przed udostępnieniem interakcyjnego środowiska uruchomieniowego. Dlatego ważne jest, aby logika aplikacji nie polegała na wywoływaniu procedury obsługi zmieniającej lokalizację, ponieważ nie ma gwarancji na wykonanie programu obsługi.

Podczas wywoływania metody NavigateTo:

Jeśli forceLoad ma falsewartość , która jest wartością domyślną:
- Ulepszona nawigacja jest dostępna pod bieżącym adresem URL, Blazora ulepszona nawigacja jest aktywowana.
- Blazor W przeciwnym razie wykonuje ponowne ładowanie pełnej strony dla żądanego adresu URL.
Jeśli forceLoad parametr to true: Blazor wykonuje ponowne ładowanie pełnej strony dla żądanego adresu URL, niezależnie od tego, czy rozszerzona nawigacja jest dostępna, czy nie.

Możesz odświeżyć bieżącą stronę, wywołując metodę NavigationManager.Refresh(bool forceLoad = false), która zawsze wykonuje rozszerzoną nawigację, jeśli jest dostępna. Jeśli rozszerzona nawigacja nie jest dostępna, Blazor wykonuje ponowne ładowanie pełnej strony.

Navigation.Refresh();

Przekaż true do parametru forceLoad , aby upewnić się, że ponowne ładowanie pełnostronicowe jest zawsze wykonywane, nawet jeśli jest dostępna rozszerzona nawigacja:

Navigation.Refresh(true);

Rozszerzona nawigacja jest domyślnie włączona, ale może być kontrolowana hierarchicznie i na podstawie linku przy użyciu atrybutu data-enhance-nav HTML.

Następujące przykłady wyłączają nawigację rozszerzoną:

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

Jeśli miejsce docelowe nie jestBlazor punktem końcowym, rozszerzona nawigacja nie ma zastosowania, a skrypt JavaScript po stronie klienta jest ponawiany jako ładowanie pełnej strony. Dzięki temu nie ma wątpliwości co do struktury stron zewnętrznych, które nie powinny być poprawiane na istniejącej stronie.

Aby włączyć rozszerzoną Enhance obsługę formularzy, dodaj parametr do formularzy lub EditForm atrybut do data-enhance formularzy HTML (<form>):

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

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

Ulepszona obsługa formularzy nie jest hierarchiczna i nie przepływa do formularzy podrzędnych:

Nieobsługiwane: nie można ustawić rozszerzonej nawigacji na elemektorze przodka formularza w celu włączenia rozszerzonej nawigacji dla formularza.

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

Rozszerzone wpisy formularza działają tylko z punktami Blazor końcowymi. Opublikowanie rozszerzonego formularza wBlazor punkcie końcowym powoduje wystąpienie błędu.

Aby wyłączyć rozszerzoną nawigację:

W przypadku elementu EditFormusuń Enhance parametr z elementu formularza (lub ustaw go na wartość false: Enhance="false").
W przypadku kodu HTML <form>usuń data-enhance atrybut z elementu formularza (lub ustaw go na wartość false: data-enhance="false").

BlazorUlepszona nawigacja i przekazywanie formularzy mogą cofnąć dynamiczne zmiany w modelu DOM, jeśli zaktualizowana zawartość nie jest częścią renderowania serwera. Aby zachować zawartość elementu, użyj atrybutu data-permanent .

W poniższym przykładzie zawartość <div> elementu jest aktualizowana dynamicznie przez skrypt podczas ładowania strony:

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

Po Blazor uruchomieniu na kliencie możesz użyć enhancedload zdarzenia w celu nasłuchiwania rozszerzonych aktualizacji strony. Umożliwia to ponowne stosowanie zmian do modelu DOM, które mogły zostać cofnięte przez rozszerzoną aktualizację strony.

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

Aby wyłączyć rozszerzoną nawigację i obsługę formularzy globalnie, zobacz uruchamianie ASP.NET CoreBlazor.

Ulepszona nawigacja przy użyciu renderowania statycznego po stronie serwera (statyczna usługa SSR) wymaga szczególnej uwagi podczas ładowania kodu JavaScript. Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor JavaScript z renderowaniem statycznym po stronie serwera (static SSR) .

Tworzenie identyfikatora URI względem prefiksu podstawowego identyfikatora URI

Na podstawie podstawowego identyfikatora URI ToBaseRelativePath aplikacji konwertuje bezwzględny identyfikator URI na identyfikator URI względem prefiksu podstawowego identyfikatora URI.

Rozważmy następujący przykład:

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

Jeśli podstawowy identyfikator URI aplikacji to https://localhost:8000, zostaną uzyskane następujące wyniki:

Przekazywanie https://localhost:8000/segment wyników w elemecie inputURIbaseRelativePath .segment
Przekazywanie https://localhost:8000/segment1/segment2 wyników w elemecie inputURIbaseRelativePath .segment1/segment2

Jeśli podstawowy identyfikator URI aplikacji nie jest zgodny z podstawowym identyfikatorem URI inputURI, ArgumentException zostanie zgłoszony element .

Przekazywanie https://localhost:8001/segmentinputURI wyników powoduje wystąpienie następującego wyjątku:

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

Używa NavigationManager interfejsu API historii przeglądarki do obsługi stanu historii nawigacji skojarzonego z każdą zmianą lokalizacji wprowadzonych przez aplikację. Utrzymywanie stanu historii jest szczególnie przydatne w scenariuszach przekierowania zewnętrznego, takich jak w przypadku uwierzytelniania użytkowników z zewnętrznymi dostawcami tożsamości. Aby uzyskać więcej informacji, zobacz sekcję Opcje nawigacji.

Przekaż NavigationOptions polecenie , aby NavigateTo kontrolować następujące zachowania:

ForceLoad: Pomiń routing po stronie klienta i wymuś załadowanie nowej strony z serwera, niezależnie od tego, czy identyfikator URI jest obsługiwany przez router po stronie klienta. Domyślna wartość to false.
ReplaceHistoryEntry: zastąp bieżący wpis w stosie historii. Jeśli false, dołącz nowy wpis do stosu historii. Domyślna wartość to false.
HistoryEntryState: Pobiera lub ustawia stan, który ma być dołączany do wpisu historii.

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

Aby uzyskać więcej informacji na temat uzyskiwania stanu skojarzonego z wpisem historii docelowej podczas obsługi zmian lokalizacji, zobacz sekcję Obsługa/zapobieganie zmianom lokalizacji.

Ciągi zapytań

Użyj atrybutu [SupplyParameterFromQuery] , aby określić, że parametr składnika pochodzi z ciągu zapytania.

Użyj atrybutu [Parameter] , aby określić, że parametr składnika składnika routable pochodzi z ciągu zapytania.

Uwaga

Parametry składnika mogą odbierać tylko wartości parametrów zapytania w składnikach routingu z dyrektywą @page .

Tylko składniki routingu bezpośrednio odbierają parametry zapytania, aby uniknąć odwrócania przepływu informacji od góry w dół i w celu jasnego kolejności przetwarzania parametrów, zarówno przez strukturę, jak i przez aplikację. Ten projekt pozwala uniknąć drobnych usterek w kodzie aplikacji, które zostały napisane przy założeniu określonej kolejności przetwarzania parametrów. Możesz definiować niestandardowe parametry kaskadowe lub bezpośrednio przypisywać do zwykłych parametrów składnika w celu przekazania wartości parametrów zapytania do składników niezwiązanych z routingem.

Parametry składnika dostarczone z ciągu zapytania obsługują następujące typy:

bool, DateTime, , decimal, doublefloatGuid, int, long, . string
Warianty dopuszczające wartość null poprzednich typów.
Tablice powyższych typów, niezależnie od tego, czy są dopuszczane do wartości null, czy nie mogą być dopuszczane do wartości null.

Poprawne formatowanie niezmienne kultury jest stosowane dla danego typu (CultureInfo.InvariantCulture).

Określ właściwość atrybutu [SupplyParameterFromQuery]Name , aby użyć nazwy parametru zapytania innej niż nazwa parametru składnika. W poniższym przykładzie nazwa języka C# parametru składnika to {COMPONENT PARAMETER NAME}. Dla symbolu zastępczego określono inną nazwę parametru {QUERY PARAMETER NAME} zapytania:

W przeciwieństwie do właściwości parametru składnika ([Parameter]), [SupplyParameterFromQuery] właściwości można oznaczyć private oprócz public.

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

Podobnie jak właściwości parametru składnika ([Parameter]), [SupplyParameterFromQuery] właściwości są zawsze public właściwościami platformy .NET 6/7. W programie .NET 8 lub nowszym [SupplyParameterFromQuery] można oznaczyć public właściwości lub private.

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

W poniższym przykładzie z adresem URL :/search?filter=scifi%20stars&page=3&star=LeVar%20Burton&star=Gary%20Oldman

Właściwość Filter jest rozpoznawana jako scifi stars.
Właściwość Page jest rozpoznawana jako 3.
Tablica Stars jest wypełniana z parametrów zapytania o nazwie star (Name = "star") i jest rozpoznawana jako LeVar Burton i Gary Oldman.

Uwaga

Parametry ciągu zapytania w następującym składniku strony routingu działają również w składniku niezwiązanym z routingiem @page bez dyrektywy (na przykład Search.razor w przypadku współużytkowanego Search składnika używanego w innych składnikach).

Search.razor:

@page "/search"

<h1>Search Example</h1>

<p>Filter: @Filter</p>

<p>Page: @Page</p>

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

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

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

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

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

Search.razor:

@page "/search"

<h1>Search Example</h1>

<p>Filter: @Filter</p>

<p>Page: @Page</p>

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

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

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

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

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

Służy GetUriWithQueryParameter do dodawania, zmieniania lub usuwania co najmniej jednego parametru zapytania w bieżącym adresie URL:

@inject NavigationManager Navigation

...

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

W poprzednim przykładzie:

Symbol {NAME} zastępczy określa nazwę parametru zapytania. Symbol {VALUE} zastępczy określa wartość jako obsługiwany typ. Obsługiwane typy są wymienione w dalszej części tej sekcji.
Ciąg jest zwracany jako bieżący adres URL z pojedynczym parametrem:
- Dodano, jeśli nazwa parametru zapytania nie istnieje w bieżącym adresie URL.
- Zaktualizowano wartość do podanej, jeśli parametr zapytania istnieje w bieżącym adresie URL.
- Usunięto, jeśli typ podanej wartości ma wartość null, a wartość to null.
Poprawne formatowanie niezmienne kultury jest stosowane dla danego typu (CultureInfo.InvariantCulture).
Nazwa i wartość parametru zapytania są zakodowane pod adresem URL.
Wszystkie wartości o pasującej nazwie parametru zapytania są zastępowane, jeśli istnieje wiele wystąpień typu.

Wywołanie GetUriWithQueryParameters metody w celu utworzenia identyfikatora URI utworzonego na podstawie Uri wielu parametrów z wieloma parametrami dodanymi, zaktualizowanymi lub usuniętymi. Dla każdej wartości struktura używa value?.GetType() metody do określania typu środowiska uruchomieniowego dla każdego parametru zapytania i wybiera prawidłowe formatowanie niezmienne kultury. Struktura zgłasza błąd dla nieobsługiwanych typów.

@inject NavigationManager Navigation

...

Navigation.GetUriWithQueryParameters({PARAMETERS})

Symbol {PARAMETERS} zastępczy to IReadOnlyDictionary<string, object>.

Przekaż ciąg identyfikatora URI, aby GetUriWithQueryParameters wygenerować nowy identyfikator URI z podanego identyfikatora URI z wieloma parametrami dodanymi, zaktualizowanymi lub usuniętymi. Dla każdej wartości struktura używa value?.GetType() metody do określania typu środowiska uruchomieniowego dla każdego parametru zapytania i wybiera prawidłowe formatowanie niezmienne kultury. Struktura zgłasza błąd dla nieobsługiwanych typów. Obsługiwane typy są wymienione w dalszej części tej sekcji.

@inject NavigationManager Navigation

...

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

Symbol {URI} zastępczy to identyfikator URI z ciągiem zapytania lub bez go.
Symbol {PARAMETERS} zastępczy to IReadOnlyDictionary<string, object>.

Obsługiwane typy są identyczne z obsługiwanymi typami ograniczeń tras:

bool
DateTime
decimal
double
float
Guid
int
long
string

Obsługiwane typy obejmują:

Warianty dopuszczające wartość null poprzednich typów.
Tablice powyższych typów, niezależnie od tego, czy są dopuszczane do wartości null, czy nie mogą być dopuszczane do wartości null.

Ostrzeżenie

Dzięki kompresji, która jest domyślnie włączona, unikaj tworzenia bezpiecznych (uwierzytelnionych/autoryzowanych) interaktywnych składników po stronie serwera, które renderuje dane z niezaufanych źródeł. Niezaufane źródła obejmują parametry trasy, ciągi zapytań, dane z JS międzyoperacyjności i inne źródło danych, które użytkownik innej firmy może kontrolować (bazy danych, usługi zewnętrzne). Aby uzyskać więcej informacji, zobacz Blazor po stronie serwera ASP.NET Core).

Zastąp wartość parametru zapytania, gdy parametr istnieje

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

Bieżący adres URL	Wygenerowany adres 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`

Dołączanie parametru zapytania i wartości, gdy parametr nie istnieje

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

Bieżący adres URL	Wygenerowany adres 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`

Usuwanie parametru zapytania, gdy wartość parametru jest `null`

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

Bieżący adres URL	Wygenerowany adres 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/`

Dodawanie, aktualizowanie i usuwanie parametrów zapytania

W poniższym przykładzie:

name zostanie usunięta, jeśli jest obecna.
age parametr jest dodawany z wartością 25 (int), jeśli nie istnieje. Jeśli jest obecny, age zostanie zaktualizowany do wartości 25.
eye color element jest dodawany lub aktualizowany do wartości green.

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

Bieżący adres URL	Wygenerowany adres 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`

Obsługa wartości wyliczalnych

W poniższym przykładzie:

full name element jest dodawany lub aktualizowany do Morena Baccarinpojedynczej wartości.
pingparametry są dodawane lub zastępowane parametrami 35, 1687 i 240.

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

Bieżący adres URL	Wygenerowany adres 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`

Nawigowanie za pomocą dodanego lub zmodyfikowanego ciągu zapytania

Aby nawigować za pomocą dodanego lub zmodyfikowanego ciągu zapytania, przekaż wygenerowany adres URL do .NavigateTo

Następujące przykładowe wywołania:

GetUriWithQueryParameter aby dodać lub zamienić name parametr zapytania przy użyciu wartości Morena Baccarin.
Wywołania NavigateTo wyzwalające nawigację do nowego adresu URL.

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

Ciąg zapytania żądania jest uzyskiwany z NavigationManager.Uri właściwości :

@inject NavigationManager Navigation

...

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

Aby przeanalizować parametry ciągu zapytania, jednym z podejść jest użycie URLSearchParams międzyoperacyjnościJSJavaScript ():

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

Aby uzyskać więcej informacji na temat izolacji języka JavaScript z modułami języka JavaScript, zobacz Wywoływanie funkcji Języka JavaScript z metod platformy .NET w programie ASP.NET Core Blazor.

Routing skrótu do nazwanych elementów

Przejdź do nazwanego elementu przy użyciu następujących metod z odwołaniem skrótu (#) do elementu. Trasy do elementów w składniku i trasy do elementów w składnikach zewnętrznych używają ścieżek względnych katalogu głównego. Ukośnik wiodący (/) jest opcjonalny.

Przykłady dla każdego z poniższych podejść pokazują nawigację do elementu z elementem idtargetElement w składniku Counter :

Element kotwicy (<a>) z elementem href:
```
<a href="/counter#targetElement">
```

NavLink składnik z elementem href:

<NavLink href="/counter#targetElement">

NavigationManager.NavigateTo Przekazywanie względnego adresu URL:
```
Navigation.NavigateTo("/counter#targetElement");
```

W poniższym przykładzie pokazano skrót routingu do nagłówków H2 w składniku i do składników zewnętrznych.

W składnikach Home (Home.razor) i Counter (Counter.razor) umieść następujące znaczniki u dołu istniejącego znacznika składnika, aby służyć jako elementy docelowe nawigacji. Funkcja <div> tworzy sztuczną przestrzeń pionową w celu zademonstrowania zachowania przewijania przeglądarki:

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

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

Dodaj następujący HashedRouting składnik do aplikacji.

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

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

Jeśli podczas nawigacji występuje znaczne opóźnienie, na przykład podczas ładowania zestawów z opóźnieniem w Blazor WebAssembly aplikacji lub w przypadku powolnego połączenia sieciowego z Blazor aplikacją po stronie serwera, Router składnik może wskazywać użytkownikowi, że następuje przejście strony.

W górnej części składnika, który określa Router składnik, dodaj dyrektywę @using dla Microsoft.AspNetCore.Components.Routing przestrzeni nazw:

@using Microsoft.AspNetCore.Components.Routing

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

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

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

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

Obsługa zdarzeń nawigacji asynchronicznej za pomocą polecenia `OnNavigateAsync`

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

Odwiedza trasę po raz pierwszy, przechodząc do niej bezpośrednio w przeglądarce.
Przechodzi do nowej trasy przy użyciu linku NavigationManager.NavigateTo lub wywołania.

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

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

Podczas prerenderingu na serwerze OnNavigateAsync jest wykonywane dwa razy:

Raz, gdy żądany składnik punktu końcowego jest początkowo renderowany statycznie.
Po raz drugi, gdy przeglądarka renderuje składnik punktu końcowego.

Aby zapobiec dwukrotnemu wykonaniu kodu OnNavigateAsync dewelopera, Routes składnik może przechowywać NavigationContext element do użycia w metodzieOnAfterRender{Async} cyklu życia, gdzie firstRender można to sprawdzić. Aby uzyskać więcej informacji, zobacz Prerendering with JavaScript interop (Wstępne używanie międzyoperacji języka JavaScript).

Aby zapobiec dwukrotnemu wykonywaniu kodu OnNavigateAsync dewelopera, App składnik może przechowywać element NavigationContext do użycia w programie OnAfterRender{Async}, gdzie firstRender można sprawdzić. Aby uzyskać więcej informacji, zobacz Prerendering with JavaScript interop (Wstępne używanie międzyoperacji języka JavaScript).

Obsługa anulowania w programie `OnNavigateAsync`

NavigationContext Obiekt przekazany do wywołania zwrotnego OnNavigateAsync zawiera element CancellationToken ustawiony, gdy wystąpi nowe zdarzenie nawigacji. Wywołanie OnNavigateAsync zwrotne musi zostać zgłoszony, gdy ten token anulowania jest ustawiony, aby uniknąć dalszego uruchamiania OnNavigateAsync wywołania zwrotnego w 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 metody , PostAsJsonAsyncco może anulować 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 przechodzi z dala od punktu końcowego /store .

@inject HttpClient Http
@inject ProductCatalog Products

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

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

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

@inject HttpClient Http
@inject ProductCatalog Products

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

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

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

Uwaga

Nie zgłaszaj, jeśli token anulowania w elemencie NavigationContext jest anulowany, może spowodować niezamierzone zachowanie, takie jak renderowanie składnika z poprzedniej nawigacji.

Obsługa/zapobieganie zmianom lokalizacji

RegisterLocationChangingHandler rejestruje program obsługi w celu przetwarzania przychodzących zdarzeń nawigacji. Kontekst programu obsługi udostępniany przez LocationChangingContext program zawiera następujące właściwości:

TargetLocation: Pobiera lokalizację docelową.
HistoryEntryState: pobiera stan skojarzony z wpisem historii docelowej.
IsNavigationIntercepted: pobiera, czy nawigacja została przechwycona z linku.
CancellationToken: pobiera element , CancellationToken aby określić, czy nawigacja została anulowana, na przykład w celu określenia, czy użytkownik wyzwolił inną nawigację.
PreventNavigation: wywoływana, aby uniemożliwić kontynuowanie nawigacji.

Składnik może zarejestrować wiele lokalizacji zmieniających programy obsługi w metodzie OnAfterRender{Async}cyklu życia. Nawigacja wywołuje wszystkie programy obsługi zmieniające lokalizacje zarejestrowane w całej aplikacji (w wielu składnikach), a każda nawigacja wewnętrzna wykonuje je wszystkie równolegle. Oprócz NavigateTo procedur obsługi są wywoływane:

Podczas wybierania linków wewnętrznych są to linki wskazujące adresy URL w ścieżce podstawowej aplikacji.
Podczas nawigowania za pomocą przycisków do przodu i wstecz w przeglądarce.

Programy obsługi są wykonywane tylko na potrzeby nawigacji wewnętrznej w aplikacji. Jeśli użytkownik wybierze link, który przejdzie do innej witryny lub ręcznie zmieni pasek adresu na inną witrynę, zmiany lokalizacji nie są wykonywane.

Zaimplementuj IDisposable i usuń zarejestrowane programy obsługi w celu ich wyrejestrowania. Aby uzyskać więcej informacji, zobacz Cykl życia składników platformy ASP.NET Core Razor.

Ważne

Nie próbuj wykonywać zadań oczyszczania MODELU DOM za pośrednictwem międzyoperacji języka JavaScript (JS) podczas obsługi zmian lokalizacji. MutationObserver Użyj wzorca w JS programie na kliencie. Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor JavaScript interoperability (JS interop).

W poniższym przykładzie program obsługi zmieniającej lokalizację jest rejestrowany dla zdarzeń nawigacji.

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

Ponieważ nawigacja wewnętrzna może zostać anulowana asynchronicznie, może wystąpić wiele nakładających się wywołań zarejestrowanych procedur obsługi. Na przykład wiele wywołań programu obsługi może wystąpić, gdy użytkownik szybko wybierze przycisk Wstecz na stronie lub wybierze wiele linków przed wykonaniem nawigacji. Poniżej przedstawiono podsumowanie logiki nawigacji asynchronicznej:

Jeśli jakiekolwiek lokalizacje zmieniające programy obsługi są zarejestrowane, wszystkie nawigacje są początkowo przywracane, a następnie odtwarzane, jeśli nawigacja nie zostanie anulowana.
W przypadku nakładania się żądań nawigacji najnowsze żądanie zawsze anuluje wcześniejsze żądania, co oznacza następujące kwestie:
- Aplikacja może traktować wiele opcji przycisków wstecz i do przodu jako pojedynczy wybór.
- Jeśli użytkownik wybierze wiele linków przed zakończeniem nawigacji, wybranie ostatniego linku określa nawigację.

Aby uzyskać więcej informacji na temat przekazywania NavigationOptions do NavigateTo wpisów i stanu stosu historii nawigacji, zobacz sekcję Opcje nawigacji.

Aby uzyskać dodatkowy przykładowy kod, zobacz element BasicTestApp.dotnet/aspnetcore

Uwaga

Linki dokumentacji do źródła referencyjnego platformy .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla bieżące programowanie dla następnej wersji platformy .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać tag wersji kodu źródłowego platformy ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Składnik NavigationLock przechwytuje zdarzenia nawigacji, o ile jest renderowany, skutecznie "blokowanie" danej nawigacji do momentu podjęcia decyzji o kontynuowaniu lub anulowaniu. Użyj NavigationLock funkcji , gdy przechwytywanie nawigacji może być ograniczone do okresu istnienia składnika.

NavigationLock Parametry:

ConfirmExternalNavigation Ustawia okno dialogowe przeglądarki, aby monitować użytkownika o potwierdzenie lub anulowanie nawigacji zewnętrznej. Domyślna wartość to false. Wyświetlenie okna dialogowego potwierdzenia wymaga początkowej interakcji użytkownika ze stroną przed wyzwoleniem nawigacji zewnętrznej za pomocą adresu URL na pasku adresu przeglądarki. Aby uzyskać więcej informacji na temat wymagań dotyczących interakcji, zobacz Okno: beforeunload zdarzenie (dokumentacja MDN).
OnBeforeInternalNavigation Ustawia wywołanie zwrotne dla wewnętrznych zdarzeń nawigacji.

W poniższym składniku NavLock:

Próba wykonania linku do witryny internetowej firmy Microsoft musi zostać potwierdzona przez użytkownika, zanim nawigacja zakończy się https://www.microsoft.com pomyślnie.
PreventNavigationPolecenie jest wywoływane, aby zapobiec wystąpieniu nawigacji, jeśli użytkownik odmówi potwierdzenia nawigacji za pośrednictwem wywołania międzyoperacyjnego języka JavaScript (JS), które zduplikuje confirm

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

Aby uzyskać dodatkowy przykładowy kod, zobacz ConfigurableNavigationLock składnik w BasicTestAppdotnet/aspnetcore źródle odwołania)..

`NavLink` cm6long

NavLink Podczas tworzenia linków nawigacyjnych użyj składnika zamiast elementów hiperłącza HTML (<a>). NavLink Składnik zachowuje się jak element, z wyjątkiem przełącza klasę <a>active CSS na podstawie tego, czy jest zgodny href z bieżącym adresem URL. Klasa active pomaga użytkownikowi zrozumieć, która strona jest aktywną stroną wśród wyświetlanych linków nawigacji. Opcjonalnie przypisz nazwę klasy CSS, aby NavLink.ActiveClass zastosować niestandardową klasę CSS do renderowanego linku, gdy bieżąca trasa jest zgodna z parametrem href.

Istnieją dwie NavLinkMatch opcje, które można przypisać do Match atrybutu <NavLink> elementu:

NavLinkMatch.All: wartość jest aktywna NavLink , gdy jest zgodna z całym bieżącym adresem URL.
NavLinkMatch.Prefix (ustawienie domyślne): wartość jest aktywna NavLink , gdy pasuje do dowolnego prefiksu bieżącego adresu URL.

W poprzednim przykładzie HomeNavLinkhref="" pasuje do adresu URL strony głównej i otrzymuje tylko klasę active CSS na domyślnej ścieżce podstawowej aplikacji (/). Drugi NavLink otrzymuje klasę active , gdy użytkownik odwiedza dowolny adres URL z prefiksem component (na przykład /component i /component/another-segment).

Dodatkowe NavLink atrybuty składnika są przekazywane do renderowanego tagu kotwicy. W poniższym przykładzie NavLink składnik zawiera target atrybut:

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

Renderowane są następujące znaczniki HTML:

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

Ostrzeżenie

Ze względu na sposób Blazor renderowania zawartości podrzędnej składniki renderowania NavLink wewnątrz for pętli wymagają lokalnej zmiennej indeksu, jeśli zmienna pętli przyrostowej jest używana w NavLink zawartości składnika (podrzędnego):

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

Użycie zmiennej indeksu w tym scenariuszu jest wymaganiem dla każdego składnika podrzędnego, który używa zmiennej pętli w zawartości podrzędnej, a nie tylko NavLink składnika.

Alternatywnie należy użyć pętli z poleceniem foreachEnumerable.Range:

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

NavLink wpisy składników można dynamicznie tworzyć na podstawie składników aplikacji za pośrednictwem odbicia. W poniższym przykładzie przedstawiono ogólne podejście do dalszego dostosowywania.

W przypadku następującej demonstracji dla składników aplikacji jest używana spójna, standardowa konwencja nazewnictwa:

Nazwy plików składników routable używają wielkości liter Pascal† na przykład Pages/ProductDetail.razor.
Ścieżki plików składników routable pasują do ich adresów URL w przypadku kebabu} z łącznikami wyświetlanymi między wyrazami w szablonie trasy składnika. Na przykład składnik ProductDetail z szablonem trasy /product-detail (@page "/product-detail") jest żądany w przeglądarce pod względnym adresem URL /product-detail.

†Wielkość liter zgodna z językiem Pascal (nazwy z wyrazami pisanymi wielkimi literami) to konwencja nazewnictwa bez spacji i interpunkcji, gdzie każdy wyraz zaczyna się wielką literą, włącznie z pierwszym wyrazem.
{Przypadek Kebab to konwencja nazewnictwa bez spacji i znaków interpunkcyjnych, która używa małych liter i kreski między wyrazami.

W znacznikach RazorNavMenu składnika (NavMenu.razor) na stronie Home domyślnej NavLink składniki są dodawane z kolekcji:

<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 w @code bloku:

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

Powyższy przykład nie zawiera następujących stron na renderowanej liście składników:

Home page: Strona jest wyświetlana oddzielnie od automatycznie wygenerowanych linków, ponieważ powinna być wyświetlana w górnej części listy i ustawić Match parametr.
Error page: Strona błędu jest przechodzina tylko do platformy i nie powinna być wyświetlana.

Przykład poprzedniego kodu w przykładowej aplikacji, którą można uruchomić lokalnie, uzyskaj Blazor WebAssembly lub przykładową.

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

Ta sekcja dotyczy Blazor Web Appoperacji na obwodzie.

Ta sekcja dotyczy Blazor Server aplikacji.

Element A Blazor Web App jest zintegrowany z ASP.NET podstawowym routingiem punktów końcowych. Aplikacja ASP.NET Core jest skonfigurowana do akceptowania połączeń przychodzących dla składników MapRazorComponents interakcyjnych w Program pliku. Domyślny składnik główny (pierwszy załadowany składnik) to App składnik (App.razor):

app.MapRazorComponents<App>();

Blazor Server jest zintegrowany z routingiem punktów końcowych platformy ASP.NET Core. Aplikacja ASP.NET Core jest skonfigurowana do akceptowania połączeń przychodzących dla składników MapBlazorHub interaktywnych w Program pliku :

app.UseRouting();

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

Typowa konfiguracja polega na kierowaniu wszystkich żądań do Razor strony, która działa jako host dla części Blazor Server aplikacji po stronie serwera. Zgodnie z konwencją strona hosta jest zwykle nazwana _Host.cshtml w Pages folderze aplikacji.

Trasa określona w pliku hosta jest nazywana trasą rezerwową, ponieważ działa z niskim priorytetem w dopasowywaniu tras. Trasa rezerwowa jest używana, gdy inne trasy nie są zgodne. Dzięki temu aplikacja może korzystać z innych kontrolerów i stron bez zakłócania routingu Blazor Server składników w aplikacji.

Aby uzyskać informacje na temat konfigurowania hostowania MapFallbackToPage serwera adresu URL innego niż główny, zobacz Host and deploy ASP.NET Core Blazor.

Udostępnij za pośrednictwem

ASP.NET Core Blazor routingu i nawigacji

Routing statyczny i interakcyjny

Szablony tras

Skupienie elementu na nawigacji

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

Kierowanie do składników z wielu zestawów

Routing statyczny

Routing interaktywny

Parametry tras

Ograniczenia trasy

Unikanie przechwytywania plików w parametrze trasy

Routing z adresami URL zawierającymi kropki

Parametry trasy catch-all

Pomocnicy identyfikatora URI i stanu nawigacji

Zmiany lokalizacji

Ulepszona nawigacja i obsługa formularzy

Tworzenie identyfikatora URI względem prefiksu podstawowego identyfikatora URI

Stan historii nawigacji

Opcje nawigacji

Ciągi zapytań

Zastąp wartość parametru zapytania, gdy parametr istnieje

Dołączanie parametru zapytania i wartości, gdy parametr nie istnieje

Usuwanie parametru zapytania, gdy wartość parametru jest `null`

Dodawanie, aktualizowanie i usuwanie parametrów zapytania

Obsługa wartości wyliczalnych

Nawigowanie za pomocą dodanego lub zmodyfikowanego ciągu zapytania

Routing skrótu do nazwanych elementów

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

Obsługa zdarzeń nawigacji asynchronicznej za pomocą polecenia `OnNavigateAsync`

Obsługa anulowania w programie `OnNavigateAsync`

Obsługa/zapobieganie zmianom lokalizacji

`NavLink` cm6long

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

Dodatkowe zasoby

Udostępnij za pośrednictwem

ASP.NET Core Blazor routingu i nawigacji

Routing statyczny i interakcyjny

Szablony tras

Skupienie elementu na nawigacji

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

Kierowanie do składników z wielu zestawów

Routing statyczny

Routing interaktywny

Parametry tras

Ograniczenia trasy

Unikanie przechwytywania plików w parametrze trasy

Routing z adresami URL zawierającymi kropki

Parametry trasy catch-all

Pomocnicy identyfikatora URI i stanu nawigacji

Zmiany lokalizacji

Ulepszona nawigacja i obsługa formularzy

Tworzenie identyfikatora URI względem prefiksu podstawowego identyfikatora URI

Stan historii nawigacji

Opcje nawigacji

Ciągi zapytań

Zastąp wartość parametru zapytania, gdy parametr istnieje

Dołączanie parametru zapytania i wartości, gdy parametr nie istnieje

Usuwanie parametru zapytania, gdy wartość parametru jest null

Dodawanie, aktualizowanie i usuwanie parametrów zapytania

Obsługa wartości wyliczalnych

Nawigowanie za pomocą dodanego lub zmodyfikowanego ciągu zapytania

Routing skrótu do nazwanych elementów

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

Obsługa zdarzeń nawigacji asynchronicznej za pomocą polecenia OnNavigateAsync

Obsługa anulowania w programie OnNavigateAsync

Obsługa/zapobieganie zmianom lokalizacji

NavLink cm6long

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

Dodatkowe zasoby

Usuwanie parametru zapytania, gdy wartość parametru jest `null`

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

Obsługa zdarzeń nawigacji asynchronicznej za pomocą polecenia `OnNavigateAsync`

Obsługa anulowania w programie `OnNavigateAsync`

`NavLink` cm6long