Memanggil fungsi JavaScript dari metode .NET di ASP.NET Core Blazor

Artikel ini menjelaskan cara memanggil fungsi JavaScript (JS) dari .NET.

Untuk informasi tentang cara memanggil metode .NET dari JS, lihat Memanggil metode .NET dari fungsi JavaScript di ASP.NET Core Blazor.

Memanggil fungsi JS

IJSRuntime didaftarkan oleh kerangka kerja Blazor. Untuk memanggil JS dari .NET, masukkan IJSRuntime abstraksi dan panggil salah satu metode berikut:

• IJSRuntime.InvokeAsync
• JSRuntimeExtensions.InvokeAsync
• JSRuntimeExtensions.InvokeVoidAsync

Untuk metode .NET sebelumnya yang memanggil JS fungsi:

• Pengidentifikasi fungsi (String) relatif terhadap cakupan global (window). Untuk memanggil window.someScope.someFunction, pengidentifikasinya adalah someScope.someFunction. Tidak perlu mendaftarkan fungsi sebelum dipanggil.
• Teruskan sejumlah argumen JSON yang dapat diserialisasikan di Object[] ke fungsi JS.
• Token pembatalan (CancellationToken) menyebarkan pemberitahuan bahwa operasi harus dibatalkan.
• TimeSpan mewakili batas waktu untuk JS operasi.
• Jenis TValue pengembalian juga harus dapat diserialisasikan JSON. TValue harus sesuai dengan jenis .NET yang paling cocok dengan jenis JSON yang dikembalikan.
• JS Promise dikembalikan untuk InvokeAsync metode. InvokeAsync membongkar Promise dan mengembalikan nilai yang ditunggu oleh Promise.

Untuk aplikasi Blazor dengan prarender diaktifkan, yang merupakan default untuk aplikasi sisi server, memanggil JS tidak dimungkinkan selama prarender. Untuk informasi selengkapnya, lihat bagian Prarendering.

Contoh berikut didasarkan pada TextDecoder, dekoder yang berbasis pada JS. Contoh menunjukkan cara memanggil fungsi JS dari metode C# yang memindahkan persyaratan dari kode pengembang ke JS API yang sudah ada. Fungsi JS menerima array byte dari metode C#, mendekode array, dan mengembalikan teks ke komponen untuk ditampilkan.

<script>
  window.convertArray = (win1251Array) => {
    var win1251decoder = new TextDecoder('windows-1251');
    var bytes = new Uint8Array(win1251Array);
    var decodedArray = win1251decoder.decode(bytes);
    return decodedArray;
  };
</script>

Catatan

Untuk panduan umum tentang JS lokasi dan rekomendasi kami untuk aplikasi produksi, lihat Lokasi JavaScript di aplikasi ASP.NET Core Blazor.

Komponen berikut:

• convertArray JS Memanggil fungsi dengan InvokeAsync saat memilih tombol (Convert Array).
• Setelah fungsi dipanggil JS , array yang dilewatkan dikonversi menjadi string. String dikembalikan ke komponen untuk ditampilkan (text).

CallJs1.razor:

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

<PageTitle>Call JS 1</PageTitle>

<h1>Call JS Example 1</h1>

<p>
    <button @onclick="ConvertArray">Convert Array</button>
</p>

<p>
    @text
</p>

<p>
    Quote ©2005 <a href="https://www.uphe.com">Universal Pictures</a>: 
    <a href="https://www.uphe.com/movies/serenity-2005">Serenity</a><br>
    <a href="https://www.imdb.com/name/nm0472710/">David Krumholtz on IMDB</a>
</p>

@code {
    private MarkupString text;

    private uint[] quoteArray = 
        new uint[]
        {
            60, 101, 109, 62, 67, 97, 110, 39, 116, 32, 115, 116, 111, 112, 32,
            116, 104, 101, 32, 115, 105, 103, 110, 97, 108, 44, 32, 77, 97,
            108, 46, 60, 47, 101, 109, 62, 32, 45, 32, 77, 114, 46, 32, 85, 110,
            105, 118, 101, 114, 115, 101, 10, 10,
        };

    private async Task ConvertArray() => 
        text = new(await JS.InvokeAsync<string>("convertArray", quoteArray));
}

JAVAScript API dibatasi untuk gerakan pengguna

Bagian ini berlaku untuk komponen sisi server.

Beberapa API JavaScript (JS) browser hanya dapat dijalankan dalam konteks gerakan pengguna, seperti menggunakan Fullscreen API. API ini tidak dapat dipanggil melalui JS mekanisme interop dalam komponen sisi server karena penanganan peristiwa UI dilakukan secara asinkron dan umumnya tidak lagi dalam konteks gerakan pengguna. Aplikasi harus menangani peristiwa UI sepenuhnya di JavaScript, jadi gunakan onclick alih-alih Blazor's @onclick atribut direktif tersebut.

Memanggil fungsi JavaScript tanpa membaca nilai yang dikembalikan (InvokeVoidAsync)

Gunakan InvokeVoidAsync saat:

• .NET tidak diperlukan untuk membaca hasil panggilan JavaScript (JS).
• JS fungsi mengembalikan void(0)/void 0 atau tidak terdefinisi.

Sediakan fungsi displayTickerAlert1JS. Fungsi ini dipanggil dengan InvokeVoidAsync dan tidak mengembalikan nilai:

<script>
  window.displayTickerAlert1 = (symbol, price) => {
    alert(`${symbol}: $${price}!`);
  };
</script>

Catatan

Untuk panduan umum tentang JS lokasi dan rekomendasi kami untuk aplikasi produksi, lihat Lokasi JavaScript di aplikasi ASP.NET Core Blazor.

Contoh komponen (.razor) (InvokeVoidAsync)

TickerChanged memanggil metode handleTickerChanged1 dalam komponen berikut.

CallJs2.razor:

@page "/call-js-2"
@inject IJSRuntime JS

<PageTitle>Call JS 2</PageTitle>

<h1>Call JS Example 2</h1>

<p>
    <button @onclick="SetStock">Set Stock</button>
</p>

@if (stockSymbol is not null)
{
    <p>@stockSymbol price: @price.ToString("c")</p>
}

@code {
    private string? stockSymbol;
    private decimal price;

    private async Task SetStock()
    {
        stockSymbol = 
            $"{(char)('A' + Random.Shared.Next(0, 26))}" +
            $"{(char)('A' + Random.Shared.Next(0, 26))}";
        price = Random.Shared.Next(1, 101);
        await JS.InvokeVoidAsync("displayTickerAlert1", stockSymbol, price);
    }
}

Contoh kelas (.cs) (InvokeVoidAsync)

JsInteropClasses1.cs:

using Microsoft.JSInterop;

namespace BlazorSample;

public class JsInteropClasses1(IJSRuntime js) : IDisposable
{
    private readonly IJSRuntime js = js;

    public async ValueTask TickerChanged(string symbol, decimal price) => 
        await js.InvokeVoidAsync("displayTickerAlert1", symbol, price);

