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.

JS Memanggil fungsi

IJSRuntime terdaftar oleh Blazor kerangka kerja. 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 JSargumen Object[] on-serializable ke JS fungsi.
• Token pembatalan (CancellationToken) menyebarkan pemberitahuan bahwa operasi harus dibatalkan.
• TimeSpan mewakili batas waktu untuk JS operasi.
• Jenis TValue pengembalian juga harus ON yang dapat diserialisasikan JS. TValue harus cocok dengan jenis .NET yang paling baik memetakan ke JSjenis ON yang dikembalikan.
• JS Promise dikembalikan untuk InvokeAsync metode. InvokeAsync membongkar Promise dan mengembalikan nilai yang ditunggu oleh Promise.

Untuk Blazor aplikasi dengan pra-penyajian diaktifkan, yang merupakan default untuk aplikasi sisi server, panggilan ke JS tidak dimungkinkan selama pra-penyajian. Untuk informasi selengkapnya, lihat bagian Pra-penyajian.

Contoh berikut didasarkan pada TextDecoder, JSdekoder berbasis. Contoh menunjukkan cara JS memanggil fungsi dari metode C# yang membongkar persyaratan dari kode pengembang ke API yang ada JS . 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 CoreBlazor.

Komponen berikut:

• convertArrayJS 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 (dokumentasi MDN). 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@onclick atribut direktif.

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.

displayTickerAlert1JS Menyediakan fungsi. 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 CoreBlazor.

Contoh komponen (.razor) (InvokeVoidAsync)

TickerChangedhandleTickerChanged1 memanggil metode 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);
    }

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

TickerChangedhandleTickerChanged1 memanggil metode 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).

displayTickerAlert2JS Menyediakan fungsi. 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 CoreBlazor.

Contoh komponen (.razor) (InvokeAsync)

TickerChangedhandleTickerChanged2 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)
    {
        return await js.InvokeAsync<string>("displayTickerAlert2", symbol, price);
    }

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

TickerChangedhandleTickerChanged2 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 merender Razor komponen sebelumnya. Pra-penyajian tercakup dalam komponen Prerender ASP.NET CoreRazor.

Catatan

Navigasi internal untuk perutean interaktif di Blazor Web Apps tidak melibatkan permintaan konten halaman baru dari server. Oleh karena itu, pra-penyajian 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 Prarender komponen ASP.NET CoreRazor.

Saat aplikasi melakukan pra-penyajian, tindakan tertentu, seperti memanggil ke JavaScript (JS), tidak dimungkinkan.

Untuk contoh berikut, fungsi dipanggil setElementText1 dengan JSRuntimeExtensions.InvokeVoidAsync dan tidak mengembalikan nilai.

Catatan

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

<script>
  window.setElementText1 = (element, text) => element.innerText = text;
</script>

Peringatan

Contoh sebelumnya memodifikasi DOM secara langsung hanya untuk tujuan demonstrasi. Memodifikasi DOM secara langsung dengan JS tidak disarankan dalam sebagian besar skenario karena JS dapat mengganggu Blazorpelacakan perubahan. Untuk informasi selengkapnya, lihat ASP.NET Blazor interoperabilitas Core JavaScript (JS interop).

Peristiwa OnAfterRender{Async} siklus hidup tidak dipanggil selama proses pra-penyajian di server. Ambil alih OnAfterRender{Async} metode untuk menunda JS panggilan interop sampai setelah komponen dirender dan interaktif pada klien setelah pra-penyajian.

PrerenderedInterop1.razor:

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

<PageTitle>Prerendered Interop 1</PageTitle>

<h1>Prerendered Interop Example 1</h1>

<div @ref="divElement">Text during render</div>

@code {
    private ElementReference divElement;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            await JS.InvokeVoidAsync(
                "setElementText1", divElement, "Text after render");
        }
    }
}

Catatan

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

Contoh:

export setElementText1 = (element, text) => element.innerText = text;

