Bagikan melalui

navigasi dan perutean ASP.NET Core Blazor

Catatan

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

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 9 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 9 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 disuntikkan sebagai NavigationManager dalam kelas dan komponen.

Perutean statis versus interaktif

Bagian ini berlaku untuk Blazor Web Apps.

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

Ketika mode render interaktif ditetapkan pada komponen Routes, router Blazor 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.

Routing interaktif juga mencegah prarendering karena konten halaman baru tidak diminta dari server dengan permintaan halaman yang biasa. Untuk informasi selengkapnya, lihat Prerender ASP.NET Core Razor komponen.

Pola Rute

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

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

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

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

Pada saat runtime, komponen RouteView:

  • Menerima RouteData dari Router beserta 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. Kerangka kerja templat proyekBlazor menentukan MainLayout komponen (MainLayout.razor) sebagai tata letak default aplikasi. Untuk informasi selengkapnya tentang tata letak, lihat Blazor ASP.NET Core.

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"

<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 diresolusikan dengan benar, aplikasi harus menyertakan tag <base> (lokasi <head> konten) dengan jalur dasar aplikasi yang ditentukan dalam atribut href. Untuk informasi selengkapnya, lihat jalur dasar aplikasi ASP.NET CoreBlazor.

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 .NET 5.0.1 dan untuk rilis 5.x tambahan, Router komponen menyertakan parameter PreferExactMatches diatur ke @true. Untuk informasi selengkapnya, lihat Migrasi dari ASP.NET Core 3.1 ke .NET 5.

Memusatkan perhatian pada elemen 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 konten khusus untuk parameter Router dari komponen NotFound.

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

Item sembarang didukung sebagai konten dari parameter NotFound, seperti komponen interaktif lainnya. Untuk menerapkan tata letak default ke NotFound konten, lihat tata letak Blazor ASP.NET Core.

Penting

Blazor Web Apptidak menggunakan parameter NotFound (markup<NotFound>...</NotFound>), tetapi parameter ini didukung untuk kompatibilitas mundur guna menghindari perubahan yang dapat menyebabkan kerusakan dalam kerangka kerja. Sisi server alur middleware ASP.NET Core memproses permintaan di server. Gunakan teknik sisi server untuk menangani permintaan buruk.

† yang didukung dalam konteks ini berarti bahwa menempatkan markup <NotFound>...</NotFound> tidak menghasilkan pengecualian, tetapi menggunakan markup juga tidak efektif.

Untuk informasi selengkapnya, termasuk pendekatan yang direkomendasikan untuk menangani permintaan buruk, lihat mode render ASP.NET Core Blazor.

Mengarahkan ke komponen dari beberapa rakitan

Bagian ini berlaku untuk Blazor Web Apps.

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

Pengaturan Rute Statis

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

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

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

Catatan

Panduan sebelumnya juga berlaku dalam skenario perpustakaan 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 pembuat-gambar interaktif dapat ditetapkan ke komponen Routes (Routes.razor) yang membuat router Blazor menjadi interaktif setelah SSR statis dan routing statis di server. Misalnya, <Routes @rendermode="InteractiveServer" /> mengatur penyajian sisi server interaktif (SSR interaktif) pada komponen Routes. Komponen Router mewarisi penyajian sisi server interaktif (SSRI) dari Routes. Router menjadi lebih interaktif setelah melakukan perutean statis pada server.

Navigasi internal untuk routing interaktif tidak melibatkan permintaan konten halaman baru dari server. Oleh karena itu, pra-rendering tidak terjadi untuk permintaan halaman internal. Untuk informasi selengkapnya, lihat Prerender ASP.NET Core Razor komponen.

Jika komponen Routes didefinisikan dalam proyek server, parameter AdditionalAssemblies dari komponen Router harus menyertakan assembly proyek .Client. Ini memungkinkan router untuk berfungsi dengan benar ketika dirender secara interaktif.

Dalam contoh berikut, komponen Routes berada dalam proyek server, dan file _Imports.razor dari proyek BlazorSample.Client menunjukkan assembly untuk mencari komponen yang routable.

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

Rakitan tambahan dipindai selain rakitan yang ditentukan oleh AppAssembly.

Catatan

Panduan sebelumnya juga berlaku dalam skenario perpustakaan kelas komponen.

Atau, komponen yang dapat dirutekan hanya terdapat dalam proyek .Client dengan WebAssembly Interaktif global atau pengaturan Rendering otomatis yang diterapkan, serta komponen Routes didefinisikan dalam proyek .Client, 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.

Gunakan parameter komponen Router dan pembangun konvensi titik akhir AdditionalAssemblies untuk menemukan komponen yang dapat dirutekan di 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 oleh AppAssembly.

Parameter rute