    // Calling SuppressFinalize(this) prevents derived types that introduce 
    // a finalizer from needing to re-implement IDisposable.
    public void Dispose() => GC.SuppressFinalize(this);
}

TickerChanged memanggil metode handleTickerChanged1 dalam komponen berikut.

CallJs3.razor:

@page "/call-js-3"
@implements IDisposable
@inject IJSRuntime JS

<PageTitle>Call JS 3</PageTitle>

<h1>Call JS Example 3</h1>

<p>
    <button @onclick="SetStock">Set Stock</button>
</p>

@if (stockSymbol is not null)
{
    <p>@stockSymbol price: @price.ToString("c")</p>
}

@code {
    private string? stockSymbol;
    private decimal price;
    private JsInteropClasses1? jsClass;

    protected override void OnInitialized() => jsClass = new(JS);

    private async Task SetStock()
    {
        if (jsClass is not null)
        {
            stockSymbol = 
                $"{(char)('A' + Random.Shared.Next(0, 26))}" +
                $"{(char)('A' + Random.Shared.Next(0, 26))}";
            price = Random.Shared.Next(1, 101);
            await jsClass.TickerChanged(stockSymbol, price);
        }
    }

    public void Dispose() => jsClass?.Dispose();
}

Memanggil fungsi JavaScript dan membaca nilai yang dikembalikan (InvokeAsync)

Gunakan InvokeAsync saat .NET harus membaca hasil panggilan JavaScript (JS).

Sediakan fungsi displayTickerAlert2JS. Contoh berikut mengembalikan string untuk ditampilkan oleh pemanggil:

<script>
  window.displayTickerAlert2 = (symbol, price) => {
    if (price < 20) {
      alert(`${symbol}: $${price}!`);
      return "User alerted in the browser.";
    } else {
      return "User NOT alerted.";
    }
  };
</script>

Catatan

Untuk panduan umum tentang JS lokasi dan rekomendasi kami untuk aplikasi produksi, lihat Lokasi JavaScript di aplikasi ASP.NET Core Blazor.

Contoh komponen (.razor) (InvokeAsync)

TickerChanged handleTickerChanged2 memanggil metode dan menampilkan string yang dikembalikan dalam komponen berikut.

CallJs4.razor:

@page "/call-js-4"
@inject IJSRuntime JS

<PageTitle>Call JS 4</PageTitle>

<h1>Call JS Example 4</h1>

<p>
    <button @onclick="SetStock">Set Stock</button>
</p>

@if (stockSymbol is not null)
{
    <p>@stockSymbol price: @price.ToString("c")</p>
}

@if (result is not null)
{
    <p>@result</p>
}

@code {
    private string? stockSymbol;
    private decimal price;
    private string? result;

    private async Task SetStock()
    {
        stockSymbol = 
            $"{(char)('A' + Random.Shared.Next(0, 26))}" +
            $"{(char)('A' + Random.Shared.Next(0, 26))}";
        price = Random.Shared.Next(1, 101);
        var interopResult = 
            await JS.InvokeAsync<string>("displayTickerAlert2", stockSymbol, price);
        result = $"Result of TickerChanged call for {stockSymbol} at " +
            $"{price.ToString("c")}: {interopResult}";
    }
}

Contoh kelas (.cs) (InvokeAsync)

JsInteropClasses2.cs:

using Microsoft.JSInterop;

namespace BlazorSample;

public class JsInteropClasses2(IJSRuntime js) : IDisposable
{
    private readonly IJSRuntime js = js;

    public async ValueTask<string> TickerChanged(string symbol, decimal price) => 
        await js.InvokeAsync<string>("displayTickerAlert2", symbol, price);

    // Calling SuppressFinalize(this) prevents derived types that introduce 
    // a finalizer from needing to re-implement IDisposable.
    public void Dispose() => GC.SuppressFinalize(this);
}

TickerChanged handleTickerChanged2 memanggil metode dan menampilkan string yang dikembalikan dalam komponen berikut.

CallJs5.razor:

@page "/call-js-5"
@implements IDisposable
@inject IJSRuntime JS

<PageTitle>Call JS 5</PageTitle>

<h1>Call JS Example 5</h1>

<p>
    <button @onclick="SetStock">Set Stock</button>
</p>

@if (stockSymbol is not null)
{
    <p>@stockSymbol price: @price.ToString("c")</p>
}

@if (result is not null)
{
    <p>@result</p>
}

@code {
    private string? stockSymbol;
    private decimal price;
    private JsInteropClasses2? jsClass;
    private string? result;

    protected override void OnInitialized() => jsClass = new(JS);

    private async Task SetStock()
    {
        if (jsClass is not null)
        {
            stockSymbol = 
                $"{(char)('A' + Random.Shared.Next(0, 26))}" +
                $"{(char)('A' + Random.Shared.Next(0, 26))}";
            price = Random.Shared.Next(1, 101);
            var interopResult = await jsClass.TickerChanged(stockSymbol, price);
            result = $"Result of TickerChanged call for {stockSymbol} at " +
                $"{price.ToString("c")}: {interopResult}";
        }
    }

    public void Dispose() => jsClass?.Dispose();
}

Skenario pembuatan konten dinamis

Untuk pembuatan konten dinamis dengan BuildRenderTree, gunakan [Inject] atribut :

[Inject]
IJSRuntime JS { get; set; }

Pra-penyajian

Bagian ini berlaku untuk aplikasi sisi server yang memproses Razor komponen sebelumnya. Prerendering dicakup dalam Komponen Prerender ASP.NET Core.

Catatan

Navigasi internal untuk perutean interaktif dalam Blazor Web App tidak melibatkan permintaan konten halaman baru dari server. Oleh karena itu, pra-pemuatan tidak terjadi untuk permintaan halaman internal. Jika aplikasi mengadopsi perutean interaktif, lakukan pemuatan ulang halaman penuh untuk contoh komponen yang menunjukkan perilaku prarender. Untuk informasi selengkapnya, lihat Komponen Prerender ASP.NET CoreRazor.

Selama prarendering, panggilan ke JavaScript (JS) tidak dimungkinkan. Contoh berikut menunjukkan cara menggunakan JS interop sebagai bagian dari logika inisialisasi komponen dengan cara yang kompatibel dengan pra-penyajian.

Fungsi berikut scrollElementIntoView :

• Menggulir ke elemen yang dilewatkan dengan scrollIntoView.
• Mengembalikan nilai properti elemen top dari getBoundingClientRect metode .

window.scrollElementIntoView = (element) => {
  element.scrollIntoView();
  return element.getBoundingClientRect().top;
}

Ketika memanggil fungsi dalam kode komponen, hanya digunakan dalam dan bukan dalam metode siklus hidup sebelumnya karena elemen HTML DOM baru tersedia setelah komponen dirender.

StateHasChanged(sumber referensi) dipanggil untuk mengantrekan penyajian ulang komponen dengan status baru yang diperoleh dari JS panggilan interop (untuk informasi selengkapnya, lihat ASP.NET Core Razor penyajian komponen). Perulangan tak terbatas tidak dibuat karena StateHasChanged hanya dipanggil ketika scrollPosition adalah null.

