perutean dan navigasi inti Blazor ASP.NET

  • Artikel
  • 36 menit untuk membaca

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

Templat rute

Komponen ini Router memungkinkan perutean ke Razor komponen dalam aplikasi Blazor . Komponen Router digunakan dalam App komponen Blazor aplikasi.

App.razor:

<Router AppAssembly="@typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
    </Found>
    <NotFound>
        <p>Sorry, there's nothing at this address.</p>
    </NotFound>
</Router>

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 kerja Blazor menentukan MainLayout komponen (Shared/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 direktif. Contoh komponen berikut dimuat pada permintaan untuk /BlazorRoute dan /DifferentBlazorRoute.

Pages/BlazorRoute.razor:

@page "/BlazorRoute"
@page "/DifferentBlazorRoute"

<h1>Blazor routing</h1>

Penting

Agar URL dapat diselesaikan dengan benar, aplikasi harus menyertakan <base> tag dalam wwwroot/index.html file (Blazor WebAssembly) atau Pages/_Layout.cshtml file (Blazor Server) dengan jalur dasar aplikasi yang ditentukan dalam href atribut . Untuk informasi selengkapnya, lihat Host dan sebarkan ASP.NET Core Blazor.

Memfokuskan elemen pada navigasi

FocusOnNavigate Gunakan komponen untuk mengatur fokus UI ke elemen berdasarkan pemilih CSS setelah menavigasi dari satu halaman ke halaman lainnya. Anda dapat melihat komponen yang FocusOnNavigate digunakan oleh App komponen aplikasi yang dihasilkan dari Blazor templat proyek.

App.razor:

<Router AppAssembly="@typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
        <FocusOnNavigate RouteData="@routeData" Selector="h1" />
    </Found>
    <NotFound>
        <LayoutView Layout="@typeof(MainLayout)">
            <p role="alert">Sorry, there's nothing at this address.</p>
        </LayoutView>
    </NotFound>
</Router>

Saat komponen sebelumnya Router 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 Router memungkinkan aplikasi menentukan konten kustom jika konten tidak ditemukan untuk rute yang diminta.

App Dalam komponen, atur konten kustom dalam Router templat komponenNotFound.

App.razor:

<Router AppAssembly="@typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
    </Found>
    <NotFound>
        <h1>Sorry</h1>
        <p>Sorry, there's nothing at this address.</p> b
    </NotFound>
</Router>

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

Merutekan ke komponen dari beberapa rakitan

AdditionalAssemblies Gunakan parameter untuk menentukan rakitan tambahan untuk dipertimbangkan Router komponen saat mencari komponen yang dapat dirutekan. Rakitan tambahan dipindai selain assembly yang ditentukan ke AppAssembly. Dalam contoh berikut, Component1 adalah komponen yang dapat dirutekan yang ditentukan dalam pustaka kelas komponen yang dirujuk. Contoh berikut AdditionalAssemblies menghasilkan dukungan perutean untuk Component1.

App.razor:

<Router
    AppAssembly="@typeof(Program).Assembly"
    AdditionalAssemblies="new[] { typeof(Component1).Assembly }">
    @* ... Router component elements ... *@
</Router>

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 /RouteParameter/amazing, <h1> konten tag dirender sebagai Blazor is amazing!.

Pages/RouteParameter.razor:

@page "/RouteParameter/{text}"

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

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

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

Pages/RouteParameter.razor:

@page "/RouteParameter/{text?}"

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

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

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

Gunakan OnParametersSet alih-alih OnInitialized{Async} mengizinkan navigasi aplikasi ke komponen yang sama dengan nilai parameter opsional yang berbeda. Berdasarkan contoh sebelumnya, gunakan OnParametersSet kapan pengguna harus dapat menavigasi dari /RouteParameter ke /RouteParameter/amazing atau dari /RouteParameter/amazing ke /RouteParameter:

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

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

Pages/User.razor:

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

<h1>User Id: @Id</h1>

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

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
kultur
Pencocokan
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} CD2C1638-1638-72D5-1638-DEADBEEF1638, {CD2C1638-1638-72D5-1638-DEADBEEF1638} Tidak
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 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.

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