Router menggunakan parameter rute untuk mengisi parameter komponen yang sesuai dengan nama yang sama. Nama parameter rute tidak sensitif terhadap penggunaan huruf besar atau 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}"

<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, diterapkan dua arahan . 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?}"

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

Ketika OnInitialized{Async} siklus hidup digunakan alih-alih OnParametersSet{Async} siklus hidup, penetapan default Text 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 bisa digunakan untuk nilai string kueri. Untuk bekerja dengan string kueri, lihat bagian String kueri .

Batasan rute

Batasan rute mengharuskan pencocokan jenis pada segmen rute terhadap komponen.

Dalam contoh berikut, rute ke komponen User 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
Kecocokan
bool {active:bool} true, FALSE Tidak
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} 00001111-aaaa-2222-bbbb-3333cccc4444, {00001111-aaaa-2222-bbbb-3333cccc4444} Tidak
int {id:int} 123456789, -123456789 Ya
long {ticks:long} 123456789, -123456789 Ya
nonfile {parameter:nonfile} Bukan BlazorSample.styles.css, bukan favicon.ico 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; }
}

Hindari pengambilan file dalam parameter rute

Templat rute berikut secara tidak sengaja mengambil jalur aset statis dalam parameter rute opsionalnya (Optional). Misalnya, stylesheet aplikasi (.styles.css) direkam, yang menyebabkan rusaknya gaya aplikasi:

@page "/{optional?}"

...

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

Untuk membatasi parameter rute untuk menangkap jalur non-file, gunakan :nonfile batasan dalam templat rute:

@page "/{optional:nonfile?}"

Perutean dengan URL yang berisi titik-titik

Template rute default sisi server mengasumsikan bahwa jika segmen terakhir URL permintaan berisi titik (.) bahwa file diminta. 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 dari solusi yang dihosting oleh Server untuk merutekan permintaan dengan titik dalam parameter rute Blazor WebAssembly, tambahkan templat rute berkas cadangan dengan parameter opsional pada berkas .

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

Untuk mengonfigurasi aplikasi Blazor Server agar dapat merutekan permintaan dengan titik pada parameter rute param, tambahkan templat rute laman cadangan dengan parameter opsional dalam file Program.

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

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

Untuk mengizinkan aplikasi dari solusi yang dihosting untuk merutekan permintaan dengan titik dalam parameter rute , tambahkan template rute file fallback dengan parameter opsional di .

Startup.cs:

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

Untuk mengonfigurasi aplikasi Blazor Server agar dapat merutekan permintaan dengan titik pada parameter rute param, 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 serbaguna untuk rute

Parameter rute "catch-all", yang menangkap jalur melintasi beberapa batas folder, didukung dalam komponen.

Parameter rute serba guna adalah:

  • Dinamai agar sesuai dengan nama segmen rute. Penamaan tidak sensitif terhadap huruf besar/kecil.
  • Tipe string. Kerangka kerja tidak menyediakan konversi tipe 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}"

<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 rute /catch-all/{*pageRoute}, nilai PageRoute diatur ke this/is/a/test.

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

URI dan alat bantu 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 yang sedang digunakan saat ini.
BaseUri Mendapatkan URI dasar (dengan garis miring di akhir) yang dapat ditambahkan di depan path 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, dan Blazor navigasi yang ditingkatkan diaktifkan.
  • Jika tidak, Blazor lakukan pemuatan ulang halaman penuh untuk URL yang diminta.
Jika forceLoad adalah true:
  • Pengalihan sisi klien diabaikan.
  • 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 Sebuah peristiwa yang terjadi saat lokasi navigasi telah berubah. Untuk informasi selengkapnya, lihat bagian Perubahan lokasi.
NotFound Dipanggil untuk menangani skenario di mana sumber daya yang diminta tidak ditemukan. Untuk informasi selengkapnya, lihat bagian Respons Tidak Ditemukan .
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 menangani 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 yang sedang digunakan saat ini.
BaseUri Mendapatkan URI dasar (dengan garis miring di akhir) yang dapat ditambahkan di depan path 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, dan Blazor navigasi yang ditingkatkan diaktifkan.
  • Jika tidak, Blazor lakukan pemuatan ulang halaman penuh untuk URL yang diminta.
Jika forceLoad adalah true:
  • Pengalihan sisi klien diabaikan.
  • 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 Sebuah peristiwa yang terjadi 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 menangani 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 yang sedang digunakan saat ini.
BaseUri Mendapatkan URI dasar (dengan garis miring di akhir) yang dapat ditambahkan di depan path 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:
  • Pengalihan sisi klien diabaikan.
  • 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 Sebuah peristiwa yang terjadi 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 menangani 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 yang sedang digunakan saat ini.