PrerenderedInterop.razor:

@page "/prerendered-interop"
@using Microsoft.AspNetCore.Components
@using Microsoft.JSInterop
@inject IJSRuntime JS

<PageTitle>Prerendered Interop</PageTitle>

<h1>Prerendered Interop Example</h1>

<div @ref="divElement" style="margin-top:2000px">
    Set value via JS interop call: <strong>@scrollPosition</strong>
</div>

@code {
    private ElementReference divElement;
    private double? scrollPosition;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender && scrollPosition is null)
        {
            scrollPosition = await JS.InvokeAsync<double>(
                "scrollElementIntoView", divElement);

            StateHasChanged();
        }
    }
}

Contoh sebelumnya mencemari klien dengan fungsi global. Untuk pendekatan yang lebih baik dalam aplikasi produksi, lihat Isolasi JavaScript dalam modul JavaScript.

Interop sinkron JS dalam komponen sisi klien

Bagian ini hanya berlaku untuk komponen sisi klien.

JS panggilan interop bersifat asinkron, terlepas dari apakah kode yang dipanggil bersifat sinkron atau asinkron. Panggilan bersifat asinkron untuk memastikan bahwa komponen kompatibel di seluruh mode render sisi server dan sisi klien. Di server, semua JS panggilan interop harus asinkron karena dikirim melalui koneksi jaringan.

Jika Anda yakin bahwa komponen Anda hanya berjalan di WebAssembly, Anda dapat memilih untuk melakukan panggilan interop secara sinkron JS. Ini memiliki overhead yang sedikit lebih sedikit daripada melakukan panggilan asinkron dan dapat mengakibatkan lebih sedikit siklus render karena tidak ada status menengah saat menunggu hasil.

Untuk membuat panggilan sinkron dari .NET ke JavaScript dalam komponen klien, konversikan IJSRuntime ke IJSInProcessRuntime untuk melakukan panggilan interop JS.

@inject IJSRuntime JS

...

@code {
    protected override void HandleSomeEvent()
    {
        var jsInProcess = (IJSInProcessRuntime)JS;
        var value = jsInProcess.Invoke<string>("javascriptFunctionIdentifier");
    }
}

Saat bekerja dengan IJSObjectReference di komponen sisi klien .NET 5 atau yang lebih baru, Anda dapat menggunakan IJSInProcessObjectReference secara sinkron sebagai gantinya. IJSInProcessObjectReference mengimplementasikan IAsyncDisposable/IDisposable dan harus dibuang untuk pengumpulan sampah guna mencegah kebocoran memori, seperti yang ditunjukkan dalam contoh berikut:

@inject IJSRuntime JS
@implements IDisposable

...

@code {
    ...
    private IJSInProcessObjectReference? module;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            var jsInProcess = (IJSInProcessRuntime)JS;
            module = await jsInProcess.Invoke<IJSInProcessObjectReference>("import", 
                "./scripts.js");
            var value = module.Invoke<string>("javascriptFunctionIdentifier");
        }
    }

    ...

    void IDisposable.Dispose()
    {
        if (module is not null)
        {
            await module.Dispose();
        }
    }
}

Dalam contoh sebelumnya, JSDisconnectedException tidak terjebak selama pembuangan modul karena tidak ada sirkuit Blazor-SignalR di dalam aplikasi Blazor WebAssembly yang bisa hilang. Untuk informasi selengkapnya, lihat ASP.NET Blazor interoperabilitas Core JavaScript (JS interop).

Lokasi JavaScript

Muat kode JavaScript (JS) menggunakan salah satu pendekatan yang dijelaskan oleh artikel tentang lokasi JavaScript:

• Memuat skrip dalam markup<head> (Tidak disarankan secara umum)
• Memuat skrip dalam markup<body>
• Memuat skrip dari file JavaScript eksternal (.js) yang ditempatkan bersamaan dengan komponen
• Memuat skrip dari file JavaScript eksternal (.js)
• Menyuntikkan skrip sebelum atau sesudah Blazor dimulai

Untuk informasi tentang mengisolasi skrip dalam JS modul, lihat bagian Isolasi JavaScript di modul JavaScript.

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.

Isolasi JavaScript dalam modul JavaScript

Blazor mengaktifkan isolasi JavaScript (JS) dalam modul JavaScript standar (spesifikasi ECMAScript). Pemuatan modul JavaScript berfungsi dengan cara yang sama di Blazor seperti untuk jenis aplikasi web lainnya, dan Anda bebas menyesuaikan cara modul ditentukan di aplikasi Anda. Untuk panduan tentang cara menggunakan modul JavaScript, lihat MDN Web Docs: Modul JavaScript.

JS isolasi memberikan manfaat berikut:

• JS yang diimpor tidak lagi mencemari namespace global.
• Pengguna perpustakaan dan komponen tidak perlu mengimpor JS yang terkait.

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 kondisi untuk menentukan apakah modul harus dimuat.

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

Dalam skenario sisi server, panggilan interop JS tidak dapat dikeluarkan setelah sirkuit BlazorSignalR terputus. Tanpa adanya sirkuit selama pembuangan komponen atau kapan pun saat sirkuit tidak ada, panggilan metode berikut akan gagal dan mencatat pesan bahwa sirkuit terputus sebagai JSDisconnectedException:

• JS panggilan metode interop
  • IJSRuntime.InvokeAsync
  • JSRuntimeExtensions.InvokeAsync
  • JSRuntimeExtensions.InvokeVoidAsync
• Dispose / DisposeAsync memanggil pada setiap IJSObjectReference.

Untuk menghindari pengelogan JSDisconnectedException atau mencatat informasi kustom di sisi Blazorserver, tangkap pengecualian dalam pernyataan try-catch .

Untuk contoh pembuangan komponen berikut:

• Komponen sisi server mengimplementasikan IAsyncDisposable.
• module merupakan sebuah IJSObjectReference untuk modul JS.
• JSDisconnectedException tertangkap tetapi tidak dicatat.
• Secara opsional, Anda dapat mencatat informasi kustom dalam pernyataan catch pada tingkat log yang Anda suka. Contoh berikut tidak mencatat informasi kustom. Kode mengasumsikan bahwa pengembang tidak peduli tentang kapan atau di mana sirkuit terputus selama pembuangan komponen.

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

Jika Anda harus membersihkan objek Anda sendiri JS atau menjalankan kode lain JS pada klien setelah sirkuit hilang di aplikasi sisi Blazor server, gunakan MutationObserver pola di JS pada klien. Pola MutationObserver ini memungkinkan Anda menjalankan kode JS saat elemen dihapus dari DOM.

Untuk informasi lebih lanjut, baca artikel berikut:

• Interoperabilitas JavaScript ASP.NET Core Blazor (JS interop): Menyertakan contoh kode dari MutationObserver pola.
• Blazor: Bagian JavaScript interop membahas penanganan kesalahan dalam skenario interop.
• ASP.NET Core Razor pembuangan komponen: Artikel ini menjelaskan cara menerapkan pola pembuangan dalam komponen Razor.

Modul berikut JS mengekspor JS fungsi untuk menampilkan kotak dialog di jendela browser. Tempatkan kode berikut JS dalam file eksternal JS .

wwwroot/scripts.js:

export function showPrompt(message) {
  return prompt(message, 'Type anything here');
}

Tambahkan modul JS yang disebutkan sebelumnya ke aplikasi atau pustaka kelas sebagai aset web statis di folder wwwroot dan kemudian impor modul ke dalam kode .NET dengan memanggil InvokeAsync pada instans IJSRuntime.

IJSRuntime mengimpor modul sebagai IJSObjectReference, yang mewakili referensi ke JS objek dari kode .NET. Gunakan IJSObjectReference untuk memanggil fungsi JS yang diekspor dari modul.

CallJs6.razor:

@page "/call-js-6"
@implements IAsyncDisposable
@inject IJSRuntime JS

<PageTitle>Call JS 6</PageTitle>

<h1>Call JS Example 6</h1>

<p>
    <button @onclick="TriggerPrompt">Trigger browser window prompt</button>
</p>

<p>
    @result
</p>

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

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            module = await JS.InvokeAsync<IJSObjectReference>("import",
                "./scripts.js");
        }
    }

    private async Task TriggerPrompt() => result = await Prompt("Provide text");

    public async ValueTask<string?> Prompt(string message) =>
        module is not null ? 
            await module.InvokeAsync<string>("showPrompt", message) : null;

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

Dalam contoh sebelumnya:

• Menurut konvensi, import pengidentifikasi adalah penanda khusus yang digunakan secara spesifik untuk mengimpor JS modul.
• Tentukan file eksternal JS modul menggunakan jalur aset web statis yang stabil: ./{SCRIPT PATH AND FILE NAME (.js)}, di mana:
  • Segmen jalur untuk direktori saat ini (./) diperlukan untuk membuat jalur aset statis yang benar ke file JS.
  • Placeholder {SCRIPT PATH AND FILE NAME (.js)} adalah jalur dan nama file di bawah wwwroot.
• Membuang IJSObjectReference untuk pengumpulan sampah di IAsyncDisposable.DisposeAsync.
• Jangan menempatkan tag <script> untuk skrip setelah skrip Blazor karena modul dimuat dan di-cache secara otomatis saat dinamis import() dipanggil.

Mengimpor modul secara dinamis memerlukan permintaan jaringan, sehingga hanya dapat dicapai secara asinkron dengan memanggil InvokeAsync.

IJSInProcessObjectReference mewakili referensi ke JS objek yang fungsinya dapat dipanggil secara sinkron dalam komponen sisi klien. Untuk informasi selengkapnya, lihat bagian Interoperabilitas sinkron JS pada komponen sisi klien.

Catatan

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

• Segmen jalur untuk direktori saat ini (./) diperlukan untuk membuat jalur aset statis yang benar ke file JS.
• Tempat penampung {PACKAGE ID} adalah ID paket pustaka. ID paket secara default akan diatur ke nama rakitan proyek jika <PackageId> tidak ditentukan dalam file proyek. Dalam contoh berikut, nama rakitan pustaka adalah ComponentLibrary dan file proyek pustaka tidak menentukan <PackageId>.
• Placeholder {SCRIPT PATH AND FILE NAME (.js)} adalah jalur dan nama file di bawah wwwroot. Dalam contoh berikut, file eksternal JS (script.js) ditempatkan di folder wwwroot pustaka kelas.
• module adalah IJSObjectReference yang dapat bernilai null privat dari kelas komponen (private IJSObjectReference? module;).

module = await js.InvokeAsync<IJSObjectReference>(
    "import", "./_content/ComponentLibrary/scripts.js");

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

Sepanjang Blazor dokumentasi, contoh menggunakan .js ekstensi file untuk file modul, bukan ekstensi file yang lebih .mjs baru (RFC 9239). Dokumentasi kami terus menggunakan .js ekstensi file karena alasan yang sama dokumentasi Mozilla Foundation terus menggunakan .js ekstensi file. Untuk informasi selengkapnya, lihat Aside — .mjs versus .js (dokumentasi MDN).

Mengambil referensi ke elemen

Beberapa skenario interop JavaScript (JS) memerlukan referensi ke elemen HTML. Misalnya, pustaka UI mungkin memerlukan referensi elemen untuk inisialisasi, atau Anda mungkin perlu memanggil API seperti perintah pada elemen, seperti click atau play.

Ambil referensi ke elemen HTML dalam komponen menggunakan pendekatan berikut:

• @ref Tambahkan atribut ke elemen HTML.
• Tentukan bidang jenis ElementReference yang namanya cocok dengan nilai @ref atribut.

Contoh berikut menunjukkan pengambilan referensi ke username<input> elemen :

<input @ref="username" ... />

@code {
    private ElementReference username;
}

Peringatan

Hanya gunakan referensi elemen untuk bermutasi konten elemen kosong yang tidak berinteraksi dengan Blazor. Skenario ini berguna ketika API pihak ketiga memasok konten ke elemen . Karena Blazor tidak berinteraksi dengan elemen , tidak ada kemungkinan konflik antara Blazorrepresentasi elemen dan DOM.

Dalam contoh berikut, berbahaya untuk bermutasi konten daftar yang tidak diurutkan (ul) menggunakan MyList melalui JS interop karena Blazor berinteraksi dengan DOM untuk mengisi item daftar elemen ini (<li>) dari Todos objek:

<ul @ref="MyList">
    @foreach (var item in Todos)
    {
        <li>@item.Text</li>
    }
</ul>

MyList Menggunakan referensi elemen untuk hanya membaca konten DOM atau memicu peristiwa didukung.

Jika JS interop mengubah konten elemen MyList dan Blazor menerapkan perubahan pada elemen tersebut, perubahan tersebut tidak akan cocok dengan DOM. Mengubah konten daftar melalui JS interop dengan MyList elemen referensi tidak didukung.

Untuk informasi selengkapnya, lihat ASP.NET Blazor interoperabilitas Core JavaScript (JS interop).

Sebuah ElementReference diteruskan ke JS kode melalui JS interop. Kode JS menerima instans HTMLElement , yang dapat digunakan dengan API DOM normal. Misalnya, kode berikut menentukan metode ekstensi .NET (TriggerClickEvent) yang memungkinkan pengiriman klik mouse ke elemen.

Fungsi JSclickElement membuat sebuah click event pada elemen HTML yang diberikan (element):

window.interopFunctions = {
  clickElement : function (element) {
    element.click();
  }
}

Untuk memanggil JS fungsi yang tidak mengembalikan nilai, gunakan JSRuntimeExtensions.InvokeVoidAsync. Kode berikut memicu peristiwa pada sisi klien click dengan memanggil fungsi sebelumnya JS dengan data yang ditangkap ElementReference:

@inject IJSRuntime JS

<button @ref="exampleButton">Example Button</button>

<button @onclick="TriggerClick">
    Trigger click event on <code>Example Button</code>
</button>

@code {
    private ElementReference exampleButton;

    public async Task TriggerClick()
    {
        await JS.InvokeVoidAsync(
            "interopFunctions.clickElement", exampleButton);
    }
}

Untuk menggunakan metode ekstensi, buat metode ekstensi statis yang menerima instans IJSRuntime :

public static async Task TriggerClickEvent(this ElementReference elementRef, 
    IJSRuntime js)
{
    await js.InvokeVoidAsync("interopFunctions.clickElement", elementRef);
}

Metode clickElement ini dipanggil langsung pada objek . Contoh berikut mengasumsikan bahwa TriggerClickEvent metode tersedia dari JsInteropClasses namespace:

@inject IJSRuntime JS
@using JsInteropClasses

<button @ref="exampleButton">Example Button</button>

<button @onclick="TriggerClick">
    Trigger click event on <code>Example Button</code>
</button>

@code {
    private ElementReference exampleButton;

    public async Task TriggerClick()
    {
        await exampleButton.TriggerClickEvent(JS);
    }
}

Penting

Variabel exampleButton baru akan diisi setelah komponen selesai dirender. Jika ElementReference yang tidak diisi diteruskan ke kode JS, maka kode JS menerima nilai null. Untuk memanipulasi referensi elemen setelah komponen selesai dirender, gunakan metode siklus hidup komponen seperti OnAfterRenderAsync atau OnAfterRender.

Saat bekerja dengan jenis generik dan mengembalikan nilai, gunakan ValueTask<TResult>:

public static ValueTask<T> GenericMethod<T>(
        this ElementReference elementRef, IJSRuntime js) => 
    js.InvokeAsync<T>("{JAVASCRIPT FUNCTION}", elementRef);

Placeholder {JAVASCRIPT FUNCTION} adalah pengidentifikasi fungsi JS.

GenericMethod dipanggil langsung pada objek dengan tipe. Contoh berikut mengasumsikan bahwa GenericMethod tersedia dari JsInteropClasses namespace:

@inject IJSRuntime JS
@using JsInteropClasses

<input @ref="username" />

<button @onclick="OnClickMethod">Do something generic</button>

<p>
    returnValue: @returnValue
</p>

@code {
    private ElementReference username;
    private string? returnValue;

    private async Task OnClickMethod()
    {
        returnValue = await username.GenericMethod<string>(JS);
    }
}

Elemen referensi di seluruh komponen

ElementReference Tidak dapat diteruskan antar komponen karena:

• Instans hanya dijamin ada setelah komponen dirender, yaitu selama atau setelah metode komponen OnAfterRender/OnAfterRenderAsync dijalankan.
• ElementReference adalah struct, yang tidak dapat diteruskan sebagai komponen parameter.

Agar komponen induk membuat referensi elemen tersedia untuk komponen lain, komponen induk dapat:

• Perbolehkan komponen anak mendaftarkan panggilan balik.
• Panggil callback yang terdaftar pada OnAfterRender event dengan referensi elemen yang diteruskan. Secara tidak langsung, pendekatan ini memungkinkan komponen turunan untuk berinteraksi dengan referensi elemen induk.

<style>
    .red { color: red }
</style>

<script>
  function setElementClass(element, className) {
    var myElement = element;
    myElement.classList.add(className);
  }
</script>

Catatan

Untuk panduan umum tentang JS lokasi dan rekomendasi kami untuk aplikasi produksi, lihat Lokasi JavaScript di aplikasi ASP.NET Core Blazor.

CallJs7.razor (komponen induk):

@page "/call-js-7"

<PageTitle>Call JS 7</PageTitle>

<h1>Call JS Example 7</h1>

<h2 @ref="title">Hello, world!</h2>

Welcome to your new app.

<SurveyPrompt Parent="this" Title="How is Blazor working for you?" />

CallJs7.razor.cs:

using Microsoft.AspNetCore.Components;

namespace BlazorSample.Pages;

public partial class CallJs7 : 
    ComponentBase, IObservable<ElementReference>, IDisposable
{
    private bool disposing;
    private readonly List<IObserver<ElementReference>> subscriptions = [];
    private ElementReference title;

    protected override void OnAfterRender(bool firstRender)
    {
        base.OnAfterRender(firstRender);

        foreach (var subscription in subscriptions)
        {
            subscription.OnNext(title);
        }
    }

    public void Dispose()
    {
        disposing = true;

        foreach (var subscription in subscriptions)
        {
            try
            {
                subscription.OnCompleted();
            }
            catch (Exception)
            {
            }
        }

        subscriptions.Clear();

        // The following prevents derived types that introduce a
        // finalizer from needing to re-implement IDisposable.
        GC.SuppressFinalize(this);
    }

    public IDisposable Subscribe(IObserver<ElementReference> observer)
    {
        if (disposing)
        {
            throw new InvalidOperationException("Parent being disposed");
        }

        subscriptions.Add(observer);

        return new Subscription(observer, this);
    }

    private class Subscription(IObserver<ElementReference> observer,
        CallJs7 self) : IDisposable
    {
        public IObserver<ElementReference> Observer { get; } = observer;
        public CallJs7 Self { get; } = self;

        public void Dispose() => Self.subscriptions.Remove(Observer);
    }
}

Dalam contoh sebelumnya, namespace aplikasi adalah BlazorSample. Jika menguji kode secara lokal, perbarui namespace.

SurveyPrompt.razor (komponen anak):

<div class="alert alert-secondary mt-4">
    <span class="oi oi-pencil me-2" aria-hidden="true"></span>
    <strong>@Title</strong>

    <span class="text-nowrap">
        Please take our
        <a target="_blank" class="font-weight-bold link-dark" href="https://go.microsoft.com/fwlink/?linkid=2186158">brief survey</a>
    </span>
    and tell us what you think.
</div>

@code {
    // Demonstrates how a parent component can supply parameters
    [Parameter]
    public string? Title { get; set; }
}

SurveyPrompt.razor.cs:

using Microsoft.AspNetCore.Components;
using Microsoft.JSInterop;

namespace BlazorSample.Components;

public partial class SurveyPrompt : 
    ComponentBase, IObserver<ElementReference>, IDisposable
{
    private IDisposable? subscription = null;

    [Parameter]
    public IObservable<ElementReference>? Parent { get; set; }

    [Inject]
    public IJSRuntime? JS {get; set;}

    protected override void OnParametersSet()
    {
        base.OnParametersSet();

        subscription?.Dispose();
        subscription = Parent?.Subscribe(this);
    }

    public void OnCompleted() => subscription = null;

    public void OnError(Exception error) => subscription = null;

    public void OnNext(ElementReference value) =>
        _ = (JS?.InvokeAsync<object>("setElementClass", [ value, "red" ]));

    public void Dispose()
    {
        subscription?.Dispose();

        // The following prevents derived types that introduce a
        // finalizer from needing to re-implement IDisposable.
        GC.SuppressFinalize(this);
    }
}

Dalam contoh sebelumnya, namespace aplikasi adalah BlazorSample dengan komponen bersama di Shared folder. Jika menguji kode secara lokal, perbarui namespace.

