Bagikan melalui

perutean dan navigasi inti Blazor ASP.NET

  • Artikel

Catatan

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Penting

Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Artikel ini menjelaskan cara mengelola Blazor perutean permintaan aplikasi dan cara menggunakan NavLink komponen untuk membuat tautan navigasi.

Penting

Contoh kode di seluruh artikel ini menunjukkan metode yang dipanggil pada Navigation, yang merupakan disuntikkan NavigationManager di kelas dan komponen.

Perutean statis versus interaktif

Bagian ini berlaku untuk Blazor Web Apps.

Jika pra-penyajian tidak dinonaktifkan, Blazor router (Router komponen, <Router> dalam Routes.razor) melakukan perutean statis ke komponen selama penyajian sisi server statis (SSR statis). Jenis perutean ini disebut perutean statis.

Ketika mode render interaktif ditetapkan ke Routes komponen, Blazor router menjadi interaktif setelah SSR statis dengan perutean statis di server. Jenis perutean ini disebut perutean interaktif.

Router statis menggunakan perutean titik akhir dan jalur permintaan HTTP untuk menentukan komponen mana yang akan dirender. Ketika router menjadi interaktif, router menggunakan URL dokumen (URL di bilah alamat browser) untuk menentukan komponen mana yang akan dirender. Ini berarti bahwa router interaktif dapat secara dinamis mengubah komponen mana yang dirender jika URL dokumen berubah secara dinamis ke URL internal lain yang valid, dan dapat melakukannya tanpa melakukan permintaan HTTP untuk mengambil konten halaman baru.

Perutean interaktif juga mencegah prarender karena konten halaman baru tidak diminta dari server dengan permintaan halaman normal. Untuk informasi selengkapnya, lihat Prarender komponen ASP.NET CoreRazor.

Templat rute

Komponen ini Router memungkinkan perutean ke Razor komponen dan terletak di komponen aplikasi Routes (Components/Routes.razor).

Komponen memungkinkan Router perutean ke Razor komponen. Komponen Router digunakan dalam App komponen (App.razor).

Razor Ketika komponen (.razor) dengan direktif@page dikompilasi, kelas komponen yang dihasilkan disediakan yang RouteAttribute menentukan templat rute komponen.

Ketika aplikasi dimulai, rakitan yang ditentukan sebagai Router AppAssembly dipindai untuk mengumpulkan informasi rute untuk komponen aplikasi yang memiliki RouteAttribute.

Pada runtime, RouteView komponen:

  • RouteData Menerima dari Router bersama dengan parameter rute apa pun.
  • Merender komponen yang ditentukan dengan tata letaknya, termasuk tata letak berlapis lebih lanjut.

Secara opsional tentukan DefaultLayout parameter dengan kelas tata letak untuk komponen yang tidak menentukan tata letak dengan direktif@layout. Templat proyek kerangka kerjaBlazormenentukan MainLayout komponen (MainLayout.razor) sebagai tata letak default aplikasi. Untuk informasi selengkapnya tentang tata letak, lihat tata letak ASP.NET CoreBlazor.

Komponen mendukung beberapa templat rute menggunakan beberapa @page arahan. Contoh komponen berikut dimuat pada permintaan untuk /blazor-route dan /different-blazor-route.

BlazorRoute.razor:

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

<PageTitle>Routing</PageTitle>

<h1>Routing Example</h1>

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

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

<h1>Blazor routing</h1>

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

<h1>Blazor routing</h1>

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

<h1>Blazor routing</h1>

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

<h1>Blazor routing</h1>

Penting

Agar URL diselesaikan dengan benar, aplikasi harus menyertakan <base> tag (lokasi <head> konten) dengan jalur dasar aplikasi yang ditentukan dalam href atribut . Untuk informasi selengkapnya, lihat Host dan sebarkan ASP.NET Core Blazor.

Router tidak berinteraksi dengan nilai string kueri. Untuk bekerja dengan string kueri, lihat bagian String kueri .

Sebagai alternatif untuk menentukan templat rute sebagai string literal dengan @page direktif, templat rute berbasis konstan dapat ditentukan dengan direktif@attribute.

Dalam contoh berikut, arahan @page dalam komponen diganti dengan @attribute direktif dan templat rute berbasis konstanta di Constants.CounterRoute, yang diatur di tempat lain di aplikasi ke "/counter":

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

Catatan

Dengan rilis ASP.NET Core 5.0.1 dan untuk rilis 5.x tambahan, komponen Router menyertakan parameter PreferExactMatches yang diatur ke @true. Untuk informasi lebih lanjut, lihat Migrasi dari ASP.NET Core 3.1 ke 5.0.

Memfokuskan elemen pada navigasi

Komponen FocusOnNavigate mengatur fokus UI ke elemen berdasarkan pemilih CSS setelah menavigasi dari satu halaman ke halaman lainnya.

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

Router Saat komponen menavigasi ke halaman baru, FocusOnNavigate komponen mengatur fokus ke header tingkat atas halaman (<h1>). Ini adalah strategi umum untuk memastikan bahwa navigasi halaman diumumkan saat menggunakan pembaca layar.

Sediakan konten kustom saat konten tidak ditemukan

Komponen ini Router memungkinkan aplikasi menentukan konten kustom jika konten tidak ditemukan untuk rute yang diminta.

Atur Router konten kustom untuk parameter komponen NotFound :

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

Item arbitrer didukung sebagai konten NotFound parameter, seperti komponen interaktif lainnya. Untuk menerapkan tata letak default ke NotFound konten, lihat tata letak ASP.NET CoreBlazor.

Penting

Blazor Web Apps tidak menggunakan NotFound parameter (<NotFound>...</NotFound> markup), tetapi parameter didukung untuk kompatibilitas mundur untuk menghindari perubahan yang melanggar dalam kerangka kerja. Sisi server ASP.NET alur middleware Core memproses permintaan di server. Gunakan teknik sisi server untuk menangani permintaan buruk. Untuk informasi selengkapnya, lihat mode render ASP.NET CoreBlazor.

Merutekan ke komponen dari beberapa rakitan

Bagian ini berlaku untuk Blazor Web Apps.

Router Gunakan parameter komponen AdditionalAssemblies dan penyusun AddAdditionalAssemblies konvensi titik akhir untuk menemukan komponen yang dapat dirutekan dalam rakitan tambahan. Sub bagian berikut menjelaskan kapan dan bagaimana menggunakan setiap API.

Perutean statik

Untuk menemukan komponen yang dapat dirutekan dari rakitan tambahan untuk penyajian sisi server statis (SSR statis), bahkan jika router nantinya menjadi interaktif untuk penyajian interaktif, rakitan harus diungkapkan ke Blazor kerangka kerja. AddAdditionalAssemblies Panggil metode dengan rakitan tambahan yang ditautkan ke MapRazorComponents dalam file proyek Program server.

Contoh berikut mencakup komponen yang dapat dirutekan dalam perakitan BlazorSample.Client proyek menggunakan file proyek _Imports.razor :

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