BaseUri Mendapatkan URI dasar (dengan garis miring di akhir) yang dapat ditambahkan di depan path 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:
  • Pengalihan sisi klien diabaikan.
  • 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 Sebuah peristiwa yang terjadi 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 yang sedang digunakan saat ini.
BaseUri Mendapatkan URI dasar (dengan garis miring di akhir) yang dapat ditambahkan di depan path 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:
  • Pengalihan sisi klien diabaikan.
  • Browser dipaksa untuk memuat halaman baru dari server, apakah URI biasanya ditangani oleh router sisi klien atau tidak.
LocationChanged Sebuah peristiwa yang terjadi 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 acara , menyediakan informasi berikut tentang peristiwa navigasi:

Komponen berikut:

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

    • Metode HandleLocationChanged ini dilepaskan 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"
@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 ASP.NET Core Razor pembuangan komponen.

Respons Tidak Ditemukan

Di .NET 10 Pratinjau 4, respons Tidak Ditemukan hanya tersedia untuk SSR statis dan penyajian interaktif global. Dukungan rendering per halaman/komponen direncanakan untuk Pratinjau 5 pada bulan Juni 2025.

NavigationManager menyediakan NotFound metode untuk menangani skenario di mana sumber daya yang diminta tidak ditemukan selama penyajian sisi server statis (SSR statis) atau penyajian interaktif global:

  • SSR Statis: Panggilan NotFound mengatur kode status HTTP ke 404.
  • Penyajian streaming: Memberikan pengecualian jika respons telah dimulai.
  • Penyajian interaktif: Memberi sinyal router Blazor (Router komponen) untuk merender konten Tidak Ditemukan.

Ketika komponen dirender secara statis (SSR statis) dan NavigationManager.NotFound dipanggil, kode status 404 diatur pada respons:

@page "/render-not-found-ssr"
@inject NavigationManager Navigation

@code {
    protected override void OnInitialized()
    {
        Navigation.NotFound();
    }
}

Untuk menyediakan konten Tidak Ditemukan untuk penyajian interaktif global, gunakan halaman Tidak Ditemukan (Razor komponen).

Catatan

Templat proyek Blazor menyertakan halaman NotFound.razor secara bawaan. Halaman ini secara otomatis dirender setiap kali NavigationManager.NotFound dipanggil, sehingga lebih mudah untuk menangani rute yang hilang dengan pengalaman pengguna yang konsisten.

NotFound.razor:

<h1>Not Found</h1>

<p>Sorry! Nothing to show.</p>

Tetapkan NotFound komponen ke parameter router NotFoundPage . NotFoundPage mendukung perutean yang dapat diterapkan di seluruh middleware eksekusi ulang, termasuk middleware non-Blazor. NotFound Jika fragmen render didefinisikan bersama dengan NotFoundPage, halaman memiliki prioritas yang lebih tinggi.

Dalam contoh berikut, komponen sebelumnya NotFound ada di folder aplikasi Pages dan diteruskan ke NotFoundPage parameter :

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

Ketika sebuah komponen dirender dengan mode render interaktif global, memanggil NotFound menyampaikan sinyal ke router Blazor untuk merender komponen NotFound.

@page "/render-not-found-interactive"
@inject NavigationManager Navigation

@if (RendererInfo.IsInteractive)
{
    <button @onclick="TriggerNotFound">Trigger Not Found</button>
}

@code {
    private void TriggerNotFound()
    {
        Navigation.NotFound();
    }
}

Anda dapat menggunakan acara OnNotFound untuk pemberitahuan saat NotFound diaktifkan. Peristiwa ini hanya diaktifkan ketika NotFound dipanggil, bukan untuk respons 404. Misalnya, pengaturan HttpContextAccessor.HttpContext.Response.StatusCode ke 404 tidak memicu NotFound/OnNotFound.

Dalam contoh berikut untuk komponen yang mengadopsi penyajian sisi server interaktif (SSR interaktif), konten kustom dirender tergantung di mana OnNotFound dipanggil. Jika peristiwa dipicu oleh komponen berikut Movie saat film tidak ditemukan pada inisialisasi komponen, pesan kustom menyatakan bahwa film yang diminta tidak ditemukan. Jika peristiwa dipicu oleh User komponen, pesan yang berbeda menyatakan bahwa pengguna tidak ditemukan.

Layanan berikut NotFoundContext mengelola konteks dan pesan saat konten tidak ditemukan oleh komponen.

NotFoundContext.cs:

public class NotFoundContext
{
    public string Heading { get; private set; } = "Not Found";
    public string Message { get; private set; } = 
        "Sorry, the page that you requested couldn't be found.";

    public void UpdateContext(string heading, string message)
    {
        Heading = heading;
        Message = message;
    }
}

Layanan ini terdaftar dalam file sisi Program server:

builder.Services.AddScoped<NotFoundContext>();

