ASP.NET Core navigasi Blazor

Artikel ini menjelaskan cara memicu dan menangani navigasi halaman di Blazor. Meskipun pengguna dapat menavigasi antara halaman yang berbeda menggunakan tautan HTML normal, Blazor meningkatkan navigasi dalam aplikasi untuk menghindari pemuatan ulang halaman penuh dan memberikan pengalaman yang lebih lancar. NavLink Gunakan komponen untuk membuat tautan navigasi yang secara otomatis menerapkan gaya saat tautan cocok dengan halaman saat ini. Untuk navigasi terprogram dan manajemen URI dalam kode C#, gunakan NavigationManager layanan .

Penting

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

NavLink komponen

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

Pada komponen NavMenu (NavMenu.razor) dari aplikasi Blazor yang dibuat menggunakan templat proyek Blazor:

<div class="nav-item px-3">
    <NavLink class="nav-link" href="" Match="NavLinkMatch.All">
        <span class="bi bi-house-door-fill-nav-menu" aria-hidden="true"></span> Home
    </NavLink>
</div>
<div class="nav-item px-3">
    <NavLink class="nav-link" href="counter">
        <span class="bi bi-plus-square-fill-nav-menu" aria-hidden="true"></span> Counter
    </NavLink>
</div>

Dalam contoh sebelumnya, HomeNavLinkhref="" cocok dengan URL beranda dan hanya menerima kelas CSS active di jalur dasar default aplikasi (/). Yang kedua NavLink menerima kelas active ketika pengguna mengunjungi komponen Counter pada /counter.

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

• NavLinkMatch.All: NavLink aktif saat cocok dengan URL saat ini, mengabaikan string dan fragmen kueri. Untuk menyertakan pencocokan pada string/fragmen kueri, gunakan sakelar Microsoft.AspNetCore.Components.Routing.NavLink.EnableMatchAllForQueryStringAndFragment yang diatur ke AppContexttrue.
• NavLinkMatch.Prefix (default): NavLink aktif saat cocok dengan awalan URL saat ini.

Untuk mengadopsi logika pencocokan kustom, buat subclass dari NavLink dan timpa metode ShouldMatch. Kembalikan true dari metode saat Anda ingin menerapkan kelas CSS active:

public class CustomNavLink : NavLink
{
    protected override bool ShouldMatch(string currentUriAbsolute)
    {
        // Custom matching logic
    }
}

Atribut komponen tambahan NavLink diteruskan langsung 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 Blazor merender konten anak, merender komponen NavLink di dalam perulangan for memerlukan variabel indeks lokal jika variabel perulangan yang meningkat digunakan dalam konten komponen (anak) NavLink.

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

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

Atau, gunakan perulangan foreach dengan Enumerable.Range:

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

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

Perubahan lokasi

Untuk acara , menyediakan informasi berikut tentang peristiwa navigasi:

• Location: URL lokasi baru.
• IsNavigationIntercepted: Jika true, Blazor mencegat navigasi dari browser. Jika false, NavigationManager.NavigateTo menyebabkan terjadinya 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

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

Untuk informasi selengkapnya tentang pembuangan komponen, lihat ASP.NET Core Razor pembuangan komponen.

Perilaku pengalihan Manajer Navigasi selama penyajian sisi server statis (SSR statis)

Untuk pengalihan selama penyajian sisi server statis (SSR statis), NavigationManager bergantung pada pelemparan NavigationException yang ditangkap oleh kerangka kerja, yang mengonversi kesalahan menjadi pengalihan. Kode yang ada setelah panggilan ke NavigateTo tidak dipanggil. Saat menggunakan Visual Studio, debugger berhenti pada pengecualian, mengharuskan Anda membatalkan pilihan kotak centang untuk Hentikan saat jenis pengecualian ini ditangani pengguna di UI Visual Studio untuk menghindari debugger berhenti untuk pengalihan di masa mendatang.

Anda dapat menggunakan <BlazorDisableThrowNavigationException> properti MSBuild yang diatur ke true dalam file proyek aplikasi untuk ikut serta tidak lagi melemparkan NavigationException. Selain itu, kode setelah panggilan untuk NavigateTo dijalankan ketika tidak akan berjalan sebelumnya. Perilaku ini diaktifkan secara default dalam templat proyek .NET 10 atau yang lebih baru Blazor Web App :

<BlazorDisableThrowNavigationException>true</BlazorDisableThrowNavigationException>

Respons Tidak Ditemukan

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 NavigationManager.NotFound mengatur kode status HTTP ke 404.

• Penyajian interaktif: Memberi sinyal router Blazor (Router komponen) untuk merender konten Tidak Ditemukan.

• Streaming rendering: Jika navigasi yang ditingkatkan aktif, streaming rendering merender konten Tidak Ditemukan tanpa memuat ulang halaman. Ketika navigasi yang ditingkatkan diblokir, kerangka mengalihkan ke konten Tidak Ditemukan dengan memuat ulang halaman.

Nota

