Menggunakan Razor komponen dalam aplikasi JavaScript dan kerangka kerja SPA

Artikel ini membahas cara merender Razor komponen dari JavaScript, menggunakan Blazor elemen kustom, dan menghasilkan komponen Angular dan React.

Catatan

Sebaiknya gunakan blazor.server.js skrip (Blazor Server) dan blazor.webassembly.js (Blazor WebAssembly) saat mengintegrasikan Razor komponen ke dalam aplikasi JavaScript yang ada sampai dukungan yang blazor.web.js lebih baik untuk skrip (Blazor Web App) ditambahkan di masa mendatang. Untuk informasi selengkapnya, lihat RegisterCustomElement berhenti berfungsi di Blazor 8 (dotnet/aspnetcore #53920).

Aplikasi sampel Angular

• CustomElementsBlazorSample () (Blazor Serverjaviercn/CustomElementsBlazorSample, cabang: blazor-server): Blazor Server didukung di .NET 8/9. Untuk memigrasikan sampel .NET 7 ini, lihat Migrasi dari ASP.NET Core 7.0 ke 8.0 dan Migrasi dari ASP.NET Core di .NET 8 ke ASP.NET Core di .NET 9.
• CustomElementsBlazorSample () (Blazor WebAssemblyjaviercn/CustomElementsBlazorSample, cabang: blazor-wasm): Untuk memigrasikan sampel .NET 7 ini, lihat Migrasi dari ASP.NET Core 7.0 ke 8.0 dan Migrasi dari ASP.NET Core di .NET 8 ke ASP.NET Core di .NET 9.

Merender komponen Razor dari JavaScript

Komponen Razor dapat dirender secara dinamis dari JavaScript (JS) untuk aplikasi JS yang ada.

Contoh di bagian ini merender komponen berikut Razor ke dalam halaman melalui JS.

Quote.razor:

<div class="m-5 p-5">
    <h2>Quote</h2>
    <p>@Text</p>
</div>

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

Program Dalam file, tambahkan namespace layanan untuk lokasi komponen.

Panggil RegisterForJavaScript pengumpulan komponen akar aplikasi untuk mendaftarkan Razor komponen sebagai komponen akar untuk JS penyajian.

RegisterForJavaScript termasuk kelebihan beban yang menerima nama JS fungsi yang menjalankan logika inisialisasi (javaScriptInitializer). Fungsi JS ini dipanggil sekali per pendaftaran komponen segera setelah Blazor aplikasi dimulai dan sebelum komponen apa pun dirender. Fungsi ini dapat digunakan untuk integrasi dengan JS teknologi, seperti elemen kustom HTML atau JSkerangka kerja SPA berbasis.

Satu atau beberapa fungsi penginisialisasi dapat dibuat dan dipanggil oleh pendaftaran komponen yang berbeda. Kasus penggunaan umumnya adalah menggunakan kembali fungsi penginisialisasi yang sama untuk beberapa komponen, yang diharapkan jika fungsi inisialisasi mengonfigurasi integrasi dengan elemen kustom atau kerangka kerja SPA berbasis lainnya JS.

Penting

Jangan membingungkan javaScriptInitializer parameter RegisterForJavaScript dengan penginisialisasi JavaScript. Nama parameter dan JS fitur penginisialisasi bersifat kebetulan.

Contoh berikut menunjukkan pendaftaran dinamis komponen sebelumnya Quote dengan "quote" sebagai pengidentifikasi.

• Di aplikasi Blazor Server , ubah panggilan ke AddServerSideBlazor Program dalam file:

  builder.Services.AddServerSideBlazor(options =>
  {
      options.RootComponents.RegisterForJavaScript<Quote>(identifier: "quote", 
          javaScriptInitializer: "initializeComponent");
  });
  

• Di aplikasi Blazor WebAssembly , panggil RegisterForJavaScript RootComponents di file sisi Program klien:

  builder.RootComponents.RegisterForJavaScript<Quote>(identifier: "quote", 
      javaScriptInitializer: "initializeComponent");
  

Lampirkan fungsi penginisialisasi dengan name parameter fungsi dan parameters ke window objek . Untuk tujuan demonstrasi, fungsi berikut mencatat initializeComponent nama dan parameter komponen terdaftar.

wwwroot/jsComponentInitializers.js:

window.initializeComponent = (name, parameters) => {
  console.log({ name: name, parameters: parameters });
}

Render komponen dari JS ke dalam elemen kontainer menggunakan pengidentifikasi terdaftar, meneruskan parameter komponen sesuai kebutuhan.

Dalam contoh berikut:

• Komponen Quote (quote pengidentifikasi) dirender ke quoteContainer dalam elemen ketika fungsi dipanggil showQuote .
• String kuotasi diteruskan ke parameter komponen Text .

wwwroot/scripts.js:

window.showQuote = async () => {
  let targetElement = document.getElementById('quoteContainer');
  await Blazor.rootComponents.add(targetElement, 'quote', 
  {
    text: "Crow: I have my doubts that this movie is actually 'starring' " +
      "anybody. More like, 'camera is generally pointed at.'"
  });
}

const btn = document.querySelector("#showQuoteBtn");
btn.addEventListener("click", showQuote);

Blazor Setelah skrip dimuat, muat skrip sebelumnya ke JS dalam aplikasi:

<script src="_framework/{BLAZOR SCRIPT}"></script>
<script src="jsComponentInitializers.js"></script>
<script src="scripts.js"></script>

Dalam contoh sebelumnya, {BLAZOR SCRIPT} tempat penampung adalah Blazor skrip.

Di HTML, tempatkan elemen kontainer target (quoteContainer). Untuk demonstrasi di bagian ini, tombol memicu penyajian Quote komponen dengan memanggil showQuoteJS fungsi:

<button id="showQuoteBtn">Show Quote</button>

<div id="quoteContainer"></div>

Pada inisialisasi sebelum komponen apa pun dirender, konsol Quote alat pengembang browser mencatat pengidentifikasi komponen (name) dan parameter (parameters) ketika initializeComponent dipanggil:

Object { name: "quote", parameters: (1) […] }
  name: "quote"
  parameters: Array [ {…} ]
    0: Object { name: "Text", type: "string" }
    length: 1

Saat tombol Show Quote dipilih, Quote komponen dirender dengan kutipan yang disimpan dalam Text ditampilkan:

Kutipan ©1988-1999 Satelit Cinta LLC: Misteri Science Theater 3000 (Jejak Beaulieu (Gagak))

Catatan

rootComponents.add mengembalikan instans komponen. Panggil dispose instans untuk merilisnya:

const rootComponent = await window.Blazor.rootComponents.add(...);

...

rootComponent.dispose();

Contoh sebelumnya secara dinamis merender komponen akar saat fungsi dipanggil showQuote()JS . Untuk merender komponen akar ke dalam elemen kontainer saat Blazor dimulai, gunakan penginisialisasi JavaScript untuk merender komponen, seperti yang ditunjukkan contoh berikut.

Contoh berikut dibangun pada contoh sebelumnya, menggunakan Quote komponen, pendaftaran komponen akar dalam Program file, dan inisialisasi jsComponentInitializers.js. Fungsi showQuote() (dan script.js file) tidak digunakan.

Di HTML, tempatkan elemen kontainer target, quoteContainer2 untuk contoh ini:

<div id="quoteContainer2"></div>

Menggunakan penginisialisasi JavaScript, tambahkan komponen akar ke elemen kontainer target.

wwwroot/{PACKAGE ID/ASSEMBLY NAME}.lib.module.js:

export function afterStarted(blazor) {
  let targetElement = document.getElementById('quoteContainer2');
  blazor.rootComponents.add(targetElement, 'quote',
    {
      text: "Crow: I have my doubts that this movie is actually 'starring' " +
          "anybody. More like, 'camera is generally pointed at.'"
    });
}

Catatan

Untuk panggilan ke rootComponents.add, gunakan blazor parameter (huruf bkecil) yang disediakan oleh Blazor peristiwa mulai. Meskipun pendaftaran valid saat menggunakan Blazor objek (huruf Bbesar ), pendekatan yang disukai adalah menggunakan parameter .

Untuk contoh lanjutan dengan fitur tambahan, lihat contoh di BasicTestApp sumber referensi ASP.NET Core (dotnet/aspnetcore repositori GitHub):

• JavaScriptRootComponents.razor
• wwwroot/js/jsRootComponentInitializers.js
• wwwroot/index.html

Catatan

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

Elemen kustom Blazor

Gunakan Blazor elemen kustom untuk merender Razor komponen secara dinamis dari kerangka kerja SPA lainnya, seperti Angular atau React.

Blazor elemen kustom:

• Gunakan antarmuka HTML standar untuk menerapkan elemen HTML kustom.
• Hilangkan kebutuhan untuk mengelola status dan siklus hidup komponen akar Razor secara manual menggunakan API JavaScript.
• Berguna untuk memperkenalkan Razor komponen secara bertahap ke dalam proyek yang ada yang ditulis dalam kerangka kerja SPA lainnya.

Elemen kustom tidak mendukung konten turunan atau komponen templat.

Nama elemen

Sesuai spesifikasi HTML, nama tag elemen kustom harus mengadopsi kasus kebab:

❌Batal: mycounter
❌Batal: MY-COUNTER
❌Batal: MyCounter
✔️Sah: my-counter
✔️Sah: my-cool-counter

Paket

Tambahkan referensi paket untuk Microsoft.AspNetCore.Components.CustomElements ke file proyek aplikasi.

Catatan

Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bagian Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

Contoh komponen

Contoh berikut didasarkan pada Counter komponen dari Blazor templat proyek.

Counter.razor:

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

Blazor Server pendaftaran

Ikuti langkah-langkah berikut untuk mendaftarkan komponen akar sebagai elemen kustom di aplikasi Blazor Server .

Microsoft.AspNetCore.Components.Web Tambahkan namespace layanan ke bagian Program atas file:

using Microsoft.AspNetCore.Components.Web;

Tambahkan namespace layanan untuk komponen aplikasi. Dalam contoh berikut, namespace aplikasi adalah BlazorSample dan komponen terletak di Pages folder:

using BlazorSample.Pages;

Ubah panggilan ke AddServerSideBlazor. Tentukan elemen kustom dengan RegisterCustomElement pada RootComponents opsi sirkuit. Contoh berikut mendaftarkan Counter komponen dengan elemen my-counterHTML kustom :

builder.Services.AddServerSideBlazor(options =>
{
    options.RootComponents.RegisterCustomElement<Counter>("my-counter");
});

Blazor WebAssembly pendaftaran

Ikuti langkah-langkah berikut untuk mendaftarkan komponen akar sebagai elemen kustom di aplikasi Blazor WebAssembly .

Microsoft.AspNetCore.Components.Web Tambahkan namespace layanan ke bagian Program atas file:

using Microsoft.AspNetCore.Components.Web;

Tambahkan namespace layanan untuk komponen aplikasi. Dalam contoh berikut, namespace aplikasi adalah BlazorSample dan komponen terletak di Pages folder:

using BlazorSample.Pages;

Panggil RegisterCustomElement di RootComponents. Contoh berikut mendaftarkan Counter komponen dengan elemen my-counterHTML kustom :

builder.RootComponents.RegisterCustomElement<Counter>("my-counter");

Menggunakan elemen kustom terdaftar

Gunakan elemen kustom dengan kerangka kerja web apa pun. Misalnya, elemen HTML kustom sebelumnya my-counter yang merender komponen aplikasi Counter digunakan dalam aplikasi React dengan markup berikut:

<my-counter></my-counter>

Untuk contoh lengkap tentang cara membuat elemen kustom dengan Blazor, lihat CustomElementsComponent komponen di sumber referensi.

Catatan

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

Meneruskan parameter

Teruskan parameter ke komponen Anda Razor baik sebagai atribut HTML atau sebagai properti JavaScript pada elemen DOM.

Komponen berikut Counter menggunakan IncrementAmount parameter untuk mengatur jumlah kenaikan tombol Click me .

Counter.razor:

@page "/counter"

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    [Parameter]
    public int IncrementAmount { get; set; } = 1;

    private void IncrementCount()
    {
        currentCount += IncrementAmount;
    }
}