Mengeraskan panggilan interop JavaScript

Bagian ini hanya berlaku untuk komponen Server Interaktif, tetapi komponen sisi klien juga dapat mengatur JS batas waktu interop jika kondisi menjaminnya.

Di aplikasi sisi server dengan interaktivitas server, interop JavaScript (JS) mungkin gagal karena kesalahan jaringan dan harus diperlakukan sebagai tidak dapat diandalkan. Blazor aplikasi menggunakan batas waktu satu menit untuk JS panggilan interop. Jika aplikasi dapat mentolerir batas waktu yang lebih agresif, atur batas waktu menggunakan salah satu pendekatan berikut.

Atur batas waktu global di Program.cs dengan CircuitOptions.JSInteropDefaultCallTimeout:

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents(options => 
        options.JSInteropDefaultCallTimeout = {TIMEOUT});

Placeholder {TIMEOUT} adalah TimeSpan (misalnya, TimeSpan.FromSeconds(80)).

Atur batas waktu per pemanggilan dalam kode komponen. Batas waktu yang ditentukan mengambil alih batas waktu global yang ditetapkan oleh JSInteropDefaultCallTimeout:

var result = await JS.InvokeAsync<string>("{ID}", {TIMEOUT}, [ "Arg1" ]);

Dalam contoh sebelumnya:

• Placeholder {TIMEOUT} adalah TimeSpan (misalnya, TimeSpan.FromSeconds(80)).
• Placeholder {ID} adalah pengidentifikasi untuk fungsi yang akan dipanggil. Misalnya, nilai someScope.someFunction memanggil fungsi window.someScope.someFunction.

Meskipun penyebab JS umum kegagalan interop adalah kegagalan jaringan dengan komponen sisi server, batas waktu per pemanggilan dapat diatur untuk JS panggilan interop untuk komponen sisi klien. Meskipun tidak ada Blazor-SignalR sirkuit ada untuk komponen sisi klien, JS panggilan interop mungkin gagal karena alasan lain yang berlaku.

Untuk informasi selengkapnya tentang kelelahan sumber daya, lihat panduan mitigasi ancaman untuk ASP.NET Core Blazor rendering sisi server interaktif.

Hindari referensi objek melingkar

Objek yang berisi referensi melingkar tidak dapat diserialisasikan pada klien untuk:

• Panggilan metode .NET.
• Metode JavaScript memanggil dari C# ketika jenis pengembalian memiliki referensi melingkar.

Perpustakaan JavaScript yang menghasilkan Antarmuka Pengguna (UI)

Terkadang Anda mungkin ingin menggunakan pustaka JavaScript (JS) yang menghasilkan elemen antarmuka pengguna yang terlihat dalam DOM browser. Pada pandangan pertama, ini mungkin tampak sulit karena sistem perbedaan Blazor bergantung pada kontrol terhadap pohon elemen DOM dan mengalami kesalahan jika beberapa kode eksternal mengubah pohon DOM dan membatalkan mekanismenya untuk menerapkan perbedaan. Ini bukan batasan khusus Blazor. Tantangan yang sama terjadi dengan kerangka kerja UI berbasis diff.

Untungnya, mudah untuk menyematkan UI yang dihasilkan secara eksternal dalam Razor antarmuka pengguna komponen dengan andal. Teknik yang direkomendasikan adalah memiliki kode komponen (.razor file) menghasilkan elemen kosong. Sejauh menyangkut sistem diffing Blazor, elemen selalu kosong, sehingga perender tidak masuk lebih dalam ke elemen dan membiarkan isinya seperti semula. Ini membuatnya aman untuk mengisi elemen dengan konten yang dikelola secara eksternal arbitrer.

Contoh berikut menunjukkan konsepnya. Dalam pernyataan if ketika firstRender adalah true, berinteraksi dengan unmanagedElement di luar Blazor menggunakan interop JS. Misalnya, panggil pustaka eksternal JS untuk mengisi elemen . Blazor membiarkan konten elemen itu saja sampai komponen ini dihapus. Ketika komponen dihapus, seluruh subtree DOM komponen juga dihapus.

<h1>Hello! This is a Razor component rendered at @DateTime.Now</h1>

<div @ref="unmanagedElement"></div>

@code {
    private ElementReference unmanagedElement;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            ...
        }
    }
}

Pertimbangkan contoh berikut yang merender peta interaktif menggunakan API Mapbox sumber terbuka.

Modul berikut JS dimasukkan ke dalam aplikasi atau disediakan dari Razor perpustakaan kelas.

Catatan

Untuk membuat peta Mapbox , dapatkan token akses dari Masuk Mapbox dan berikan di mana {ACCESS TOKEN} muncul dalam kode berikut.

wwwroot/mapComponent.js:

import 'https://api.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.js';

mapboxgl.accessToken = '{ACCESS TOKEN}';

export function addMapToElement(element) {
  return new mapboxgl.Map({
    container: element,
    style: 'mapbox://styles/mapbox/streets-v11',
    center: [-74.5, 40],
    zoom: 9
  });
}

export function setMapCenter(map, latitude, longitude) {
  map.setCenter([longitude, latitude]);
}

Untuk menghasilkan gaya yang benar, tambahkan tag lembar gaya berikut ke halaman HTML host.

Tambahkan elemen berikut <link> ke <head> markup elemen (lokasi <head> konten):

<link href="https://api.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.css" 
    rel="stylesheet" />

CallJs8.razor:

@page "/call-js-8"
@implements IAsyncDisposable
@inject IJSRuntime JS

<PageTitle>Call JS 8</PageTitle>

<HeadContent>
    <link href="https://api.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.css" 
        rel="stylesheet" />
</HeadContent>

<h1>Call JS Example 8</h1>

<div @ref="mapElement" style='width:400px;height:300px'></div>

<button @onclick="() => ShowAsync(51.454514, -2.587910)">Show Bristol, UK</button>
<button @onclick="() => ShowAsync(35.6762, 139.6503)">Show Tokyo, Japan</button>

@code
{
    private ElementReference mapElement;
    private IJSObjectReference? mapModule;
    private IJSObjectReference? mapInstance;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            mapModule = await JS.InvokeAsync<IJSObjectReference>(
                "import", "./mapComponent.js");
            mapInstance = await mapModule.InvokeAsync<IJSObjectReference>(
                "addMapToElement", mapElement);
        }
    }

    private async Task ShowAsync(double latitude, double longitude)
    {
        if (mapModule is not null && mapInstance is not null)
        {
            await mapModule.InvokeVoidAsync("setMapCenter", mapInstance, 
                latitude, longitude);
        }
    }

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

        if (mapModule is not null)
        {
            try
            {
                await mapModule.DisposeAsync();
            }
            catch (JSDisconnectedException)
            {
            }
        }
    }
}

Contoh sebelumnya menghasilkan UI peta interaktif. Pengguna:

• Dapat menyeret untuk menggulir atau memperbesar tampilan.
• Pilih tombol untuk melompat ke lokasi yang telah ditentukan sebelumnya.

Dalam contoh sebelumnya:

• <div> dengan @ref="mapElement" dibiarkan kosong sejauh yang menyangkut Blazor. mapbox-gl.js Skrip dapat mengisi elemen dengan aman dan memodifikasi kontennya. Gunakan teknik ini dengan pustaka apa pun JS yang merender UI. Anda dapat menyematkan komponen dari kerangka kerja SPA pihak JS ketiga di dalam Razor komponen, selama komponen tersebut tidak mencoba menjangkau dan memodifikasi bagian lain dari halaman. Tidak aman bagi kode eksternal untuk memodifikasi elemen yang JS tidak dianggap kosong.
• Saat menggunakan pendekatan ini, ingatlah aturan tentang bagaimana Blazor mempertahankan atau menghancurkan elemen DOM. Komponen dengan aman menangani peristiwa klik tombol dan memperbarui instans peta yang ada karena elemen DOM dipertahankan jika memungkinkan. Jika Anda merender daftar elemen peta dari dalam perulangan @foreach, Anda perlu menggunakan @key untuk memastikan mempertahankan instans komponen. Jika tidak, perubahan dalam data daftar dapat menyebabkan instans komponen mempertahankan status instans sebelumnya dengan cara yang tidak diinginkan. Untuk informasi selengkapnya, lihat cara menggunakan @key atribut direktif untuk mempertahankan hubungan antara elemen, komponen, dan objek model.
• Contoh merangkum JS logika dan dependensi dalam modul JavaScript dan memuat modul secara dinamis menggunakan import pengidentifikasi. Untuk informasi selengkapnya, lihat Isolasi JavaScript dalam modul JavaScript.

Dukungan array byte

Blazor mendukung JavaScript (JS) interop array byte yang dioptimalkan yang menghindari pengodean/pendekodean array byte ke Base64. Contoh berikut menggunakan JS interop untuk meneruskan array byte ke JavaScript.

Sediakan fungsi receiveByteArrayJS. Fungsi ini dipanggil dengan InvokeVoidAsync dan tidak mengembalikan nilai:

<script>
  window.receiveByteArray = (bytes) => {
    let utf8decoder = new TextDecoder();
    let str = utf8decoder.decode(bytes);
    return str;
  };
</script>

Catatan

Untuk panduan umum tentang JS lokasi dan rekomendasi kami untuk aplikasi produksi, lihat Lokasi JavaScript di aplikasi ASP.NET Core Blazor.

CallJs9.razor:

@page "/call-js-9"
@inject IJSRuntime JS

<h1>Call JS Example 9</h1>

<p>
    <button @onclick="SendByteArray">Send Bytes</button>
</p>

<p>
    @result
</p>

<p>
    Quote &copy;2005 <a href="https://www.uphe.com">Universal Pictures</a>:
    <a href="https://www.uphe.com/movies/serenity-2005">Serenity</a><br>
    <a href="https://www.imdb.com/name/nm0821612/">Jewel Staite on IMDB</a>
</p>

@code {
    private string? result;

    private async Task SendByteArray()
    {
        var bytes = new byte[] { 0x45, 0x76, 0x65, 0x72, 0x79, 0x74, 0x68, 0x69,
            0x6e, 0x67, 0x27, 0x73, 0x20, 0x73, 0x68, 0x69, 0x6e, 0x79, 0x2c,
            0x20, 0x43, 0x61, 0x70, 0x74, 0x69, 0x61, 0x6e, 0x2e, 0x20, 0x4e,
            0x6f, 0x74, 0x20, 0x74, 0x6f, 0x20, 0x66, 0x72, 0x65, 0x74, 0x2e };

        result = await JS.InvokeAsync<string>("receiveByteArray", bytes);
    }
}

Streaming dari .NET ke JavaScript

Blazor mendukung data streaming langsung dari .NET ke JavaScript (JS). Aliran dibuat menggunakan DotNetStreamReference.

DotNetStreamReference mewakili aliran .NET dan menggunakan parameter berikut:

• stream: Aliran dikirim ke JS.
• leaveOpen: Menentukan apakah aliran dibiarkan terbuka setelah transmisi. Apabila nilai tidak disediakan, leaveOpen akan menjadi false.

Di JS, gunakan buffer array atau aliran yang dapat dibaca untuk menerima data:

• ArrayBufferDengan menggunakan :

  async function streamToJavaScript(streamRef) {
    const data = await streamRef.arrayBuffer();
  }
  

• ReadableStreamMenggunakan :

  async function streamToJavaScript(streamRef) {
    const stream = await streamRef.stream();
  }
  

Dalam kode C#:

var streamRef = new DotNetStreamReference(stream: {STREAM}, leaveOpen: false);
await JS.InvokeVoidAsync("streamToJavaScript", streamRef);

Dalam contoh sebelumnya:

• Placeholder {STREAM} mewakili elemen Stream yang dikirim ke JS.
• JS adalah instance IJSRuntime yang disuntikkan.

Menghapus instans DotNetStreamReference biasanya tidak perlu. Ketika leaveOpen diatur ke nilai defaultnya false, Stream yang mendasar secara otomatis dihapus setelah transmisi ke JS.

Jika leaveOpen adalah true, maka membuang DotNetStreamReference tidak akan membuang Stream yang melandasinya. Kode aplikasi menentukan kapan harus membuang elemen dasar Stream. Saat memutuskan cara mengelola elemen dasar dari Stream, pertimbangkan hal berikut:

• Membuang Stream saat sedang ditransmisikan ke JS dianggap sebagai kesalahan aplikasi dan dapat menyebabkan pengecualian yang tidak terkelola terjadi.
• Stream transmisi dimulai segera setelah DotNetStreamReference diteruskan sebagai argumen ke JS panggilan interop, terlepas dari apakah aliran benar-benar digunakan dalam JS logika.

Mengingat karakteristik ini, sebaiknya buang unsur dasar Stream hanya setelah sepenuhnya dikonsumsi oleh JS (promise yang dikembalikan oleh arrayBuffer atau stream telah selesai). Ini mengikuti bahwa DotNetStreamReference seharusnya hanya diteruskan ke JS jika tanpa syarat akan dikonsumsi oleh logika JS.

Memanggil metode .NET dari fungsi JavaScript di ASP.NET Core Blazor mencakup operasi kebalikannya, yaitu aliran data dari JavaScript ke .NET.

Blazor mencakup cara mengunduh file di .

Menangkap pengecualian JavaScript

Untuk menangkap JS pengecualian, bungkus JS interop di dalam try-catch blok dan tangkap sebuah JSException.

Dalam contoh berikut, nonFunctionJS fungsi tidak ada. Ketika fungsi tidak ditemukan, JSException terperangkap dengan Message yang menunjukkan kesalahan berikut:

Could not find 'nonFunction' ('nonFunction' was undefined).

CallJs11.razor:

@page "/call-js-11"
@inject IJSRuntime JS

<PageTitle>Call JS 11</PageTitle>

<h1>Call JS Example 11</h1>