Catatan

Panduan sebelumnya juga berlaku dalam skenario pustaka kelas komponen. Panduan penting tambahan untuk pustaka kelas dan SSR statis ditemukan di pustaka kelas inti Razor (RCL) ASP.NET dengan penyajian sisi server statis (SSR statis).

Perutean interaktif

Mode render interaktif dapat ditetapkan ke Routes komponen (Routes.razor) yang membuat Blazor router menjadi interaktif setelah SSR statis dan perutean statis di server. Misalnya, <Routes @rendermode="InteractiveServer" /> menetapkan penyajian sisi server interaktif (SSR interaktif) ke Routes komponen. Komponen Router mewarisi penyajian sisi server interaktif (SSR interaktif) dari Routes komponen. Router menjadi interaktif setelah perutean statis di server.

Navigasi internal untuk perutean interaktif tidak melibatkan permintaan konten halaman baru dari server. Oleh karena itu, pra-penyajian tidak terjadi untuk permintaan halaman internal. Untuk informasi selengkapnya, lihat Prarender komponen ASP.NET CoreRazor.

Routes Jika komponen didefinisikan dalam proyek server, AdditionalAssemblies parameter Router komponen harus menyertakan perakitan .Client proyek. Ini memungkinkan perute bekerja dengan benar ketika dirender secara interaktif.

Dalam contoh berikut, Routes komponen berada dalam proyek server, dan _Imports.razor file BlazorSample.Client proyek menunjukkan perakitan untuk mencari komponen yang dapat dirutekan:

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

Rakitan tambahan dipindai selain rakitan yang ditentukan ke AppAssembly.

Catatan

Panduan sebelumnya juga berlaku dalam skenario pustaka kelas komponen.

Atau, komponen yang dapat dirutekan hanya ada dalam .Client proyek dengan Interaktif WebAssembly global atau Rendering otomatis yang diterapkan, dan Routes komponen didefinisikan dalam .Client proyek, bukan proyek server. Dalam hal ini, tidak ada rakitan eksternal dengan komponen yang dapat dirutekan, sehingga tidak perlu menentukan nilai untuk AdditionalAssemblies.

Bagian ini berlaku untuk Blazor Server aplikasi.

Router Gunakan parameter komponen AdditionalAssemblies dan penyusun AddAdditionalAssemblies konvensi titik akhir untuk menemukan komponen yang dapat dirutekan dalam rakitan tambahan.

Dalam contoh berikut, Component1 adalah komponen yang dapat dirutekan yang ditentukan dalam pustaka kelas komponen yang dirujuk bernama ComponentLibrary:

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

Rakitan tambahan dipindai selain rakitan yang ditentukan ke AppAssembly.

Parameter rute

Router menggunakan parameter rute untuk mengisi parameter komponen yang sesuai dengan nama yang sama. Nama parameter rute tidak peka huruf besar/kecil. Dalam contoh berikut, text parameter menetapkan nilai segmen rute ke properti komponen Text . Ketika permintaan dibuat untuk /route-parameter-1/amazing, konten dirender sebagai Blazor is amazing!.

RouteParameter1.razor:

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

<PageTitle>Route Parameter 1</PageTitle>

<h1>Route Parameter Example 1</h1>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Parameter opsional didukung. Dalam contoh berikut, parameter opsional text menetapkan nilai segmen rute ke properti Text komponen. Jika segmen tidak ada, nilai Text diatur ke fantastic.

Parameter opsional tidak didukung. Dalam contoh berikut, dua @page arahan diterapkan. Direktif pertama mengizinkan navigasi ke komponen tanpa parameter. Direktif kedua menetapkan {text} nilai parameter rute ke properti komponen Text .

RouteParameter2.razor:

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

<PageTitle>Route Parameter 2</PageTitle>

<h1>Route Parameter Example 2</h1>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

OnInitialized{Async} Ketika metode digunakan alih-alih OnParametersSet, penetapan Text default properti fantastic tidak terjadi jika pengguna menavigasi dalam komponen yang sama. Misalnya, situasi ini muncul ketika pengguna menavigasi dari /route-parameter-2/amazing ke /route-parameter-2. Saat instans komponen bertahan dan menerima parameter baru, OnInitialized metode tidak dipanggil lagi.

Catatan

Parameter rute tidak berfungsi dengan nilai string kueri. Untuk bekerja dengan string kueri, lihat bagian String kueri .

Batasan rute

Batasan rute memberlakukan pencocokan jenis pada segmen rute ke komponen.

Dalam contoh berikut, rute ke User komponen hanya cocok jika:

  • Id Segmen rute ada di URL permintaan.
  • Segmen Id adalah jenis bilangan bulat (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; }
}

Catatan

Batasan rute tidak berfungsi dengan nilai string kueri. Untuk bekerja dengan string kueri, lihat bagian String kueri .

Batasan rute yang diperlihatkan dalam tabel berikut ini tersedia. Untuk batasan rute yang cocok dengan budaya invarian, lihat peringatan di bawah tabel untuk informasi selengkapnya.

Batasan Contoh Contoh Kecocokan Invarian
budaya
Pencocokan
bool {active:bool} true, FALSE No
datetime {dob:datetime} 2016-12-31, 2016-12-31 7:32pm Ya
decimal {price:decimal} 49.99, -1,000.01 Ya
double {weight:double} 1.234, -1,001.01e8 Ya
float {weight:float} 1.234, -1,001.01e8 Ya
guid {id:guid} CD2C1638-1638-72D5-1638-DEADBEEF1638, {CD2C1638-1638-72D5-1638-DEADBEEF1638} No
int {id:int} 123456789, -123456789 Ya
long {ticks:long} 123456789, -123456789 Ya

Peringatan

Batasan rute yang memverifikasi URL dan dikonversi ke jenis CLR (seperti int atau DateTime) selalu menggunakan budaya yang invarian. Batasan ini mengasumsikan bahwa URL tidak dapat dilokalkan.

Batasan rute juga berfungsi dengan parameter opsional. Dalam contoh berikut, Id diperlukan, tetapi Option merupakan parameter rute boolean opsional.

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

Perutean dengan URL yang berisi titik-titik

Templat rute default sisi server mengasumsikan bahwa jika segmen terakhir URL permintaan berisi titik (.) yang diminta file. Misalnya, URL /example/some.thing relatif ditafsirkan oleh router sebagai permintaan untuk file bernama some.thing. Tanpa konfigurasi tambahan, aplikasi mengembalikan respons 404 - Tidak Ditemukan jika some.thing dimaksudkan untuk merutekan ke komponen dengan @page direktif dan some.thing merupakan nilai parameter rute. Untuk menggunakan rute dengan satu atau beberapa parameter yang berisi titik, aplikasi harus mengonfigurasi rute dengan templat kustom.

Pertimbangkan komponen berikut Example yang dapat menerima parameter rute dari segmen terakhir 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; }
}