Untuk aplikasi dan Blazor Server yang dihostingBlazor WebAssembly, templat rute default sisi server mengasumsikan bahwa jika segmen terakhir URL permintaan berisi titik (.) yang diminta file. Misalnya, URL https://localhost.com:5001/example/some.thing 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.

Pages/Example.razor:

@page "/example/{param?}"

<p>
    Param: @Param
</p>

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

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

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 di Program.cs:

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

Untuk informasi selengkapnya, lihat Perutean di ASP.NET Core.

Parameter rute catch-all

Parameter rute catch-all, yang menangkap 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.

Pages/CatchAll.razor:

@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 ditangkap didekodekan. Untuk templat /catch-all/{*pageRoute}rute , URL /catch-all/this/is/a%2Ftest%2A menghasilkan this/is/a/test*.

Pembantu status URI dan 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 ditambahkan ke jalur URI relatif untuk menghasilkan URI absolut. Biasanya, BaseUri sesuai dengan href atribut pada elemen dokumen <base> di wwwroot/index.html (Blazor WebAssembly) atau Pages/_Layout.cshtml (Blazor Server).
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 Mengingat URI dasar (misalnya, URI yang sebelumnya dikembalikan oleh BaseUri), mengonversi URI absolut menjadi 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 .

Perubahan lokasi

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

Komponen berikut:

  • Navigasi ke komponen aplikasi Counter (Pages/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. Melepaskan metode memungkinkan pengumpulan sampah komponen.

    • Implementasi pencatat mencatat informasi berikut saat tombol dipilih:

      BlazorSample.Pages.Navigate: Information: URL of new location: https://localhost:5001/counter

Pages/Navigate.razor:

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

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

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

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

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

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

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

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

String kueri

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

Catatan

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

Parameter komponen yang disediakan dari string kueri mendukung jenis berikut:

  • bool, DateTime, decimal, double, float, Guid, int, long, string.
  • Varian yang dapat diubah ke null dari jenis sebelumnya.
  • Array dari jenis sebelumnya, apakah 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:

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

Pages/Search.razor:

@page "/search"

<h1>Search Example</h1>

<p>Filter: @Filter</p>

<p>Page: @Page</p>

@if (Stars is not null)
{
    <p>Assignees:</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 NavigationManager

...

NavigationManager.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 DENGAN 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 NavigationManager

...

NavigationManager.GetUriWithQueryParameters({PARAMETERS})

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

Teruskan string URI ke GetUriWithQueryParameters untuk 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 NavigationManager

...

NavigationManager.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 yang dapat diubah ke null dari jenis sebelumnya.
  • Array dari jenis sebelumnya, apakah dapat diubah ke null atau tidak dapat diubah ke null.

Mengganti nilai parameter kueri saat parameter ada

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

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

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

Lihat 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.
NavigationManager.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

Lihat contoh berikut:

  • full name ditambahkan atau diperbarui ke Morena Baccarin, satu nilai.
  • pingparameter ditambahkan atau diganti dengan 35, , 1687 dan 240.
NavigationManager.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 berikut memanggil:

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

Interaksi pengguna dengan <Navigating> konten

Komponen Router dapat menunjukkan kepada pengguna bahwa transisi halaman sedang terjadi.

Di bagian App atas komponen (App.razor), tambahkan direktif @using untuk Microsoft.AspNetCore.Components.Routing namespace:

@using Microsoft.AspNetCore.Components.Routing

<Navigating> Tambahkan tag ke komponen dengan markup untuk ditampilkan selama peristiwa transisi halaman. Untuk informasi selengkapnya, lihat Navigating (dokumentasi API).

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

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

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

Menangani peristiwa navigasi asinkron dengan OnNavigateAsync

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

  • Kunjungi rute untuk pertama kalinya dengan menavigasi ke rute tersebut langsung di browser mereka.
  • Menavigasi ke rute baru menggunakan tautan atau NavigationManager.NavigateTo pemanggilan.

App Dalam komponen (App.razor):

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

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

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

Saat melakukan pra-penyajian di server di aplikasi atau aplikasi yang Blazor Server dihosting Blazor WebAssembly , OnNavigateAsync dijalankan dua kali:

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

Untuk mencegah kode pengembang dalam OnNavigateAsync mengeksekusi dua kali, App komponen dapat menyimpan NavigationContext untuk digunakan di OnAfterRender/OnAfterRenderAsync, di mana firstRender dapat diperiksa. Untuk informasi selengkapnya, lihat Mendeteksi kapan aplikasi melakukan pra-penyajian 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 kedaluarsa.

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

Dalam contoh komponen berikut App :

  • Token pembatalan diteruskan dalam panggilan ke PostAsJsonAsync, yang dapat membatalkan POST jika pengguna menavigasi menjauh dari /about titik akhir.
  • Token pembatalan diatur selama operasi prefetch produk jika pengguna menavigasi jauh dari /store titik akhir.

App.razor:

@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 = [345, 789, 135, 689];

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

Catatan

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

Gunakan komponen sebagai NavLink pengganti elemen hyperlink HTML (<a>) saat membuat tautan navigasi. Komponen NavLink ber perilaku seperti <a> elemen, kecuali itu beralih active ke kelas CSS berdasarkan apakah href cocok dengan URL saat ini. Kelas membantu active 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.

Catatan

Komponen NavMenu (NavMenu.razor) disediakan di Shared folder aplikasi yang dihasilkan dari Blazor templat proyek.

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 URL jalur dasar default aplikasi (misalnya, ). https://localhost:5001/ Yang kedua NavLink menerima active kelas ketika pengguna mengunjungi URL apa pun dengan component awalan (misalnya, https://localhost:5001/component dan https://localhost:5001/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 perulangan for memerlukan variabel indeks lokal jika variabel perulangan yang bertahakan digunakan dalam NavLink konten komponen (anak):

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

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

Atau, gunakan perulangan foreach dengan Enumerable.Range:

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

ASP.NET Integrasi perutean titik akhir core

Bagian ini hanya berlaku untuk Blazor Server aplikasi.

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 Program.cs:

app.UseRouting();

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

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.cshtml di Pages folder aplikasi.

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

Templat rute

Komponen ini Router memungkinkan perutean ke Razor komponen dalam aplikasi Blazor . Komponen Router digunakan dalam App komponen Blazor aplikasi.

App.razor:

<Router AppAssembly="@typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
    </Found>
    <NotFound>
        <p>Sorry, there's nothing at this address.</p>
    </NotFound>
</Router>

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 kerja Blazor menentukan MainLayout komponen (Shared/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 direktif. Contoh komponen berikut dimuat pada permintaan untuk /BlazorRoute dan /DifferentBlazorRoute.

Pages/BlazorRoute.razor:

@page "/BlazorRoute"
@page "/DifferentBlazorRoute"

<h1>Blazor routing</h1>

Penting

Agar URL dapat diselesaikan dengan benar, aplikasi harus menyertakan <base> tag dalam wwwroot/index.html file (Blazor WebAssembly) atau Pages/_Host.cshtml file (Blazor Server) 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 dan uraikan parameter .

Sediakan konten kustom saat konten tidak ditemukan

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

App Dalam komponen, atur konten kustom dalam Router templat komponenNotFound.

App.razor:

<Router AppAssembly="@typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
    </Found>
    <NotFound>
        <h1>Sorry</h1>
        <p>Sorry, there's nothing at this address.</p> b
    </NotFound>
</Router>

Catatan

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

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

Merutekan ke komponen dari beberapa rakitan

AdditionalAssemblies Gunakan parameter untuk menentukan rakitan tambahan untuk dipertimbangkan Router komponen saat mencari komponen yang dapat dirutekan. Rakitan tambahan dipindai selain assembly yang ditentukan ke AppAssembly. Dalam contoh berikut, Component1 adalah komponen yang dapat dirutekan yang ditentukan dalam pustaka kelas komponen yang dirujuk. Contoh berikut AdditionalAssemblies menghasilkan dukungan perutean untuk Component1.

App.razor:

<Router
    AppAssembly="@typeof(Program).Assembly"
    AdditionalAssemblies="new[] { typeof(Component1).Assembly }">
    @* ... Router component elements ... *@
</Router>

Catatan

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

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 /RouteParameter/amazing, <h1> konten tag dirender sebagai Blazor is amazing!.

Pages/RouteParameter.razor:

@page "/RouteParameter/{text}"

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

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

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

Pages/RouteParameter.razor:

@page "/RouteParameter/{text?}"

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

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

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

Gunakan OnParametersSet alih-alih OnInitialized{Async} mengizinkan navigasi aplikasi ke komponen yang sama dengan nilai parameter opsional yang berbeda. Berdasarkan contoh sebelumnya, gunakan OnParametersSet kapan pengguna harus dapat menavigasi dari /RouteParameter ke /RouteParameter/amazing atau dari /RouteParameter/amazing ke /RouteParameter:

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

Catatan

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

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

Pages/User.razor:

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

<h1>User Id: @Id</h1>

@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 dan uraikan parameter .

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
kultur
Pencocokan
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} CD2C1638-1638-72D5-1638-DEADBEEF1638, {CD2C1638-1638-72D5-1638-DEADBEEF1638} Tidak
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 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.

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

Untuk aplikasi dan Blazor Server yang dihostingBlazor WebAssembly, templat rute default sisi server mengasumsikan bahwa jika segmen terakhir URL permintaan berisi titik (.) yang diminta file. Misalnya, URL https://localhost.com:5001/example/some.thing 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.

Pages/Example.razor:

@page "/example/{param?}"

<p>
    Param: @Param
</p>

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

Untuk mengizinkan aplikasi solusi yang dihosting Server untuk merutekan Blazor WebAssembly permintaan 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 selengkapnya, lihat Perutean di ASP.NET Core.

Parameter rute catch-all

Parameter rute catch-all, yang menangkap 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.

Pages/CatchAll.razor:

@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 ditangkap didekodekan. Untuk templat /catch-all/{*pageRoute}rute , URL /catch-all/this/is/a%2Ftest%2A menghasilkan this/is/a/test*.

Pembantu status URI dan 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 ditambahkan ke jalur URI relatif untuk menghasilkan URI absolut. Biasanya, BaseUri sesuai dengan href atribut pada elemen dokumen <base> di wwwroot/index.html (Blazor WebAssembly) atau Pages/_Host.cshtml (Blazor Server).
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 Mengingat URI dasar (misalnya, URI yang sebelumnya dikembalikan oleh BaseUri), mengonversi URI absolut menjadi URI relatif terhadap awalan URI dasar.

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

Komponen berikut:

  • Navigasi ke komponen aplikasi Counter (Pages/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. Melepaskan metode memungkinkan pengumpulan sampah komponen.

    • Implementasi pencatat mencatat informasi berikut saat tombol dipilih:

      BlazorSample.Pages.Navigate: Information: URL of new location: https://localhost:5001/counter

Pages/Navigate.razor:

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

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

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

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

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

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

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

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

String kueri dan parameter penguraian

String kueri permintaan diperoleh dari NavigationManager.Uri properti :

@inject NavigationManager NavigationManager

...

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

Untuk mengurai parameter string kueri, salah satu pendekatannya adalah menggunakan URLSearchParamsinterop 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.

Interaksi pengguna dengan <Navigating> konten

Komponen Router dapat menunjukkan kepada pengguna bahwa transisi halaman sedang terjadi.

Di bagian App atas komponen (App.razor), tambahkan direktif @using untuk Microsoft.AspNetCore.Components.Routing namespace:

@using Microsoft.AspNetCore.Components.Routing

<Navigating> Tambahkan tag ke komponen dengan markup untuk ditampilkan selama peristiwa transisi halaman. Untuk informasi selengkapnya, lihat Navigating (dokumentasi API).

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

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

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

Menangani peristiwa navigasi asinkron dengan OnNavigateAsync

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

  • Kunjungi rute untuk pertama kalinya dengan menavigasi ke rute tersebut langsung di browser mereka.
  • Menavigasi ke rute baru menggunakan tautan atau NavigationManager.NavigateTo pemanggilan.

App Dalam komponen (App.razor):

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

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

Catatan

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

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

Saat melakukan pra-penyajian di server di aplikasi atau aplikasi yang Blazor Server dihosting Blazor WebAssembly , OnNavigateAsync dijalankan dua kali:

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

Untuk mencegah kode pengembang dalam OnNavigateAsync mengeksekusi dua kali, App komponen dapat menyimpan NavigationContext untuk digunakan di OnAfterRender/OnAfterRenderAsync, di mana firstRender dapat diperiksa. Untuk informasi selengkapnya, lihat Mendeteksi kapan aplikasi melakukan pra-penyajian 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 kedaluarsa.

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

Dalam contoh komponen berikut App :

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

App.razor:

@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 = [345, 789, 135, 689];

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

Catatan

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

Catatan

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

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

Catatan

Komponen NavMenu (NavMenu.razor) disediakan di Shared folder aplikasi yang dihasilkan dari Blazor templat proyek.

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 URL jalur dasar default aplikasi (misalnya, ). https://localhost:5001/ Yang kedua NavLink menerima active kelas ketika pengguna mengunjungi URL apa pun dengan component awalan (misalnya, https://localhost:5001/component dan https://localhost:5001/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 turunan, komponen penyajian NavLink di dalam perulangan for memerlukan variabel indeks lokal jika variabel perulangan yang tahapan digunakan dalam NavLink konten komponen (turunan):

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

Menggunakan variabel indeks dalam skenario ini adalah persyaratan untuk setiap komponen anak 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="@c">
            <span ...></span> @c
        </NavLink>
    </li>
}

ASP.NET Integrasi perutean titik akhir inti

Bagian ini hanya berlaku untuk Blazor Server aplikasi.

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.

Startup.cs:

using Microsoft.AspNetCore.Builder;

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapBlazorHub();
            endpoints.MapFallbackToPage("/_Host");
        });
    }
}

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 ketika rute lain tidak cocok. Ini memungkinkan aplikasi untuk menggunakan pengontrol dan halaman lain tanpa mengganggu perutean komponen di Blazor Server aplikasi.