Diskusi berikut menyebutkan bahwa komponen Not Found Razor dapat ditetapkan ke parameter dari komponen RouterNotFoundPage. Parameter berfungsi bersama-sama dengan NavigationManager.NotFound dan dijelaskan secara lebih rinci nanti di bagian ini.

Rendering streaming hanya dapat merender komponen yang memiliki rute, seperti NotFoundPage penugasan (NotFoundPage="...") atau penugasan halaman Middleware Eksekusi Ulang Kode Status (UseStatusCodePagesWithReExecute). DefaultNotFound konten 404 ("teks biasa" Not found) tidak memiliki rute, sehingga tidak dapat digunakan selama rendering streaming.

Nota

Fragmen render Tidak Ditemukan (<NotFound>...</NotFound>) tidak didukung di .NET 10 atau yang lebih baru.

NavigationManager.NotFound penyajian konten menggunakan hal berikut, terlepas dari apakah respons telah dimulai atau tidak (secara berurutan):

• Jika NotFoundEventArgs.Path ditetapkan, render konten halaman yang ditetapkan.
• Jika Router.NotFoundPage ditetapkan, render halaman yang ditentukan.
• Halaman Kode Status Eksekusi Ulang Halaman Middleware, jika dikonfigurasi.
• Tidak ada tindakan jika tidak ada pendekatan sebelumnya yang diadopsi.

Middleware Eksekusi Ulang Halaman Kode Status dengan UseStatusCodePagesWithReExecute diutamakan untuk masalah perutean alamat berbasis browser, seperti URL yang salah yang diketik ke bilah alamat browser atau memilih tautan yang tidak memiliki titik akhir di aplikasi.

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

Nota

Templat proyek Blazor mencakup halaman NotFound.razor. Halaman ini secara otomatis dirender setiap kali NavigationManager.NotFound dipanggil, memungkinkan untuk menangani rute yang hilang dengan pengalaman pengguna yang konsisten.

Pages/NotFound.razor:

@page "/not-found"
@layout MainLayout

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

Komponen NotFound ditetapkan ke parameter router NotFoundPage . NotFoundPage mendukung perutean yang dapat digunakan pada Middleware Halaman Kode Status Eksekusi Ulang, termasuk Blazor non-middleware.

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 NavigationManager.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 event OnNotFound untuk pemberitahuan ketika NavigationManager.NotFound dipanggil. Peristiwa ini hanya diaktifkan ketika NavigationManager.NotFound dipanggil, bukan untuk respons 404. Misalnya, pengaturan HttpContextAccessor.HttpContext.Response.StatusCode ke 404 tidak memicu NavigationManager.NotFound/OnNotFound.

Aplikasi yang menerapkan router kustom juga dapat menggunakan NavigationManager.NotFound. Router kustom dapat merender konten Tidak Ditemukan dari dua sumber, tergantung pada status respons:

• Terlepas dari status respons, jalur eksekusi ulang ke halaman dapat digunakan dengan meneruskannya ke UseStatusCodePagesWithReExecute:

  app.UseStatusCodePagesWithReExecute(
      "/not-found", createScopeForStatusCodePages: true);
  

• Ketika respons sudah dimulai, NotFoundEventArgs.Path dapat digunakan dengan berlangganan pada OnNotFoundEvent di dalam router.

  @code {
      [CascadingParameter]
      public HttpContext? HttpContext { get; set; }
  
      private void OnNotFoundEvent(object sender, NotFoundEventArgs e)
      {
          // Only execute the logic if HTTP response has started,
          // because setting NotFoundEventArgs.Path blocks re-execution
          if (HttpContext?.Response.HasStarted == false)
          {
              return;
          }
  
          var type = typeof(CustomNotFoundPage);
          var routeAttributes = type.GetCustomAttributes<RouteAttribute>(inherit: true);
  
          if (routeAttributes.Length == 0)
          {
              throw new InvalidOperationException($"The type {type.FullName} " +
                  $"doesn't have a {nameof(RouteAttribute)} applied.");
          }
  
          var routeAttribute = (RouteAttribute)routeAttributes[0];
  
          if (routeAttribute.Template != null)
          {
              e.Path = routeAttribute.Template;
          }
      }
  }
  

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 dalam contoh berikut, 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; }
    public string? Message { get; private set; }

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

Layanan ini terdaftar dalam file sisi Program server:

builder.Services.AddScoped<NotFoundContext>();

Halaman NotFound menyuntikkan NotFoundContext dan menampilkan judul dan pesan.

Pages/NotFound.razor:

@page "/not-found"
@layout MainLayout
@inject NotFoundContext NotFoundContext

<h3>@NotFoundContext.Heading</h3>
<div>
    <p>@NotFoundContext.Message</p>
</div>

Komponen Routes (Routes.razor) mengatur NotFound komponen sebagai halaman Tidak Ditemukan melalui NotFoundPage parameter :

<Router AppAssembly="typeof(Program).Assembly" NotFoundPage="typeof(Pages.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 mengatur judul dan pesan untuk konten Tidak Ditemukan dalam komponen NotFound.
• 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: