Bagikan melalui

Lokasi JavaScript di aplikasi ASP.NET Core Blazor

Catatan

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

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 9 dari artikel ini.

Penting

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

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

Muat kode JavaScript (JS) menggunakan salah satu pendekatan berikut:

JavaScript inline tidak disarankan untuk aplikasi Blazor. Sebaiknya gunakan kolokasi JS yang dikombinasikan dengan modul JS.

Lokasi tag <script>

Hanya tempatkan <script> tag dalam file komponen (.razor) jika komponen dijamin untuk mengadopsi penyajian sisi server statis (SSR statis) tanpa navigasi yang ditingkatkan. Menempatkan <script> tag dalam file komponen tidak menghasilkan peringatan atau kesalahan waktu kompilasi, tetapi perilaku pemuatan skrip mungkin tidak sesuai dengan harapan Anda dalam komponen yang mengadopsi mode render interaktif atau SSR statis dengan navigasi yang ditingkatkan.

Jangan menempatkan <script> tag dalam file komponen (.razor) karena <script> tag tidak dapat diperbarui secara dinamis. Menempatkan tag <script> dalam file komponen menghasilkan kesalahan waktu kompilasi.

Catatan

Contoh dokumentasi biasanya menempatkan skrip dalam tag <script> atau memuat skrip global dari file eksternal. Pendekatan ini mencemari klien dengan fungsi global. Untuk aplikasi produksi, sebaiknya tempatkan JS modul terpisah JS yang dapat diimpor saat diperlukan. Untuk informasi lebih lanjut, lihat bagian isolasi JavaScript dalam modul JavaScript.

Catatan

Contoh dokumentasi menempatkan skrip ke dalam tag <script> atau memuat skrip global dari file eksternal. Pendekatan ini mencemari klien dengan fungsi global. Menempatkan JS ke dalam modul-modul terpisah JS yang dapat diimpor saat diperlukan tidak didukung sebelum .NET 5. Jika aplikasi memerlukan penggunaan JS modul untuk JS isolasi, sebaiknya gunakan .NET 5 atau yang lebih baru untuk membangun aplikasi. Untuk informasi selengkapnya, gunakan daftar dropdown Versi untuk memilih .NET 5 atau versi yang lebih baru dari artikel ini dan lihat bagian Isolasi JavaScript di modul JavaScript .

Memuat skrip dalam markup <head>

Pendekatan di bagian ini umumnya tidak disarankan.

Tempatkan tag JavaScript (JS) (<script>...</script>) di<head>markup elemen:

<head>
    ...

    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</head>

Memuat JS dari <head> bukanlah pendekatan terbaik karena alasan berikut:

  • Interop JS mungkin gagal jika skrip bergantung pada Blazor. Sebaiknya muat skrip menggunakan salah satu pendekatan lain, bukan melalui markup <head>.
  • Halaman dapat menjadi interaktif lebih lambat karena waktu yang diperlukan untuk menguraikan JS dalam skrip.

Dalam markup komponen, skrip dapat dimuat melalui komponen HeadContent dengan catatan umum bahwa pendekatan ini memperlambat pemuatan halaman pada sisi klien, yang sebaiknya kami hindari. Saat skrip dimuat dengan HeadContent komponen dalam aplikasi Blazor Server, aplikasi Blazor WebAssembly, atau Blazor Web App menggunakan mode render interaktif (SSR interaktif, CSR) atau SSR statis dengan navigasi yang ditingkatkan, berpindah dari halaman komponen akan menghapus tag <script> dari konten yang ditampilkan <head>, tetapi tidak membuang kode JavaScript skrip, termasuk penangan kejadian yang didaftarkan skrip, variabel yang diekspos, dan metode yang disediakan skrip. Hanya Blazor Web App yang menggunakan SSR statis tanpa navigasi yang ditingkatkan akan memuat ulang kode JavaScript saat pengguna meninggalkan halaman. Umumnya, Anda lebih baik jika menambahkan tag <script> ke konten <head> fisik, kecuali Anda memang secara khusus ingin menyimpan referensi skrip tersebut dalam komponen yang menggunakannya dan tidak masalah jika kode tidak dihapus pada peristiwa navigasi.