Untuk mengizinkan aplikasi solusi yang dihosting Server untuk merutekanBlazor WebAssembly permintaan dengan titik di param parameter rute, tambahkan templat rute file fallback dengan parameter opsional dalam Program file:

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

Untuk mengonfigurasi Blazor Server aplikasi untuk merutekan permintaan dengan titik di param parameter rute, tambahkan templat rute halaman fallback dengan parameter opsional dalam Program file:

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

Untuk informasi lebih lanjut, lihat Perutean di ASP.NET Core.

Untuk mengizinkan aplikasi solusi yang dihosting Server untuk merutekan Blazor WebAssemblypermintaan dengan titik di param parameter rute, tambahkan templat rute file fallback dengan parameter opsional di Startup.Configure.

Startup.cs:

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

Untuk mengonfigurasi Blazor Server aplikasi untuk merutekan permintaan dengan titik di param parameter rute, tambahkan templat rute halaman fallback dengan parameter opsional di Startup.Configure.

Startup.cs:

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

Untuk informasi lebih lanjut, lihat Perutean di ASP.NET Core.

Parameter rute catch-all

Parameter rute catch-all, yang mengambil jalur di beberapa batas folder, didukung dalam komponen.

Parameter rute catch-all adalah:

  • Dinamai agar sesuai dengan nama segmen rute. Penamaan tidak peka huruf besar/kecil.
  • Jenis string . Kerangka kerja tidak menyediakan transmisi otomatis.
  • Di akhir URL.

CatchAll.razor:

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

<PageTitle>Catch All</PageTitle>

<h1>Catch All Parameters Example</h1>

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

<p>
    PageRoute: @PageRoute
</p>

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

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

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

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

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

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

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

Untuk URL /catch-all/this/is/a/test dengan templat /catch-all/{*pageRoute}rute , nilai PageRoute diatur ke this/is/a/test.

Garis miring dan segmen jalur yang diambil didekodekan. Untuk templat /catch-all/{*pageRoute}rute , URL /catch-all/this/is/a%2Ftest%2A menghasilkan this/is/a/test*.

URI dan pembantu status navigasi

Gunakan NavigationManager untuk mengelola URI dan navigasi dalam kode C#. NavigationManager menyediakan peristiwa dan metode yang diperlihatkan dalam tabel berikut.

Anggota Deskripsi
Uri Mendapatkan URI absolut saat ini.
BaseUri Mendapatkan URI dasar (dengan garis miring berikutnya) yang dapat didahului ke jalur URI relatif untuk menghasilkan URI absolut. Biasanya, BaseUri sesuai dengan href atribut pada elemen dokumen <base> (lokasi <head> konten).
NavigateTo Menavigasi ke URI yang ditentukan. Jika forceLoad adalah false:
  • Dan navigasi yang ditingkatkan tersedia di URL saat ini, Blazornavigasi yang ditingkatkan diaktifkan.
  • Jika tidak, Blazor lakukan pemuatan ulang halaman penuh untuk URL yang diminta.
Jika forceLoad adalah true:
  • Perutean sisi klien dilewati.
  • Browser dipaksa untuk memuat halaman baru dari server, apakah URI biasanya ditangani oleh router interaktif sisi klien atau tidak.

Untuk informasi selengkapnya, lihat bagian Navigasi dan penanganan formulir yang disempurnakan.

Jika replace adalah true, URI saat ini dalam riwayat browser diganti alih-alih mendorong URI baru ke tumpukan riwayat.
LocationChanged Peristiwa yang diaktifkan saat lokasi navigasi telah berubah. Untuk informasi selengkapnya, lihat bagian Perubahan lokasi.
ToAbsoluteUri Mengonversi URI relatif menjadi URI absolut.
ToBaseRelativePath Berdasarkan URI dasar aplikasi, mengonversi URI absolut menjadi URI relatif terhadap awalan URI dasar. Misalnya, lihat bagian Menghasilkan URI relatif terhadap awalan URI dasar.
RegisterLocationChangingHandler Mendaftarkan handler untuk memproses peristiwa navigasi masuk. Panggilan NavigateTo selalu memanggil handler.
GetUriWithQueryParameter Mengembalikan URI yang dibangun dengan memperbarui NavigationManager.Uri dengan parameter tunggal yang ditambahkan, diperbarui, atau dihapus. Untuk informasi selengkapnya, lihat bagian String kueri .
Anggota Deskripsi
Uri Mendapatkan URI absolut saat ini.
BaseUri Mendapatkan URI dasar (dengan garis miring berikutnya) yang dapat didahului ke jalur URI relatif untuk menghasilkan URI absolut. Biasanya, BaseUri sesuai dengan href atribut pada elemen dokumen <base> (lokasi <head> konten).
NavigateTo Menavigasi ke URI yang ditentukan. Jika forceLoad adalah true:
  • Perutean sisi klien dilewati.
  • Browser dipaksa untuk memuat halaman baru dari server, apakah URI biasanya ditangani oleh router sisi klien atau tidak.
Jika replace adalah true, URI saat ini dalam riwayat browser diganti alih-alih mendorong URI baru ke tumpukan riwayat.
LocationChanged Peristiwa yang diaktifkan saat lokasi navigasi telah berubah. Untuk informasi selengkapnya, lihat bagian Perubahan lokasi.
ToAbsoluteUri Mengonversi URI relatif menjadi URI absolut.
ToBaseRelativePath Berdasarkan URI dasar aplikasi, mengonversi URI absolut menjadi URI relatif terhadap awalan URI dasar. Misalnya, lihat bagian Menghasilkan URI relatif terhadap awalan URI dasar.
RegisterLocationChangingHandler Mendaftarkan handler untuk memproses peristiwa navigasi masuk. Panggilan NavigateTo selalu memanggil handler.
GetUriWithQueryParameter Mengembalikan URI yang dibangun dengan memperbarui NavigationManager.Uri dengan parameter tunggal yang ditambahkan, diperbarui, atau dihapus. Untuk informasi selengkapnya, lihat bagian String kueri .
Anggota Deskripsi
Uri Mendapatkan URI absolut saat ini.
BaseUri Mendapatkan URI dasar (dengan garis miring berikutnya) yang dapat didahului ke jalur URI relatif untuk menghasilkan URI absolut. Biasanya, BaseUri sesuai dengan href atribut pada elemen dokumen <base> (lokasi <head> konten).
NavigateTo Menavigasi ke URI yang ditentukan. Jika forceLoad adalah true:
  • Perutean sisi klien dilewati.
  • Browser dipaksa untuk memuat halaman baru dari server, apakah URI biasanya ditangani oleh router sisi klien atau tidak.