Komponen berikut menunjukkan cara menggunakan JS interop sebagai bagian dari logika inisialisasi komponen dengan cara yang kompatibel dengan pra-penyajian. Komponen menunjukkan bahwa dimungkinkan untuk memicu pembaruan penyajian dari dalam OnAfterRenderAsync. Pengembang harus berhati-hati untuk menghindari pembuatan perulangan tak terbatas dalam skenario ini.

Untuk contoh berikut, fungsi dipanggil setElementText2 dengan IJSRuntime.InvokeAsync dan mengembalikan nilai.

Catatan

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

<script>
  window.setElementText2 = (element, text) => {
    element.innerText = text;
    return text;
  };
</script>

Peringatan

Contoh sebelumnya memodifikasi DOM secara langsung hanya untuk tujuan demonstrasi. Memodifikasi DOM secara langsung dengan JS tidak disarankan dalam sebagian besar skenario karena JS dapat mengganggu Blazorpelacakan perubahan. Untuk informasi selengkapnya, lihat ASP.NET Blazor interoperabilitas Core JavaScript (JS interop).

Di mana JSRuntime.InvokeAsync dipanggil, ElementReference hanya digunakan dalam OnAfterRenderAsync dan bukan dalam metode siklus hidup sebelumnya karena tidak ada elemen HTML DOM sampai setelah komponen dirender.

StateHasChangeddipanggil untuk merender komponen dengan status baru yang diperoleh dari JS panggilan interop (untuk informasi selengkapnya, lihat ASP.NET penyajian komponen CoreRazor). Kode tidak membuat perulangan tak terbatas karena StateHasChanged hanya dipanggil ketika data adalah null.

PrerenderedInterop2.razor:

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

<PageTitle>Prerendered Interop 2</PageTitle>

<h1>Prerendered Interop Example 2</h1>

<p>
    Get value via JS interop call:
    <strong id="val-get-by-interop">@(infoFromJs ?? "No value yet")</strong>
</p>

<p>
    Set value via JS interop call: 
    <strong id="val-set-by-interop" @ref="divElement"></strong>
</p>



@code {
    private string? infoFromJs;
    private ElementReference divElement;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender && infoFromJs == null)
        {
            infoFromJs = await JS.InvokeAsync<string>(
                "setElementText2", divElement, "Hello from interop call!");

            StateHasChanged();
        }
    }
}

Catatan

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

Contoh:

export setElementText2 = (element, text) => {
  element.innerText = text;
  return text;
};

Interop sinkron JS dalam komponen sisi klien

Bagian ini hanya berlaku untuk komponen sisi klien.

Panggilan interop JS tidak sinkron secara default, terlepas dari apakah kode yang dipanggil sinkron atau asinkron. Panggilan tidak sinkron secara default 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 tahu dengan pasti bahwa komponen Anda hanya berjalan di WebAssembly, Anda dapat memilih untuk melakukan panggilan interop 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 melakukan panggilan sinkron dari .NET ke JavaScript dalam komponen sisi klien, transmisikan IJSRuntime untuk IJSInProcessRuntime melakukan JS panggilan interop:

@inject IJSRuntime JS

...

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

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

@inject IJSRuntime JS
@implements IAsyncDisposable

...

@code {
    ...
    private IJSInProcessObjectReference? module;

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

    ...

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

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 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 Blazor yang sama seperti halnya untuk jenis aplikasi web lainnya, dan Anda bebas menyesuaikan bagaimana 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.
• Konsumen pustaka dan komponen tidak perlu mengimpor JS 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 bersyariah untuk menentukan apakah modul harus dimuat.

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

Misalnya, modul berikut JS mengekspor JS fungsi untuk menampilkan perintah 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 sebelumnya JS ke pustaka aplikasi atau kelas sebagai aset web statis di wwwroot folder lalu impor modul ke dalam kode .NET dengan memanggil InvokeAsyncIJSRuntime instans.

IJSRuntime mengimpor modul sebagai IJSObjectReference, yang mewakili referensi ke JS objek dari kode .NET. IJSObjectReference Gunakan untuk memanggil fungsi yang JS 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 some 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)
        {
            await module.DisposeAsync();
        }
    }
}