Templat rute

Komponen Router memungkinkan perutean ke Razor komponen di aplikasi Blazor . Komponen Router digunakan dalam App komponen Blazor aplikasi.

App.razor:

<Router AppAssembly="@typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
    </Found>
    <NotFound>
        <p>Sorry, there's nothing at this address.</p>
    </NotFound>
</Router>

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 kerja Blazor menentukan MainLayout komponen (Shared/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 /BlazorRoute dan /DifferentBlazorRoute.

Pages/BlazorRoute.razor:

@page "/BlazorRoute"
@page "/DifferentBlazorRoute"

<h1>Blazor routing</h1>

Penting

Agar URL diselesaikan dengan benar, aplikasi harus menyertakan <base> tag dalam wwwroot/index.html file (Blazor WebAssembly) atau Pages/_Host.cshtml file (Blazor Server) 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 dan parameter penguraian .

Menyediakan konten kustom saat konten tidak ditemukan

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

App Dalam komponen, atur konten kustom dalam Router templat komponenNotFound.

App.razor:

<Router AppAssembly="@typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
    </Found>
    <NotFound>
        <h1>Sorry</h1>
        <p>Sorry, there's nothing at this address.</p> b
    </NotFound>
</Router>

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

Merutekan ke komponen dari beberapa rakitan

AdditionalAssemblies Gunakan parameter untuk menentukan rakitan tambahan untuk komponen yang perlu dipertimbangkan Router saat mencari komponen yang dapat dirutekan. Rakitan tambahan dipindai selain rakitan yang ditentukan ke AppAssembly. Dalam contoh berikut, Component1 adalah komponen yang dapat dirutekan yang ditentukan dalam pustaka kelas komponen yang dirujuk. Contoh berikut AdditionalAssemblies menghasilkan dukungan perutean untuk Component1.

App.razor:

<Router
    AppAssembly="@typeof(Program).Assembly"
    AdditionalAssemblies="new[] { typeof(Component1).Assembly }">
    @* ... Router component elements ... *@
</Router>

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 /RouteParameter/amazing, <h1> konten tag dirender sebagai Blazor is amazing!.

Pages/RouteParameter.razor:

@page "/RouteParameter/{text}"

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

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

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 .

Pages/RouteParameter.razor:

@page "/RouteParameter"
@page "/RouteParameter/{text}"

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

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

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

Gunakan OnParametersSet alih-alih OnInitialized{Async} mengizinkan navigasi aplikasi ke komponen yang sama dengan nilai parameter opsional yang berbeda. Berdasarkan contoh sebelumnya, gunakan OnParametersSet kapan pengguna harus dapat menavigasi dari /RouteParameter ke /RouteParameter/amazing atau dari /RouteParameter/amazing ke /RouteParameter:

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

Catatan

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

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

Pages/User.razor:

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

<h1>User Id: @Id</h1>

@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 dan parameter penguraian .

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
kultur
Pencocokan
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} CD2C1638-1638-72D5-1638-DEADBEEF1638, {CD2C1638-1638-72D5-1638-DEADBEEF1638} Tidak
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 invarian. Batasan ini mengasumsikan bahwa URL tidak dapat dilokalkan.

Perutean dengan URL yang berisi titik-titik

Untuk aplikasi dan Blazor Server yang dihostingBlazor WebAssembly, templat rute default sisi server mengasumsikan bahwa jika segmen terakhir URL permintaan berisi titik (.) yang diminta file. Misalnya, URL https://localhost.com:5001/example/some.thing 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.

Pages/Example.razor:

@page "/example"
@page "/example/{param}"

<p>
    Param: @Param
</p>

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

Untuk mengizinkan aplikasi solusi yang dihosting Server untuk merutekan Blazor WebAssembly permintaan 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 selengkapnya, lihat Perutean di ASP.NET Core.

Parameter rute catch-all

Parameter rute catch-all didukung di ASP.NET Core 5.0 atau yang lebih baru. Untuk informasi selengkapnya, pilih versi 5.0 dari artikel ini.

Pembantu status URI dan 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 ditambahkan ke jalur URI relatif untuk menghasilkan URI absolut. Biasanya, BaseUri sesuai dengan href atribut pada elemen dokumen <base> di wwwroot/index.html (Blazor WebAssembly) atau Pages/_Host.cshtml (Blazor Server).
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 Mengingat URI dasar (misalnya, URI yang sebelumnya dikembalikan oleh BaseUri), mengonversi URI absolut menjadi URI relatif terhadap awalan URI dasar.

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