Jika replace adalah true, URI saat ini dalam riwayat browser diganti alih-alih mendorong URI baru ke tumpukan riwayat.
LocationChanged Peristiwa yang diaktifkan saat lokasi navigasi telah berubah. Untuk informasi selengkapnya, lihat bagian Perubahan lokasi.
ToAbsoluteUri Mengonversi URI relatif menjadi URI absolut.
ToBaseRelativePath Berdasarkan URI dasar aplikasi, mengonversi URI absolut menjadi URI relatif terhadap awalan URI dasar. Misalnya, lihat bagian Menghasilkan URI relatif terhadap awalan URI dasar.
GetUriWithQueryParameter Mengembalikan URI yang dibangun dengan memperbarui NavigationManager.Uri dengan parameter tunggal yang ditambahkan, diperbarui, atau dihapus. Untuk informasi selengkapnya, lihat bagian String kueri .
Anggota Deskripsi
Uri Mendapatkan URI absolut saat ini.
BaseUri Mendapatkan URI dasar (dengan garis miring berikutnya) yang dapat didahului ke jalur URI relatif untuk menghasilkan URI absolut. Biasanya, BaseUri sesuai dengan href atribut pada elemen dokumen <base> (lokasi <head> konten).
NavigateTo Menavigasi ke URI yang ditentukan. Jika forceLoad adalah true:
  • Perutean sisi klien dilewati.
  • Browser dipaksa untuk memuat halaman baru dari server, apakah URI biasanya ditangani oleh router sisi klien atau tidak.
LocationChanged Peristiwa yang diaktifkan saat lokasi navigasi telah berubah.
ToAbsoluteUri Mengonversi URI relatif menjadi URI absolut.
ToBaseRelativePath Berdasarkan URI dasar aplikasi, mengonversi URI absolut menjadi URI relatif terhadap awalan URI dasar. Misalnya, lihat bagian Menghasilkan URI relatif terhadap awalan URI dasar.

Perubahan lokasi

Untuk peristiwa tersebut LocationChanged , LocationChangedEventArgs berikan informasi berikut tentang peristiwa navigasi:

Komponen berikut:

  • Navigasi ke komponen aplikasi Counter (Counter.razor) saat tombol dipilih menggunakan NavigateTo.
  • Menangani peristiwa yang diubah lokasi dengan berlangganan ke NavigationManager.LocationChanged.

    • Metode HandleLocationChanged ini tidak terkait ketika Dispose dipanggil oleh kerangka kerja. Melepas kait metode memungkinkan pengumpulan sampah komponen.

    • Implementasi pencatat mencatat informasi berikut saat tombol dipilih:

      BlazorSample.Pages.Navigate: Information: URL of new location: https://localhost:{PORT}/counter

Navigate.razor:

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

<PageTitle>Navigate</PageTitle>

<h1>Navigate Example</h1>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Untuk informasi selengkapnya tentang pembuangan komponen, lihat siklus hidup komponen ASP.NET CoreRazor.

Navigasi dan penanganan formulir yang disempurnakan

Bagian ini berlaku untuk Blazor Web Apps.

Blazor Web Apps mampu melakukan dua jenis perutean untuk navigasi halaman dan permintaan penanganan formulir:

  • Navigasi normal (navigasi lintas dokumen): pemuatan ulang halaman penuh dipicu untuk URL permintaan.
  • Navigasi yang ditingkatkan (navigasi dokumen yang sama): Blazor mencegat permintaan dan melakukan fetch permintaan sebagai gantinya. Blazor lalu patch konten respons ke dalam DOM halaman. BlazorNavigasi dan penanganan formulir yang disempurnakan menghindari kebutuhan untuk memuat ulang halaman penuh dan mempertahankan lebih banyak status halaman, sehingga halaman dimuat lebih cepat, biasanya tanpa kehilangan posisi gulir pengguna di halaman.

Navigasi yang ditingkatkan tersedia ketika:

  • Blazor Skrip Aplikasi Web (blazor.web.js) digunakan, bukan Blazor Server skrip (blazor.server.js) atau Blazor WebAssembly skrip (blazor.webassembly.js).
  • Fitur ini tidak dinonaktifkan secara eksplisit.
  • URL tujuan berada dalam ruang URI dasar internal (jalur dasar aplikasi).

Jika perutean sisi server dan navigasi yang ditingkatkan diaktifkan, penangan perubahan lokasi hanya dipanggil untuk navigasi terprogram yang dimulai dari runtime interaktif. Dalam rilis mendatang, jenis navigasi tambahan, seperti mengikuti tautan, juga dapat memanggil penangan perubahan lokasi.

Ketika navigasi yang ditingkatkan terjadi, LocationChanged penanganan aktivitas yang terdaftar di Interactive Server dan runtime WebAssembly biasanya dipanggil. Ada kasus ketika penangan perubahan lokasi mungkin tidak mencegat navigasi yang ditingkatkan. Misalnya, pengguna mungkin beralih ke halaman lain sebelum runtime interaktif tersedia. Oleh karena itu, penting bahwa logika aplikasi tidak mengandalkan pemanggilan lokasi yang mengubah handler, karena tidak ada jaminan handler yang dijalankan.

Saat memanggil NavigateTo:

  • Jika forceLoad adalah false, yang merupakan default:
    • Dan navigasi yang ditingkatkan tersedia di URL saat ini, Blazornavigasi yang ditingkatkan diaktifkan.
    • Jika tidak, Blazor lakukan pemuatan ulang halaman penuh untuk URL yang diminta.
  • Jika forceLoad adalah true: Blazor melakukan pemuatan ulang halaman penuh untuk URL yang diminta, apakah navigasi yang ditingkatkan tersedia atau tidak.

Anda dapat menyegarkan halaman saat ini dengan memanggil NavigationManager.Refresh(bool forceLoad = false), yang selalu melakukan navigasi yang ditingkatkan, jika tersedia. Jika navigasi yang disempurnakan tidak tersedia, Blazor lakukan pemuatan ulang halaman penuh.

Navigation.Refresh();

Teruskan true ke forceLoad parameter untuk memastikan pemuatan ulang halaman penuh selalu dilakukan, bahkan jika navigasi yang ditingkatkan tersedia:

Navigation.Refresh(true);

Navigasi yang ditingkatkan diaktifkan secara default, tetapi dapat dikontrol secara hierarkis dan berdasarkan per tautan menggunakan data-enhance-nav atribut HTML.

Contoh berikut menonaktifkan navigasi yang ditingkatkan:

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

Jika tujuan adalah titik akhir non-Blazor , navigasi yang disempurnakan tidak berlaku, dan JavaScript sisi klien mencoba kembali sebagai pemuatan halaman penuh. Ini memastikan tidak ada kebingungan dengan kerangka kerja tentang halaman eksternal yang seharusnya tidak di-patch ke halaman yang ada.

Untuk mengaktifkan penanganan formulir yang ditingkatkan Enhance , tambahkan parameter ke EditForm formulir atau data-enhance atribut ke formulir HTML (<form>):

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

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

Penanganan formulir yang disempurnakan tidak hierarkis dan tidak mengalir ke formulir anak:

Anda tidak dapat mengatur navigasi yang ditingkatkan pada elemen leluhur formulir untuk mengaktifkan navigasi yang disempurnakan untuk formulir.

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

Posting formulir yang disempurnakan hanya berfungsi dengan Blazor titik akhir. Memposting formulir yang disempurnakan ke non-titikBlazor akhir menghasilkan kesalahan.

Untuk menonaktifkan navigasi yang disempurnakan:

  • EditFormUntuk , hapus Enhance parameter dari elemen formulir (atau atur ke false: Enhance="false").
  • Untuk HTML <form>, hapus data-enhance atribut dari elemen formulir (atau atur ke false: data-enhance="false").

BlazorNavigasi dan penyerahan formulir yang disempurnakan dapat membatalkan perubahan dinamis pada DOM jika konten yang diperbarui bukan bagian dari penyajian server. Untuk mempertahankan konten elemen, gunakan data-permanent atribut .

Dalam contoh berikut, konten elemen diperbarui <div> secara dinamis oleh skrip saat halaman dimuat:

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

Setelah Blazor dimulai pada klien, Anda dapat menggunakan enhancedload peristiwa untuk mendengarkan pembaruan halaman yang disempurnakan. Hal ini memungkinkan penerapan ulang perubahan pada DOM yang mungkin telah dibatalkan oleh pembaruan halaman yang disempurnakan.

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

Untuk menonaktifkan navigasi dan penanganan formulir yang disempurnakan secara global, lihat startup ASP.NET CoreBlazor.

Navigasi yang ditingkatkan dengan penyajian sisi server statis (SSR statis) memerlukan perhatian khusus saat memuat JavaScript. Untuk informasi selengkapnya, lihat ASP.NET Core Blazor JavaScript dengan penyajian sisi server statis (SSR statis).

Menghasilkan URI relatif terhadap awalan URI dasar

Berdasarkan URI dasar aplikasi, ToBaseRelativePath mengonversi URI absolut menjadi URI relatif terhadap awalan URI dasar.

Pertimbangkan contoh berikut:

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

Jika URI dasar aplikasi adalah https://localhost:8000, hasil berikut diperoleh:

  • Meneruskan https://localhost:8000/segment hasil inputURI dalam satu baseRelativePath dari segment.
  • Meneruskan https://localhost:8000/segment1/segment2 hasil inputURI dalam satu baseRelativePath dari segment1/segment2.

Jika URI dasar aplikasi tidak cocok dengan URI dasar , ArgumentException URI inputURIakan dilemparkan.

Meneruskan https://localhost:8001/segment hasil inputURI dalam pengecualian berikut:

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

menggunakan NavigationManager API Riwayat browser untuk mempertahankan status riwayat navigasi yang terkait dengan setiap perubahan lokasi yang dibuat oleh aplikasi. Mempertahankan status riwayat sangat berguna dalam skenario pengalihan eksternal, seperti saat mengautentikasi pengguna dengan penyedia identitas eksternal. Untuk informasi selengkapnya, lihat bagian Opsi navigasi.

Teruskan NavigationOptions ke NavigateTo untuk mengontrol perilaku berikut:

  • ForceLoad: Melewati perutean sisi klien dan memaksa browser memuat halaman baru dari server, apakah URI ditangani oleh router sisi klien atau tidak. Nilai defaultnya adalah false.
  • ReplaceHistoryEntry: Ganti entri saat ini dalam tumpukan riwayat. Jika false, tambahkan entri baru ke tumpukan riwayat. Nilai defaultnya adalah false.
  • HistoryEntryState: Mendapatkan atau mengatur status untuk ditambahkan ke entri riwayat.
Navigation.NavigateTo("/path", new NavigationOptions
{
    HistoryEntryState = "Navigation state"
});

Untuk informasi selengkapnya tentang mendapatkan status yang terkait dengan entri riwayat target saat menangani perubahan lokasi, lihat bagian Menangani/mencegah perubahan lokasi.

String kueri

[SupplyParameterFromQuery] Gunakan atribut untuk menentukan bahwa parameter komponen berasal dari string kueri.

[SupplyParameterFromQuery] Gunakan atribut dengan [Parameter] atribut untuk menentukan bahwa parameter komponen komponen yang dapat dirutekan berasal dari string kueri.

Catatan

Parameter komponen hanya dapat menerima nilai parameter kueri dalam komponen yang dapat dirutekan dengan direktif @page .

Hanya komponen yang dapat dirutekan yang secara langsung menerima parameter kueri untuk menghindari menumbangkan alur informasi top-down dan untuk membuat urutan pemrosesan parameter menjadi jelas, baik oleh kerangka kerja maupun oleh aplikasi. Desain ini menghindari bug halus dalam kode aplikasi yang ditulis dengan asumsi urutan pemrosesan parameter tertentu. Anda bebas menentukan parameter berjendela kustom atau secara langsung ditetapkan ke parameter komponen reguler untuk meneruskan nilai parameter kueri ke komponen yang tidak dapat dirutekan.

Parameter komponen yang disediakan dari string kueri mendukung jenis berikut:

  • bool, , DateTime, doubledecimal, float, Guid, int, , long, string.
  • Varian nullable dari jenis sebelumnya.
  • Array dari jenis sebelumnya, baik yang dapat diubah ke null atau tidak dapat diubah ke null.

Pemformatan invarian budaya yang benar diterapkan untuk jenis yang diberikan (CultureInfo.InvariantCulture).

[SupplyParameterFromQuery] Tentukan properti atribut Name untuk menggunakan nama parameter kueri yang berbeda dari nama parameter komponen. Dalam contoh berikut, nama C# dari parameter komponen adalah {COMPONENT PARAMETER NAME}. Nama parameter kueri yang berbeda ditentukan untuk {QUERY PARAMETER NAME} tempat penampung:

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

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

Dalam contoh berikut dengan URL :/search?filter=scifi%20stars&page=3&star=LeVar%20Burton&star=Gary%20Oldman

  • Properti Filter menyelesaikan ke scifi stars.
  • Properti Page menyelesaikan ke 3.
  • Array Stars diisi dari parameter kueri bernama star (Name = "star") dan diselesaikan ke LeVar Burton dan Gary Oldman.

Catatan

Parameter string kueri dalam komponen halaman yang dapat dirutekan berikut juga berfungsi dalam komponen yang tidak dapat dirutekan tanpa direktif @page (misalnya, Search.razor untuk komponen bersama Search yang digunakan dalam komponen lain).

Search.razor:

@page "/search"

<h1>Search Example</h1>

<p>Filter: @Filter</p>

<p>Page: @Page</p>

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

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

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

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

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

Search.razor:

@page "/search"

<h1>Search Example</h1>

<p>Filter: @Filter</p>

<p>Page: @Page</p>

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

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

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

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

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

Gunakan NavigationManager.GetUriWithQueryParameter untuk menambahkan, mengubah, atau menghapus satu atau beberapa parameter kueri pada URL saat ini:

@inject NavigationManager Navigation

...

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