Render Counter komponen dengan elemen kustom dan teruskan nilai ke IncrementAmount parameter sebagai atribut HTML. Nama atribut mengadopsi sintaks kebab-case (increment-amount, bukan IncrementAmount):

<my-counter increment-amount="10"></my-counter>

Atau, Anda dapat mengatur nilai parameter sebagai properti JavaScript pada objek elemen. Nama properti mengadopsi sintaks kasus unta (incrementAmount, bukan IncrementAmount):

const elem = document.querySelector("my-counter");
elem.incrementAmount = 10;

Anda dapat memperbarui nilai parameter kapan saja menggunakan atribut atau sintaks properti.

Jenis parameter yang didukung:

• Dengan menggunakan sintaks properti JavaScript, Anda dapat meneruskan objek dari jenis yang dapat diserialisasikan JSON.
• Dengan menggunakan atribut HTML, Anda terbatas pada meneruskan objek string, boolean, atau jenis numerik.

Membuat komponen Angular dan React

Buat komponen JavaScript khusus kerangka kerja (JS) dari komponen Razor untuk kerangka kerja web, seperti Angular atau React. Kemampuan ini tidak disertakan dengan .NET, tetapi diaktifkan oleh dukungan untuk komponen penyajian Razor dari JS. Sampel pembuatan komponen JS di GitHub menunjukkan cara membuat komponen Angular dan React dari komponen Razor. Lihat file README.md aplikasi sampel GitHub untuk informasi tambahan.

Peringatan

Fitur komponen Angular dan React saat ini bersifat eksperimental, tidak didukung, dan dapat berubah atau dihapus kapan saja. Kami menantikan umpan balik Anda tentang seberapa baik pendekatan ini mampu memenuhi kebutuhan Anda.