<p>
    <button @onclick="CatchUndefinedJSFunction">Catch Exception</button>
</p>

<p>
    @result
</p>

<p>
    @errorMessage
</p>

@code {
    private string? errorMessage;
    private string? result;

    private async Task CatchUndefinedJSFunction()
    {
        try
        {
            result = await JS.InvokeAsync<string>("nonFunction");
        }
        catch (JSException e)
        {
            errorMessage = $"Error Message: {e.Message}";
        }
    }
}

Membatalkan fungsi JavaScript yang berjalan lama

JS Gunakan AbortController dengan CancellationTokenSource dalam komponen untuk membatalkan fungsi JavaScript yang berjalan lama dari kode C#.

Kelas berikut JSHelpers berisi fungsi jangka panjang yang disimulasikan, longRunningFn, untuk dihitung terus menerus sampai AbortController.signal menunjukkan yang AbortController.abort telah dipanggil. Fungsinya sleep adalah untuk tujuan demonstrasi untuk mensimulasikan eksekusi lambat dari fungsi yang berjalan lama dan tidak akan ada dalam kode produksi. Ketika komponen memanggil stopFn, longRunningFn disinyalir untuk membatalkan melalui pemeriksaan kondisional perulangan while pada AbortSignal.aborted.

<script>
  class Helpers {
    static #controller = new AbortController();

    static async #sleep(ms) {
      return new Promise(resolve => setTimeout(resolve, ms));
    }

    static async longRunningFn() {
      var i = 0;
      while (!this.#controller.signal.aborted) {
        i++;
        console.log(`longRunningFn: ${i}`);
        await this.#sleep(1000);
      }
    }

    static stopFn() {
      this.#controller.abort();
      console.log('longRunningFn aborted!');
    }
  }

  window.Helpers = Helpers;
</script>

Catatan

Untuk panduan umum tentang JS lokasi dan rekomendasi kami untuk aplikasi produksi, lihat Lokasi JavaScript di aplikasi ASP.NET Core Blazor.

Komponen berikut:

• JS Memanggil fungsi longRunningFn saat tombol Start Task dipilih. Sebuah CancellationTokenSource digunakan untuk mengelola eksekusi fungsi yang berjalan lama. Saat CancellationToken.Register dibatalkan, JSJS menetapkan delegasi panggilan interop untuk mengeksekusi fungsi stopFnCancellationTokenSource.Token.
• Ketika tombol Cancel Task dipilih, CancellationTokenSource.Token dibatalkan dengan panggilan ke Cancel.
• CancellationTokenSource dibuang dengan metode Dispose.

CallJs12.razor:

@page "/call-js-12"
@inject IJSRuntime JS

<h1>Cancel long-running JS interop</h1>

<p>
    <button @onclick="StartTask">Start Task</button>
    <button @onclick="CancelTask">Cancel Task</button>
</p>

@code {
    private CancellationTokenSource? cts;

    private async Task StartTask()
    {
        cts = new CancellationTokenSource();
        cts.Token.Register(() => JS.InvokeVoidAsync("Helpers.stopFn"));

        await JS.InvokeVoidAsync("Helpers.longRunningFn");
    }

    private void CancelTask()
    {
        cts?.Cancel();
    }

    public void Dispose()
    {
        cts?.Cancel();
        cts?.Dispose();
    }
}

Konsol alat pengembang dari browser menunjukkan eksekusi fungsi berdurasi lama setelah tombol JS dipilih dan saat fungsi dibatalkan setelah tombol Start Task dipilih.

longRunningFn: 1
longRunningFn: 2
longRunningFn: 3
longRunningFn aborted!

Interop JavaScript [JSImport]/[JSExport]

Bagian ini berlaku untuk komponen sisi klien.

Sebagai alternatif untuk berinteraksi dengan JavaScript (JS) di komponen sisi klien menggunakan mekanisme interop yang didasarkan pada antarmuka Blazor, API interop JSIJSRuntimeJS[JSImport] tersedia untuk aplikasi yang menargetkan .NET 7 atau yang lebih baru.

Untuk informasi selengkapnya, lihat JavaScript JSImport/JSExport interop dengan ASP.NET Core Blazor.

Interop JavaScript yang tidak terenkripsi

Bagian ini berlaku untuk komponen sisi klien.

Interop yang tidak terencana menggunakan IJSUnmarshalledRuntime antarmuka usang dan harus diganti dengan interop JavaScript[JSImport]/[JSExport].

Untuk informasi selengkapnya, lihat JavaScript JSImport/JSExport interop dengan ASP.NET Core Blazor.

Pembuangan referensi objek interop JavaScript

Contoh di seluruh artikel interop JavaScript (JS) menunjukkan pola umum dalam pengelolaan objek:

• Saat memanggil JS dari .NET, seperti yang dijelaskan dalam artikel ini, hapus semua yang telah dibuatIJSObjectReference/IJSInProcessObjectReference/JSObjectReference, baik dari .NET maupun dari JS untuk menghindari kebocoran memori JS.

• Saat memanggil .NET dari JS, seperti yang dijelaskan dalam Memanggil metode .NET dari fungsi JavaScript di ASP.NET Core Blazor, buang sumber daya yang dibuat baik dari .NET maupun dari DotNetObjectReference untuk menghindari kebocoran memori .NET.

JS referensi objek interop diimplementasikan sebagai peta yang dikunci oleh pengidentifikasi di sisi JS panggilan interop yang membuat referensi. Ketika pembuangan objek dimulai dari pihak .NET atau JS, Blazor menghapus entri dari peta, dan objek dapat dikumpulkan sebagai sampah selama tidak ada referensi kuat lain terhadap objek tersebut.

Minimal, selalu buang objek yang dibuat di sisi .NET untuk menghindari kebocoran memori terkelola .NET.

Tugas pembersihan DOM selama penghapusan komponen

Untuk informasi selengkapnya, lihat ASP.NET Blazor interoperabilitas Core JavaScript (JS interop).

Panggilan interop JavaScript tanpa sirkuit

Untuk informasi selengkapnya, lihat ASP.NET Blazor interoperabilitas Core JavaScript (JS interop).

Sumber Daya Tambahan:

• Memanggil metode .NET dari fungsi JavaScript di Blazor ASP.NET Core
• InteropComponent.razor contoh (dotnet/AspNetCore cabang repositori main GitHub): Cabang main mewakili pengembangan unit produk saat ini untuk rilis ASP.NET Core berikutnya. Untuk memilih cabang untuk rilis yang berbeda (misalnya, release/{VERSION}, di mana {VERSION} adalah versi rilis), gunakan daftar dropdown Beralih cabang atau tag untuk memilih cabang. Untuk cabang yang sudah tidak ada lagi, gunakan tab Tag untuk menemukan API (misalnya, v7.0.0).
• Blazor repositori contoh GitHub (dotnet/blazor-samples) (cara mengunduh)
• Menangani kesalahan dalam aplikasi ASP.NET Core (bagian interop JavaScript)
• Mitigasi ancaman: Fungsi JavaScript yang dipanggil dari .NET