Untuk contoh sebelumnya:

  • Tempat {NAME} penampung menentukan nama parameter kueri. Tempat {VALUE} penampung menentukan nilai sebagai jenis yang didukung. Jenis yang didukung dicantumkan nanti di bagian ini.
  • String dikembalikan sama dengan URL saat ini dengan satu parameter:
    • Ditambahkan jika nama parameter kueri tidak ada di URL saat ini.
    • Diperbarui ke nilai yang disediakan jika parameter kueri ada di URL saat ini.
    • Dihapus jika jenis nilai yang disediakan dapat diubah ke null dan nilainya adalah null.
  • Pemformatan invarian budaya yang benar diterapkan untuk jenis yang diberikan (CultureInfo.InvariantCulture).
  • Nama dan nilai parameter kueri dikodekan URL.
  • Semua nilai dengan nama parameter kueri yang cocok diganti jika ada beberapa instans jenis.

Panggil NavigationManager.GetUriWithQueryParameters untuk membuat URI yang dibangun dari Uri dengan beberapa parameter ditambahkan, diperbarui, atau dihapus. Untuk setiap nilai, kerangka kerja menggunakan value?.GetType() untuk menentukan jenis runtime untuk setiap parameter kueri dan memilih pemformatan invarian budaya yang benar. Kerangka kerja melemparkan kesalahan untuk jenis yang tidak didukung.

@inject NavigationManager Navigation

...

Navigation.GetUriWithQueryParameters({PARAMETERS})

Tempat {PARAMETERS} penampung adalah IReadOnlyDictionary<string, object>.

Teruskan string URI ke untuk GetUriWithQueryParameters menghasilkan URI baru dari URI yang disediakan dengan beberapa parameter ditambahkan, diperbarui, atau dihapus. Untuk setiap nilai, kerangka kerja menggunakan value?.GetType() untuk menentukan jenis runtime untuk setiap parameter kueri dan memilih pemformatan invarian budaya yang benar. Kerangka kerja melemparkan kesalahan untuk jenis yang tidak didukung. Jenis yang didukung dicantumkan nanti di bagian ini.

@inject NavigationManager Navigation

...

Navigation.GetUriWithQueryParameters("{URI}", {PARAMETERS})
  • Tempat {URI} penampung adalah URI dengan atau tanpa string kueri.
  • Tempat {PARAMETERS} penampung adalah IReadOnlyDictionary<string, object>.

Jenis yang didukung identik dengan jenis yang didukung untuk batasan rute:

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

Jenis yang didukung meliputi:

  • Varian nullable dari jenis sebelumnya.
  • Array dari jenis sebelumnya, baik yang dapat diubah ke null atau tidak dapat diubah ke null.

Peringatan

Dengan kompresi, yang diaktifkan secara default, hindari membuat komponen sisi server interaktif yang aman (diautentikasi/diotorisasi) yang merender data dari sumber yang tidak tepercaya. Sumber yang tidak tepercaya termasuk parameter rute, string kueri, data dari JS interop, dan sumber data lain yang dapat dikontrol pengguna pihak ketiga (database, layanan eksternal). Untuk informasi selengkapnya, lihat panduan inti BlazorSignalR ASP.NET dan panduan mitigasi ancaman untuk penyajian sisi server interaktif ASP.NET CoreBlazor.

Mengganti nilai parameter kueri saat parameter ada

Navigation.GetUriWithQueryParameter("full name", "Morena Baccarin")
URL Saat Ini URL yang Dihasilkan
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

Menambahkan parameter dan nilai kueri saat parameter tidak ada

Navigation.GetUriWithQueryParameter("name", "Morena Baccarin")
URL Saat Ini URL yang Dihasilkan
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

Menghapus parameter kueri saat nilai parameter adalah null

Navigation.GetUriWithQueryParameter("full name", (string)null)
URL Saat Ini URL yang Dihasilkan
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/

Menambahkan, memperbarui, dan menghapus parameter kueri

Dalam contoh berikut:

  • name dihapus, jika ada.
  • age ditambahkan dengan nilai 25 (int), jika tidak ada. Jika ada, age diperbarui ke nilai 25.
  • eye color ditambahkan atau diperbarui ke nilai green.
Navigation.GetUriWithQueryParameters(
    new Dictionary<string, object?>
    {
        ["name"] = null,
        ["age"] = (int?)25,
        ["eye color"] = "green"
    })
URL Saat Ini URL yang Dihasilkan
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

Dukungan untuk nilai yang dapat dijumlahkan

Dalam contoh berikut:

  • full name ditambahkan atau diperbarui ke Morena Baccarin, satu nilai.
  • pingparameter ditambahkan atau diganti dengan 35, , 1687 dan 240.
Navigation.GetUriWithQueryParameters(
    new Dictionary<string, object?>
    {
        ["full name"] = "Morena Baccarin",
        ["ping"] = new int?[] { 35, 16, null, 87, 240 }
    })
URL Saat Ini URL yang Dihasilkan
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

Untuk menavigasi dengan string kueri yang ditambahkan atau dimodifikasi, teruskan URL yang dihasilkan ke NavigateTo.

Contoh panggilan berikut:

  • GetUriWithQueryParameter untuk menambahkan atau mengganti name parameter kueri menggunakan nilai Morena Baccarin.
  • NavigateTo Panggilan untuk memicu navigasi ke URL baru.
Navigation.NavigateTo(
    Navigation.GetUriWithQueryParameter("name", "Morena Baccarin"));

String kueri permintaan diperoleh dari NavigationManager.Uri properti :

@inject NavigationManager Navigation

...

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

Untuk mengurai parameter string kueri, salah satu pendekatannya adalah menggunakan URLSearchParams interop JavaScript (JS):

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

Untuk informasi selengkapnya tentang isolasi JavaScript dengan modul JavaScript, lihat Memanggil fungsi JavaScript dari metode .NET di ASP.NET Core Blazor.

Perutean hash ke elemen bernama

Navigasikan ke elemen bernama menggunakan pendekatan berikut dengan referensi hash (#) ke elemen . Rute ke elemen dalam komponen dan rute ke elemen dalam komponen eksternal menggunakan jalur root-relative. Garis miring ke depan (/) bersifat opsional.

Contoh untuk setiap pendekatan berikut menunjukkan navigasi ke elemen dengan salah satu id dari targetElement dalam Counter komponen:

  • Elemen jangkar (<a>) dengan href:

    <a href="/counter#targetElement">

  • NavLink komponen dengan href:

    <NavLink href="/counter#targetElement">

  • NavigationManager.NavigateTo meneruskan URL relatif:

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

Contoh berikut menunjukkan perutean yang di-hash ke judul bernama H2 dalam komponen dan komponen eksternal.

Home Di komponen (Home.razor) dan Counter (Counter.razor), letakkan markup berikut di bagian bawah markup komponen yang ada untuk berfungsi sebagai target navigasi. menciptakan <div> ruang vertikal buatan untuk menunjukkan perilaku pengguliran browser:

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

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

Tambahkan komponen berikut HashedRouting ke aplikasi.

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

Interaksi pengguna dengan <Navigating> konten

Jika ada penundaan yang signifikan selama navigasi, seperti saat rakitan pemuatan malas di Blazor WebAssembly aplikasi atau untuk koneksi jaringan lambat ke Blazor aplikasi sisi server, Router komponen dapat menunjukkan kepada pengguna bahwa transisi halaman sedang terjadi.

Di bagian atas komponen yang menentukan Router komponen, tambahkan direktif @using untuk Microsoft.AspNetCore.Components.Routing namespace:

@using Microsoft.AspNetCore.Components.Routing

Berikan konten ke Navigating parameter untuk ditampilkan selama peristiwa transisi halaman.

Dalam konten elemen router (<Router>...</Router>):

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

Untuk contoh yang menggunakan properti , lihat rakitan beban malas Navigating di ASP.NET Core Blazor WebAssembly.

Menangani peristiwa navigasi asinkron dengan OnNavigateAsync

Komponen Router mendukung OnNavigateAsync fitur. Handler OnNavigateAsync dipanggil saat pengguna:

  • Mengunjungi rute untuk pertama kalinya dengan menavigasi ke rute tersebut langsung di browser mereka.
  • Menavigasi ke rute baru menggunakan tautan atau NavigationManager.NavigateTo pemanggilan.
<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)
    {
        ...
    }
}

Untuk contoh yang menggunakan , lihat rakitan beban malas OnNavigateAsyncdi ASP.NET Core Blazor WebAssembly.

Saat melakukan pra-penyajian di server, OnNavigateAsync dijalankan dua kali:

  • Setelah ketika komponen titik akhir yang diminta awalnya dirender secara statis.
  • Untuk kedua kalinya ketika browser merender komponen titik akhir.

Untuk mencegah kode pengembang dalam OnNavigateAsync mengeksekusi dua kali, Routes komponen dapat menyimpan NavigationContext untuk digunakan di OnAfterRender{Async}, di mana firstRender dapat diperiksa. Untuk informasi selengkapnya, lihat Pra-penyajian dengan interop JavaScript di Blazor artikel Siklus Hidup.

Untuk mencegah kode pengembang dalam OnNavigateAsync mengeksekusi dua kali, App komponen dapat menyimpan NavigationContext untuk digunakan di OnAfterRender{Async}, di mana firstRender dapat diperiksa. Untuk informasi selengkapnya, lihat Pra-penyajian dengan interop JavaScript di Blazor artikel Siklus Hidup.

Menangani pembatalan di OnNavigateAsync

Objek NavigationContext yang OnNavigateAsync diteruskan ke panggilan balik berisi CancellationToken yang diatur saat peristiwa navigasi baru terjadi. Panggilan OnNavigateAsync balik harus dilemparkan ketika token pembatalan ini diatur untuk menghindari terus menjalankan OnNavigateAsync panggilan balik pada navigasi yang ketinggalan jaman.

Jika pengguna menavigasi ke titik akhir tetapi segera menavigasi ke titik akhir baru, aplikasi tidak boleh terus menjalankan OnNavigateAsync panggilan balik untuk titik akhir pertama.

Dalam contoh berikut:

  • Token pembatalan diteruskan dalam panggilan ke PostAsJsonAsync, yang dapat membatalkan POST jika pengguna menavigasi jauh dari /about titik akhir.
  • Token pembatalan diatur selama operasi prefetch produk jika pengguna menavigasi jauh dari /store titik akhir.
@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);
            }
        }
    }
}

Catatan

Tidak melemparkan jika token pembatalan di NavigationContext dibatalkan dapat mengakibatkan perilaku yang tidak diinginkan, seperti merender komponen dari navigasi sebelumnya.

Menangani/mencegah perubahan lokasi

RegisterLocationChangingHandler mendaftarkan handler untuk memproses peristiwa navigasi masuk. Konteks handler yang disediakan dengan LocationChangingContext menyertakan properti berikut:

Komponen dapat mendaftarkan beberapa penangan perubahan lokasi dalam metode atau .OnAfterRenderOnAfterRenderAsync Navigasi memanggil semua penangan perubahan lokasi yang terdaftar di seluruh aplikasi (di beberapa komponen), dan navigasi internal apa pun menjalankan semuanya secara paralel. Selain NavigateTo handler dipanggil:

  • Saat memilih tautan internal, yang merupakan tautan yang menunjuk ke URL di bawah jalur dasar aplikasi.
  • Saat menavigasi menggunakan tombol teruskan dan kembali di browser.

Handler hanya dijalankan untuk navigasi internal dalam aplikasi. Jika pengguna memilih tautan yang menavigasi ke situs lain atau mengubah bilah alamat ke situs lain secara manual, penangan perubahan lokasi tidak dijalankan.

Terapkan IDisposable dan buang handler terdaftar untuk membatalkan pendaftarannya. Untuk informasi lebih lanjut, lihat siklus hidup komponen Razor ASP.NET Core.

Penting

Jangan mencoba menjalankan tugas pembersihan DOM melalui interop JavaScript (JS) saat menangani perubahan lokasi. MutationObserver Gunakan pola pada JS klien. Untuk informasi selengkapnya, lihat ASP.NET Blazor interoperabilitas Core JavaScript (JS interop).

Dalam contoh berikut, penangan perubahan lokasi didaftarkan untuk peristiwa navigasi.

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

Karena navigasi internal dapat dibatalkan secara asinkron, beberapa panggilan yang tumpang tindih ke handler terdaftar dapat terjadi. Misalnya, beberapa panggilan handler dapat terjadi ketika pengguna dengan cepat memilih tombol kembali pada halaman atau memilih beberapa tautan sebelum navigasi dijalankan. Berikut ini adalah ringkasan logika navigasi asinkron:

  • Jika ada penangan yang mengubah lokasi terdaftar, semua navigasi awalnya dikembalikan, lalu diputar ulang jika navigasi tidak dibatalkan.
  • Jika permintaan navigasi yang tumpang tindih dibuat, permintaan terbaru selalu membatalkan permintaan sebelumnya, yang berarti hal berikut:
    • Aplikasi ini dapat memperlakukan beberapa pilihan tombol kembali dan teruskan sebagai satu pilihan.
    • Jika pengguna memilih beberapa tautan sebelum navigasi selesai, tautan terakhir yang dipilih menentukan navigasi.

Untuk informasi selengkapnya tentang meneruskan NavigationOptions ke NavigateTo untuk mengontrol entri dan status tumpukan riwayat navigasi, lihat bagian Opsi navigasi.

Untuk contoh kode tambahan, lihat NavigationManagerComponent di BasicTestApp (dotnet/aspnetcore sumber referensi).

Catatan

Tautan dokumentasi ke sumber referensi .NET biasanya memuat cabang default repositori, yang mewakili pengembangan saat ini untuk rilis .NET berikutnya. Untuk memilih tag rilis tertentu, gunakan daftar dropdown Beralih cabang atau tag. Untuk informasi lebih lanjut, lihat Cara memilih tag versi kode sumber ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Komponen NavigationLock mencegat peristiwa navigasi selama dirender, secara efektif "mengunci" navigasi tertentu sampai keputusan dibuat untuk melanjutkan atau membatalkan. Gunakan NavigationLock saat intersepsi navigasi dapat dilingkupkan ke masa pakai komponen.

NavigationLock Parameter:

  • ConfirmExternalNavigation mengatur dialog browser untuk meminta pengguna mengonfirmasi atau membatalkan navigasi eksternal. Nilai defaultnya adalah false. Menampilkan dialog konfirmasi memerlukan interaksi pengguna awal dengan halaman sebelum memicu navigasi eksternal dengan URL di bilah alamat browser. Untuk informasi selengkapnya tentang persyaratan interaksi, lihat Jendela: beforeunload peristiwa (dokumentasi MDN).
  • OnBeforeInternalNavigation mengatur panggilan balik untuk peristiwa navigasi internal.

Dalam komponen NavLock berikut:

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

Untuk contoh kode tambahan, lihat ConfigurableNavigationLock komponen di BasicTestApp (dotnet/aspnetcore sumber referensi).

NavLink Gunakan komponen sebagai pengganti elemen hyperlink HTML (<a>) saat membuat tautan navigasi. Komponen NavLink berulah seperti <a> elemen, kecuali itu beralih active ke kelas CSS berdasarkan apakah href cocok dengan URL saat ini. Kelas ini active membantu pengguna memahami halaman mana yang merupakan halaman aktif di antara tautan navigasi yang ditampilkan. Secara opsional, tetapkan nama kelas CSS untuk NavLink.ActiveClass menerapkan kelas CSS kustom ke tautan yang dirender saat rute saat ini cocok dengan href.

Ada dua NavLinkMatch opsi yang dapat Anda tetapkan ke Match atribut <NavLink> elemen :

Dalam contoh sebelumnya, HomeNavLinkhref="" cocok dengan URL beranda dan hanya menerima active kelas CSS di jalur dasar default aplikasi ()./ Yang kedua NavLink menerima active kelas ketika pengguna mengunjungi URL apa pun dengan component awalan (misalnya, /component dan /component/another-segment).

Atribut komponen tambahan NavLink diteruskan ke tag jangkar yang dirender. Dalam contoh berikut, NavLink komponen menyertakan target atribut :

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

Markup HTML berikut dirender:

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

Peringatan

Karena cara merender Blazor konten anak, komponen penyajian NavLink di dalam for perulangan memerlukan variabel indeks lokal jika variabel perulangan yang bertahas digunakan dalam NavLink konten komponen (turunan):

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

Menggunakan variabel indeks dalam skenario ini adalah persyaratan untuk komponen turunan apa pun yang menggunakan variabel perulangan dalam konten turunannyaNavLink, bukan hanya komponen.

Atau, gunakan perulangan foreach dengan Enumerable.Range:

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

NavLink entri komponen dapat dibuat secara dinamis dari komponen aplikasi melalui pantulan. Contoh berikut menunjukkan pendekatan umum untuk penyesuaian lebih lanjut.

Untuk demonstrasi berikut, konvensi penamaan standar yang konsisten digunakan untuk komponen aplikasi:

  • Nama file komponen yang dapat dirutekan menggunakan kasus Pascal†, misalnya Pages/ProductDetail.razor.
  • Jalur file komponen yang dapat dirutekan cocok dengan URL mereka dalam kasus kebab‡ dengan tanda hubung yang muncul di antara kata-kata dalam templat rute komponen. Misalnya, komponen ProductDetail dengan template rute /product-detail (@page "/product-detail") diminta di browser di URL relatif /product-detail.

†Pascal case (camel case dengan huruf besar) adalah konvensi penamaan tanpa spasi dan tanda baca dan dengan huruf pertama dari setiap kata dikapitalisasi, termasuk kata pertama.
‡Kasus Kebab adalah konvensi penamaan tanpa spasi dan tanda baca yang menggunakan huruf kecil dan tanda hubung antar kata.

Razor Dalam markup NavMenu komponen (NavMenu.razor) di bawah halaman defaultHome, NavLink komponen ditambahkan dari koleksi:

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

Metode GetRoutableComponents dalam @code blok:

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

Contoh sebelumnya tidak menyertakan halaman berikut dalam daftar komponen yang dirender:

  • Home halaman: Halaman dicantumkan secara terpisah dari tautan yang dihasilkan secara otomatis karena akan muncul di bagian atas daftar dan mengatur Match parameter.
  • Error halaman: Halaman kesalahan hanya dinavigasi oleh kerangka kerja dan tidak boleh dicantumkan.

Untuk contoh kode sebelumnya dalam aplikasi sampel yang dapat Anda jalankan secara lokal, dapatkan Blazor Aplikasi Web atau Blazor WebAssembly aplikasi sampel.

integrasi perutean titik akhir inti ASP.NET

Bagian ini berlaku untuk Blazor Web Apps yang beroperasi melalui sirkuit.

Bagian ini berlaku untuk Blazor Server aplikasi.

Blazor Aplikasi Web diintegrasikan ke dalam Perutean Titik Akhir Inti ASP.NET. Aplikasi ASP.NET Core dikonfigurasi untuk menerima koneksi masuk untuk komponen interaktif dengan MapRazorComponents dalam Program file. Komponen akar default (komponen pertama yang dimuat) adalah App komponen (App.razor):

app.MapRazorComponents<App>();

Blazor Server diintegrasikan ke dalam Perutean Titik Akhir Inti ASP.NET. Aplikasi ASP.NET Core dikonfigurasi untuk menerima koneksi masuk untuk komponen interaktif dengan MapBlazorHub dalam Program file:

app.UseRouting();

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

Blazor Server diintegrasikan ke dalam Perutean Titik Akhir Inti ASP.NET. Aplikasi ASP.NET Core dikonfigurasi untuk menerima koneksi masuk untuk komponen interaktif dengan MapBlazorHub di Startup.Configure.

Konfigurasi umumnya adalah merutekan semua permintaan ke Razor halaman, yang bertindak sebagai host untuk bagian Blazor Server sisi server aplikasi. Menurut konvensi, halaman host biasanya dinamai _Host.cshtmlPages di folder aplikasi.

Rute yang ditentukan dalam file host disebut rute fallback karena beroperasi dengan prioritas rendah dalam pencocokan rute. Rute fallback digunakan saat rute lain tidak cocok. Ini memungkinkan aplikasi untuk menggunakan pengontrol dan halaman lain tanpa mengganggu perutean komponen di Blazor Server aplikasi.

Untuk informasi tentang mengonfigurasi MapFallbackToPage hosting server URL non-root, lihat Host dan sebarkan ASP.NET Core Blazor.