Komponen Routes (Routes.razor):

  • Menyuntikkan NotFoundContext layanan.
  • Menampilkan judul (Heading) dan pesan (Message) ketika OnNotFound dipicu oleh panggilan ke NotFound.
@inject NotFoundContext NotFoundContext

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
        <FocusOnNavigate RouteData="routeData" Selector="h1" />
    </Found>
    <NotFound>
        <LayoutView Layout="typeof(Layout.MainLayout)">
            <h1>@NotFoundContext.Heading</h1> 
            <div>
                <p>@NotFoundContext.Message</p>
            </div>
        </LayoutView>
    </NotFound>
</Router>

Dalam contoh komponen berikut:

  • Layanan NotFoundContext diintegrasikan, bersama dengan NavigationManager.
  • Di OnInitializedAsync, HandleNotFound adalah penanganan aktivitas yang ditetapkan ke OnNotFound peristiwa. HandleNotFound memanggil NotFoundContext.UpdateContext untuk menetapkan judul dan pesan untuk konten 'Tidak Ditemukan' yang ditampilkan oleh komponen Router dalam komponen Routes (Routes.razor).
  • Komponen biasanya menggunakan ID dari parameter rute untuk memperoleh informasi film atau pengguna dari sumber data, seperti database. Dalam contoh berikut, tidak ada entitas yang dikembalikan (null) untuk mensimulasikan apa yang terjadi ketika entitas tidak ditemukan.
  • Ketika tidak ada entitas yang dikembalikan ke OnInitializedAsync, NavigationManager.NotFound dipanggil, yang pada gilirannya memicu OnNotFound event dan HandleNotFound event handler. Pesan Tidak Ditemukan ditampilkan oleh router.
  • Metode HandleNotFound ini tidak terkait pada pembuangan komponen di IDisposable.Dispose.

Movie komponen (Movie.razor):

@page "/movie/{Id:int}"
@implements IDisposable
@inject NavigationManager NavigationManager
@inject NotFoundContext NotFoundContext

<div>
    No matter what ID is used, no matching movie is returned
    from the call to GetMovie().
</div>

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

    protected override async Task OnInitializedAsync()
    {
        NavigationManager.OnNotFound += HandleNotFound;

        var movie = await GetMovie(Id);

        if (movie == null)
        {
            NavigationManager.NotFound();
        }
    }

    private void HandleNotFound(object? sender, NotFoundEventArgs e)
    {
        NotFoundContext.UpdateContext("Movie Not Found",
            "Sorry! The requested movie wasn't found.");
    }

    private async Task<MovieItem[]?> GetMovie(int id)
    {
        // Simulate no movie with matching id found
        return await Task.FromResult<MovieItem[]?>(null);
    }

    void IDisposable.Dispose()
    {
        NavigationManager.OnNotFound -= HandleNotFound;
    }

    public class MovieItem
    {
        public int Id { get; set; }
        public string? Title { get; set; }
    }
}

User komponen (User.razor):

@page "/user/{Id:int}"
@implements IDisposable
@inject NavigationManager NavigationManager
@inject NotFoundContext NotFoundContext

<div>
    No matter what ID is used, no matching user is returned
    from the call to GetUser().
</div>

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

    protected override async Task OnInitializedAsync()
    {
        NavigationManager.OnNotFound += HandleNotFound;

        var user = await GetUser(Id);

        if (user == null)
        {
            NavigationManager.NotFound();
        }
    }

    private void HandleNotFound(object? sender, NotFoundEventArgs e)
    {
        NotFoundContext.UpdateContext("User Not Found",
            "Sorry! The requested user wasn't found.");
    }

    private async Task<UserItem[]?> GetUser(int id)
    {
        // Simulate no user with matching id found
        return await Task.FromResult<UserItem[]?>(null);
    }

    void IDisposable.Dispose()
    {
        NavigationManager.OnNotFound -= HandleNotFound;
    }

    public class UserItem
    {
        public int Id { get; set; }
        public string? Name { get; set; }
    }
}

Untuk mencapai komponen pendahuluan dalam demonstrasi lokal menggunakan aplikasi pengujian, buat entri pada komponen NavMenu (NavMenu.razor) untuk menjangkau komponen Movie dan User. ID entitas, yang diteruskan sebagai parameter rute, dalam contoh berikut adalah nilai semu yang tidak berpengaruh karena tidak benar-benar digunakan oleh komponen, yang mensimulasikan ketidakberhasilan menemukan film atau pengguna.

Dalam NavMenu.razor:

<div class="nav-item px-3">
    <NavLink class="nav-link" href="movie/1">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Movie
    </NavLink>
</div>

<div class="nav-item px-3">
    <NavLink class="nav-link" href="user/2">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> User
    </NavLink>
</div>

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 permintaan fetch 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: