Bagikan melalui

Lokasi JavaScript di aplikasi ASP.NET Core Blazor

  • Artikel

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 8 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:

Peringatan

Hanya tempatkan <script> tag dalam file komponen (.razor) jika komponen dijamin untuk mengadopsi penyajian sisi server statis (SSR statis) karena <script> tag tidak dapat diperbarui secara dinamis.

Peringatan

Jangan menempatkan <script> tag dalam file komponen (.razor) karena <script> tag tidak dapat diperbarui secara dinamis.

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 modul terpisah JS yang dapat diimpor saat diperlukan tidak didukung lebih Blazor awal dari ASP.NET Core 5.0. Jika aplikasi memerlukan penggunaan modul JS untuk isolasi JS, sebaiknya gunakan ASP.NET Core 5.0 atau yang lebih baru untuk membangun aplikasi. Untuk informasi lebih lanjut, gunakan daftar dropdown Versi untuk memilih versi 5.0 atau yang lebih baru dari artikel ini dan lihat bagian isolasi JavaScript dalam 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.

Memuat skrip dalam markup <body>

Tempatkan tag JavaScript (<script>...</script>) di dalam elemen penutup </body> 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 struktur proyek ASP.NET CoreBlazor.

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 fungsi Call JavaScript dari metode .NET di ASP.NET CoreBlazor , di mana ada penjelasan lebih lanjut tentang BlazorJS API dengan contoh tambahan. Pembuangan komponen, yang ada dalam contoh kedua, tercakup dalam siklus hidup komponen ASP.NET CoreRazor.

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 void 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 JS modul ke dalam module, yang merupakan IJSObjectReference OnAfterRenderAsync 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 void 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)
        {
            await module.DisposeAsync();
        }
    }
}

{PATH}/JsCollocation2.razor.js:

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

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 Interop JavaScript JSImport/JSExport dengan ASP.NET Core 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 elemen penutup </body> 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 struktur proyek ASP.NET CoreBlazor.
  • 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 startup ASP.NET CoreBlazor.

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 startup ASP.NET CoreBlazor.

Isolasi JavaScript dalam modul JavaScript

Blazormengaktifkan isolasi JavaScript (JS) dalam modul standar JS (spesifikasi ECMAScript).

JS isolasi memberikan manfaat berikut:

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

Untuk informasi lebih lanjut, lihat Memanggil fungsi JavaScript dari metode .NET di Blazor ASP.NET Core.

Impor dinamis dengan import() operator didukung dengan ASP.NET Core dan Blazor:

if ({CONDITION}) import("/additionalModule.js");

Dalam contoh sebelumnya, {CONDITION} tempat penampung mewakili pemeriksaan bersyariah untuk menentukan apakah modul harus dimuat.

Untuk kompatibilitas browser, lihat Dapatkah saya menggunakan: modul JavaScript: impor dinamis.