Dalam contoh sebelumnya:

• Menurut konvensi, import pengidentifikasi adalah pengidentifikasi khusus yang digunakan khusus 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.
  • Tempat penampung {SCRIPT PATH AND FILE NAME (.js)} adalah jalur dan nama file di bagian wwwroot.
• Membuang untuk pengumpulan IJSObjectReference sampah di IAsyncDisposable.DisposeAsync.

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 Interop sinkron JS di komponen sisi klien.

Catatan

Saat file eksternal JS disediakan oleh Razor pustaka kelas, 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. Default ID paket 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>.
• Tempat penampung {SCRIPT PATH AND FILE NAME (.js)} adalah jalur dan nama file di bagian wwwroot. Dalam contoh berikut, file eksternal JS (script.js) ditempatkan di folder pustaka wwwroot kelas.
• module adalah nullable IJSObjectReference 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 Selain — .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 mencoba menerapkan perbedaan pada elemen, diff tidak akan cocok dengan DOM. Mengubah konten daftar melalui JS interop dengan MyList referensi elemen tidak didukung.

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

Diteruskan ElementReference 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 clickElement ini JS membuat click peristiwa pada elemen HTML yang diteruskan (element):

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

Untuk memanggil JS fungsi yang tidak mengembalikan nilai, gunakan JSRuntimeExtensions.InvokeVoidAsync. Kode berikut memicu peristiwa sisi click klien dengan memanggil fungsi sebelumnya JS dengan 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 hanya diisi setelah komponen dirender. Jika tidak diisi ElementReference diteruskan ke JS kode, JS kode menerima nilai null. Untuk memanipulasi referensi elemen setelah komponen selesai dirender, gunakan OnAfterRenderAsync metode siklus hidup komponen atau OnAfterRender .

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

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

Tempat {JAVASCRIPT FUNCTION} penampung adalah JS pengidentifikasi fungsi.

GenericMethod dipanggil langsung pada objek dengan jenis. 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 parameter komponen.

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

• Perbolehkan komponen anak mendaftarkan panggilan balik.
• Panggil panggilan balik terdaftar selama OnAfterRender peristiwa 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 CoreBlazor.

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)
        {
            try
            {
                subscription.OnNext(title);
            }
            catch (Exception)
            {
                throw;
            }
        }
    }

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

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

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. Secara default, 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});

Tempat {TIMEOUT} penampung 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}, new[] { "Arg1" });

Dalam contoh sebelumnya:

• Tempat {TIMEOUT} penampung adalah TimeSpan (misalnya, TimeSpan.FromSeconds(80)).
• Tempat {ID} penampung adalah pengidentifikasi untuk dipanggil fungsi. 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 SignalR sirkuit 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 penyajian sisi server interaktif ASP.NET CoreBlazor.

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.

Pustaka JavaScript yang merender 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 Blazorsistem yang berbeda bergantung pada memiliki kontrol atas pohon elemen DOM dan mengalami kesalahan jika beberapa kode eksternal mengubah pohon DOM dan membatalkan mekanismenya untuk menerapkan perbedaan. Ini bukan Blazorbatasan -spesifik. 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 Blazormenyangkut sistem diffing, elemen selalu kosong, sehingga perender tidak berulang ke dalam elemen dan sebaliknya meninggalkan isinya saja. Ini membuatnya aman untuk mengisi elemen dengan konten yang dikelola secara eksternal arbitrer.

Contoh berikut menunjukkan konsepnya. if Dalam pernyataan ketika firstRender adalah true, berinteraksi dengan unmanagedElement di luar menggunakan BlazorJS interop. 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 ditempatkan ke dalam aplikasi atau disediakan dari Razor pustaka 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).AsTask();
        }
    }

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

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

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:

• dengan <div>@ref="mapElement" dibiarkan kosong sejauh Blazor yang bersangkutan. 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. Kode eksternal JS tidak aman untuk memodifikasi elemen yang Blazor 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 secara default. Jika Anda merender daftar elemen peta dari dalam perulangan @foreach , Anda ingin menggunakan @key untuk memastikan pelestarian 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 ES6 dan memuat modul secara dinamis menggunakan import pengidentifikasi. Untuk informasi selengkapnya, lihat Isolasi JavaScript dalam modul JavaScript.

Dukungan array byte

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

receiveByteArrayJS Menyediakan fungsi. 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 CoreBlazor.

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 streaming data langsung dari .NET ke JavaScript. Aliran dibuat menggunakan DotNetStreamReference.

DotNetStreamReference mewakili aliran .NET dan menggunakan parameter berikut:

• stream: Aliran yang dikirim ke JavaScript.
• leaveOpen: Menentukan apakah aliran dibiarkan terbuka setelah transmisi. Jika nilai tidak disediakan, leaveOpen default ke false.

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

• ArrayBufferMenggunakan :

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

• ReadableStreamMenggunakan :

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

Dalam kode C#:

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

Dalam contoh sebelumnya:

• Tempat {STREAM} penampung mewakili yang Stream dikirim ke JavaScript.
• JS adalah instans yang disuntikkan IJSRuntime .

Memanggil metode .NET dari fungsi JavaScript di ASP.NET Core Blazor mencakup operasi terbalik, streaming dari JavaScript ke .NET.

ASP.NET Unduhan file Core Blazor mencakup cara mengunduh file di Blazor.

Menangkap pengecualian JavaScript

Untuk menangkap JS pengecualian, bungkus JS interop di-trycatchblok dan tangkap .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

JSGunakan 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 CoreBlazor.

Komponen berikut:

• JS Memanggil fungsi longRunningFn saat tombol Start Task dipilih. digunakan CancellationTokenSource untuk mengelola eksekusi fungsi yang berjalan lama. CancellationToken.RegisterJS mengatur delegasi panggilan interop untuk menjalankan JS fungsi stopFn saat CancellationTokenSource.Token dibatalkan.
• Ketika tombol Cancel Task dipilih, CancellationTokenSource.Token dibatalkan dengan panggilan ke Cancel.
• dibuang CancellationTokenSource dalam Dispose metode .

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 browser menunjukkan eksekusi fungsi jangka JS panjang setelah tombol Start Task dipilih dan ketika fungsi dibatalkan setelah tombol Cancel 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 JSBlazormekanisme interop berdasarkan IJSRuntime antarmuka,/JS[JSImport][JSExport] API interop tersedia untuk aplikasi yang menargetkan .NET 7 atau yang lebih baru.

Untuk informasi selengkapnya, lihat Interop Impor/JSEkspor JavaScript JSdengan 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 Interop Impor/JSEkspor JavaScript JSdengan ASP.NET Core Blazor.

Pembuangan referensi objek interop JavaScript

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

• Saat memanggil JS dari .NET, seperti yang dijelaskan dalam artikel ini, buang apa pun yang dibuat/IJSInProcessObjectReference/JSObjectReferenceIJSObjectReferencebaik dari .NET atau dari JS untuk menghindari kebocoran JS memori.

• Saat memanggil .NET dari JS, seperti yang dijelaskan dalam Metode panggilan .NET dari fungsi JavaScript di ASP.NET CoreBlazor , buang yang dibuat DotNetObjectReference baik dari .NET atau dari JS 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 .NET atau JS sisi, Blazor menghapus entri dari peta, dan objek dapat menjadi sampah yang dikumpulkan selama tidak ada referensi kuat lainnya ke objek yang ada.

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

Tugas pembersihan DOM selama pembuangan 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/5.0), gunakan daftar dropdown Beralih cabang atau tag untuk memilih cabang.
• Blazorsampel repositori GitHub () (dotnet/blazor-samplescara mengunduh)
• Menangani kesalahan di aplikasi ASP.NET Core Blazor (bagian interop JavaScript)
• Mitigasi ancaman: Fungsi JavaScript yang dipanggil dari .NET