Dalam markup komponen, skrip dapat dimuat melalui komponen HeadContent dengan catatan umum bahwa pendekatan ini memperlambat pemuatan halaman pada sisi klien, yang sebaiknya kami hindari. Ketika skrip dimuat dengan komponen HeadContent, menavigasi jauh dari halaman komponen menghapus tag <script> dari konten <head> yang dirender tetapi tidak membongkar kode JavaScript skrip, termasuk penanganan aktivitas yang didaftarkan skrip, variabel yang diekspos, dan metode yang disediakan skrip. Umumnya, Anda lebih baik jika menambahkan tag <script> ke konten <head> fisik, kecuali Anda memang secara khusus ingin menyimpan referensi skrip tersebut dalam komponen yang menggunakannya dan tidak masalah jika kode tidak dihapus pada peristiwa navigasi.

Memuat skrip dalam markup <body>

Tempatkan tag JavaScript (<script>...</script>) di dalam </body> penutup setelah Blazor referensi skrip:

<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</body>

Dalam contoh sebelumnya, {BLAZOR SCRIPT} tempat penampung adalah Blazor jalur skrip dan nama file. Untuk lokasi skrip, lihat Blazor proyek ASP.NET Core.

Memuat skrip dari file JavaScript eksternal (.js) yang ditempatkan dengan komponen

Kolokasi file JavaScript (JS) untuk Razor komponen adalah cara mudah untuk mengatur skrip dalam aplikasi.

Razor komponen Blazor aplikasi menyusun JS file menggunakan .razor.js ekstensi dan dapat diatasi secara publik menggunakan jalur ke file dalam proyek:

{PATH}/{COMPONENT}.razor.js

  • Tempat {PATH} penampung adalah jalur ke komponen.
  • Tempat {COMPONENT} penampung adalah komponen.

Saat aplikasi diterbitkan, kerangka kerja secara otomatis memindahkan skrip ke akar web. Skrip dipindahkan ke bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.js, tempat penampung:

Tidak ada perubahan yang diperlukan pada URL relatif skrip, seperti Blazor yang mengurus penempatan JS file dalam aset statis yang diterbitkan untuk Anda.

Bagian ini dan contoh berikut terutama berfokus pada penjelasan JS kolokasi file. Contoh pertama menunjukkan file yang dikolokasi JS dengan fungsi biasa JS . Contoh kedua menunjukkan penggunaan modul untuk memuat fungsi, yang merupakan pendekatan yang direkomendasikan untuk sebagian besar aplikasi produksi. JS Panggilan dari .NET sepenuhnya tercakup dalam Blazor , di mana ada penjelasan lebih lanjut tentang BlazorJS API dengan contoh tambahan. Pembuangan komponen, yang ada dalam contoh kedua, tercakup dalam ASP.NET pembuangan komponen core Razor.

Komponen berikut JsCollocation1 memuat skrip melalui HeadContent komponen dan memanggil JS fungsi dengan IJSRuntime.InvokeAsync. Tempat {PATH} penampung adalah jalur ke komponen.

Penting

Jika Anda menggunakan kode berikut untuk demonstrasi di aplikasi pengujian, ubah {PATH} tempat penampung ke jalur komponen (misalnya: Components/Pages di .NET 8 atau yang lebih baru atau Pages di .NET 7 atau yang lebih lama). Blazor Web App Dalam (.NET 8 atau yang lebih baru), komponen memerlukan mode render interaktif yang diterapkan baik secara global ke aplikasi atau ke definisi komponen.

Tambahkan skrip berikut setelah Blazor skrip (lokasi Blazor skrip mulai):

<script src="{PATH}/JsCollocation1.razor.js"></script>

JsCollocation1 komponen ({PATH}/JsCollocation1.razor):

@page "/js-collocation-1"
@inject IJSRuntime JS

<PageTitle>JS Collocation 1</PageTitle>

<h1>JS Collocation Example 1</h1>

<button @onclick="ShowPrompt">Call showPrompt1</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

@code {
    private string? result;

    public async Task ShowPrompt()
    {
        result = await JS.InvokeAsync<string>(
            "showPrompt1", "What's your name?");
        StateHasChanged();
    }
}

File yang dikolokasi JS ditempatkan di JsCollocation1 samping file komponen dengan nama JsCollocation1.razor.jsfile . JsCollocation1 Dalam komponen, skrip dirujuk di jalur file yang dikolokasi. Dalam contoh berikut, showPrompt1 fungsi menerima nama pengguna dari Window prompt() dan mengembalikannya ke JsCollocation1 komponen untuk ditampilkan.