Komponen berikut:

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

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

    • Implementasi pencatat mencatat informasi berikut saat tombol dipilih:

      BlazorSample.Pages.Navigate: Information: URL of new location: https://localhost:5001/counter

Pages/Navigate.razor:

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

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

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

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

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

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

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

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

String kueri dan parameter penguraian

String kueri permintaan diperoleh dari NavigationManager.Uri properti :

@inject NavigationManager NavigationManager

...

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

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

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

Catatan

Komponen NavMenu (NavMenu.razor) disediakan di Shared folder aplikasi yang dihasilkan dari Blazor templat proyek.

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 URL jalur dasar default aplikasi (misalnya, ). https://localhost:5001/ Yang kedua NavLink menerima active kelas ketika pengguna mengunjungi URL apa pun dengan component awalan (misalnya, https://localhost:5001/component dan https://localhost:5001/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 turunan, komponen penyajian NavLink di dalam perulangan for memerlukan variabel indeks lokal jika variabel perulangan yang tahapan digunakan dalam NavLink konten komponen (turunan):

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

Menggunakan variabel indeks dalam skenario ini adalah persyaratan untuk setiap komponen anak 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="@c">
            <span ...></span> @c
        </NavLink>
    </li>
}

ASP.NET Integrasi perutean titik akhir inti

Bagian ini hanya berlaku untuk Blazor Server aplikasi.

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.

Startup.cs:

using Microsoft.AspNetCore.Builder;

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapBlazorHub();
            endpoints.MapFallbackToPage("/_Host");
        });
    }
}

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 ketika rute lain tidak cocok. Ini memungkinkan aplikasi untuk menggunakan pengontrol dan halaman lain tanpa mengganggu perutean komponen di Blazor Server aplikasi.