{PATH}/JsCollocation1.razor.js:

function showPrompt1(message) {
  return prompt(message, 'Type your name here');
}

Pendekatan sebelumnya tidak disarankan untuk penggunaan umum dalam aplikasi produksi karena pendekatan mencemari klien dengan fungsi global. Pendekatan yang lebih baik untuk aplikasi produksi adalah menggunakan JS modul. Prinsip umum yang sama berlaku untuk memuat JS modul dari file yang dikolokasi JS , seperti yang ditunjukkan contoh berikutnya.

Metode komponen berikut JsCollocation2 memuat OnAfterRenderAsync modul ke dalam JS, yang merupakan moduleIJSObjectReference kelas komponen. module digunakan untuk memanggil showPrompt2 fungsi. Tempat {PATH} penampung adalah jalur ke komponen.

Penting

Jika Anda menggunakan kode berikut untuk demonstrasi di aplikasi pengujian, ubah {PATH} tempat penampung ke jalur komponen. Blazor Web App Dalam (.NET 8 atau yang lebih baru), komponen memerlukan mode render interaktif yang diterapkan baik secara global ke aplikasi atau ke definisi komponen.

JsCollocation2 komponen ({PATH}/JsCollocation2.razor):

@page "/js-collocation-2"
@implements IAsyncDisposable
@inject IJSRuntime JS

<PageTitle>JS Collocation 2</PageTitle>

<h1>JS Collocation Example 2</h1>

<button @onclick="ShowPrompt">Call showPrompt2</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

@code {
    private IJSObjectReference? module;
    private string? result;

    protected async override Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            /*
                Change the {PATH} placeholder in the next line to the path of
                the collocated JS file in the app. Examples:

                ./Components/Pages/JsCollocation2.razor.js (.NET 8 or later)
                ./Pages/JsCollocation2.razor.js (.NET 7 or earlier)
            */
            module = await JS.InvokeAsync<IJSObjectReference>("import",
                "./{PATH}/JsCollocation2.razor.js");
        }
    }

    public async Task ShowPrompt()
    {
        if (module is not null)
        {
            result = await module.InvokeAsync<string>(
                "showPrompt2", "What's your name?");
            StateHasChanged();
        }
    }

    async ValueTask IAsyncDisposable.DisposeAsync()
    {
        if (module is not null)
        {
            try
            {
                await module.DisposeAsync();
            }
            catch (JSDisconnectedException)
            {
            }
        }
    }
}

Dalam contoh sebelumnya, JSDisconnectedException terjebak selama pembuangan modul jika Blazorsirkuit hilang SignalR . Jika kode sebelumnya digunakan dalam Blazor WebAssembly aplikasi, tidak SignalR ada koneksi yang hilang, sehingga Anda dapat menghapustry-catchblok dan meninggalkan baris yang membuang modul ().await module.DisposeAsync(); Untuk informasi selengkapnya, lihat ASP.NET Blazor interoperabilitas Core JavaScript (JS interop).

{PATH}/JsCollocation2.razor.js:

export function showPrompt2(message) {
  return prompt(message, 'Type your name here');
}

Penting

Jangan menempatkan tag <script> untuk JsCollocation2.razor.js setelah skrip Blazor karena modul dimuat dan di-cache secara otomatis ketika import() dinamis dipanggil.

Penggunaan skrip dan modul untuk dikolokasi JS di Razor pustaka kelas (RCL) hanya didukung untuk Blazormekanisme interop 's JS berdasarkan IJSRuntime antarmuka. Jika Anda menerapkan interop JavaScript[JSImport]/[JSExport], lihat .Blazor

Untuk skrip atau modul yang Razor disediakan oleh pustaka kelas (RCL) menggunakan IJSRuntimeinterop berbasis JS , jalur berikut digunakan:

./_content/{PACKAGE ID}/{PATH}/{COMPONENT}.{EXTENSION}.js

  • Segmen jalur untuk direktori saat ini (./) diperlukan untuk membuat jalur aset statis yang benar ke file JS.
  • Tempat penampung {PACKAGE ID} adalah pengidentifikasi paket RCL (atau nama pustaka untuk pustaka kelas yang dirujuk oleh aplikasi).
  • Tempat {PATH} penampung adalah jalur ke komponen. Jika komponen Razor terletak di akar RCL, segmen jalur tidak disertakan.
  • Tempat {COMPONENT} penampung adalah nama komponen.
  • Tempat {EXTENSION} penampung cocok dengan ekstensi komponen, baik razor atau cshtml.

Dalam contoh aplikasi Blazor berikut:

  • Pengidentifikasi paket RCL adalah AppJS.
  • Skrip modul dimuat untuk komponen JsCollocation3 (JsCollocation3.razor).
  • Komponen JsCollocation3 ada di folder Components/Pages RCL.
module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./_content/AppJS/Components/Pages/JsCollocation3.razor.js");

Untuk informasi lebih lanjut tentang RCL, lihat Menggunakan komponen ASP.NET Core Razor dari Razor pustaka kelas (RCL).

Memuat skrip dari file JavaScript eksternal (.js)

Tempatkan tag JavaScript (JS) (<script>...</script>) dengan jalur sumber skrip (src) di dalam </body> penutup setelah Blazor referensi skrip:

<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script src="{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

Untuk tempat penampung dalam contoh sebelumnya:

  • Tempat {BLAZOR SCRIPT} penampung adalah Blazor jalur skrip dan nama file. Untuk lokasi skrip, lihat Blazor proyek ASP.NET Core.
  • Tempat penampung {SCRIPT PATH AND FILE NAME (.js)} adalah nama file jalur dan skrip di bagian wwwroot.

Pada contoh tag <script> sebelumnya, file scripts.js ada di folder wwwroot/js aplikasi:

<script src="js/scripts.js"></script>

Anda juga dapat menyajikan skrip langsung dari wwwroot folder jika Anda lebih suka tidak menyimpan semua skrip Anda di folder terpisah di bawah wwwroot:

<script src="scripts.js"></script>

Ketika file JS eksternal disediakan oleh pustaka kelas Razor, tentukan file JS menggunakan jalur aset web statis yang stabil: _content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}:

  • Tempat penampung {PACKAGE ID} adalah ID paket pustaka. Default ID paket diatur ke nama rakitan proyek jika <PackageId> tidak ditentukan dalam file proyek.
  • Tempat penampung {SCRIPT PATH AND FILE NAME (.js)} adalah jalur dan nama file di bagian wwwroot.
<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script src="_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

Dalam contoh berikut dari tag <script> sebelumnya:

  • Pustaka kelas Razor memiliki nama rakitan ComponentLibrary, dan <PackageId> tidak ditentukan dalam file proyek pustaka.
  • File scripts.js ada di folder wwwroot pustaka kelas.
<script src="_content/ComponentLibrary/scripts.js"></script>

Untuk informasi lebih lanjut, lihat Menggunakan komponen Razor ASP.NET Core dari pustaka kelas (RCL) Razor.

Menyuntikkan skrip sebelum atau sesudah Blazor dimulai

Untuk memastikan skrip dimuat sebelum atau sesudah Blazor dimulai, gunakan penginisialisasi JavaScript. Untuk informasi dan contoh selengkapnya, lihat Blazor ASP.NET Core.

Suntikkan skrip setelah Blazor dimulai

Untuk menyuntikkan skrip setelah Blazor dimulai, rantai ke hasil tersebut Promise dari awal Blazormanual . Untuk informasi selengkapnya dan contohnya, lihat Blazor ASP.NET Core.

Isolasi JavaScript dalam modul JavaScript

Blazormengaktifkan isolasi JavaScript (JS) dalam modulJS (spesifikasi ECMAScript).

JS isolasi memberikan manfaat berikut:

  • JS yang diimpor tidak lagi mencemari namespace global.
  • Konsumen pustaka dan komponen tidak perlu mengimpor JS terkait.

Dalam skenario sisi server, selalu perangkap JSDisconnectedException jika hilangnya BlazorSignalR sirkuit JS mencegah panggilan interop membuang modul, yang menghasilkan pengecualian yang tidak tertangani. Blazor WebAssembly aplikasi tidak menggunakan SignalR koneksi selama JS interop, jadi tidak perlu menjebak JSDisconnectedException aplikasi Blazor WebAssembly untuk pembuangan modul.

Untuk informasi selengkapnya, lihat sumber daya berikut: