在 ASP.NET Core Blazor 中從 .NET 方法呼叫 JavaScript 函式

本文說明如何從 .NET 叫用 JavaScript (JS) 函式。

如需有關如何從 JS 呼叫 .NET 方法的資訊，請參閱在 ASP.NET Core Blazor 中從 JavaScript 函式呼叫 .NET 方法。

叫用 JS 函式

IJSRuntime 會由 Blazor 架構進行註冊。 若要從 .NET 呼叫 JS，請插入 IJSRuntime 抽象概念，並呼叫下列其中一種方法：

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

針對上述會叫用 JS 函式的 .NET 方法：

• 函式識別碼 (String) 是相對於全域範圍 (window)。 若要呼叫 window.someScope.someFunction，識別碼為 someScope.someFunction。 在呼叫函式之前，不需要註冊函式。
• 將 Object[] 中任意數目的 JSON 可序列化引數傳遞至 JS 函數。
• 取消權杖 (CancellationToken) 會傳播應取消作業的通知。
• TimeSpan 代表 JS 作業的時間限制。
• TValue 傳回型別也必須有 JSON 可序列化特性。 TValue 應符合與所傳回 JSON 型別對應程度最佳的 .NET 型別。
• InvokeAsync 方法會傳回 JS Promise。 InvokeAsync 會將 Promise 解除包裝，並傳回 Promise 所等候的值。

已啟用預先轉譯 (此為伺服器端應用程式的預設值) 的 Blazor 應用程式無法在預先轉譯期間呼叫 JS。 如需詳細資訊，請參閱預先轉譯一節。

下列範例是以 JS 型解碼器 TextDecoder 作為基礎。 此範例示範如何從會將需求從開發人員程式碼卸載至現有 JS API 的 C# 方法叫用 JS 函式。 JS 函式會接受來自 C# 方法的位元組陣列、將陣列解碼，再將文字傳回元件來顯示。

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

注意

如需 JS 位置的一般指導和我們對於生產應用程式的建議，請參閱 ASP.NET Core Blazor 應用程式中的 JavaScript 位置

下列 元件：

• 會在選取按鈕 (Convert Array) 時，使用 InvokeAsync 叫用 convertArrayJS 函式。
• 在呼叫 JS 函式後，所傳遞的陣列會轉換成字串。 字串會傳回元件來顯示 (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

本節適用於伺服器端元件。

某些瀏覽器 JavaScript (JS) API 只能在使用者手勢的內容中執行，例如使用 Fullscreen API (MDN 文件)。 在伺服器端元件中無法透過 JS Interop 機制呼叫這些 API，因為 UI 事件處理是以非同步方式進行，一般來說，這時已不再處於使用者手勢的內容中。 應用程式必須完全在 JavaScript 中處理 UI 事件，因此請使用 onclick 而非 Blazor 的 @onclick 指示詞屬性。

叫用 JavaScript 函式而不讀取傳回的值 (InvokeVoidAsync)

InvokeVoidAsync 的使用時機：

• 不需要 .NET 就能讀取 JavaScript (JS) 呼叫的結果。
• JS 函式傳回 void(0)/void 0 或未定義。

請提供 displayTickerAlert1JS 函式。 系統會使用 InvokeVoidAsync 來呼叫此函式，而且此函式不會傳回值：

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

注意

如需 JS 位置的一般指導和我們對於生產應用程式的建議，請參閱 ASP.NET Core Blazor 應用程式中的 JavaScript 位置

元件 (.razor) 範例 (InvokeVoidAsync)

TickerChanged 會在下列元件中呼叫 handleTickerChanged1 方法。

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);
    }
}

類別 (.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 會在下列元件中呼叫 handleTickerChanged1 方法。

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();
}

叫用 JavaScript 函式並讀取傳回的值 (InvokeAsync)

當 .NET 應讀取 JavaScript (JS) 呼叫的結果時，請使用 InvokeAsync。

請提供 displayTickerAlert2JS 函式。 下列範例會傳回字串以供呼叫端顯示：

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

注意

如需 JS 位置的一般指導和我們對於生產應用程式的建議，請參閱 ASP.NET Core Blazor 應用程式中的 JavaScript 位置

元件 (.razor) 範例 (InvokeAsync)

TickerChanged 會呼叫 handleTickerChanged2 方法，並在下列元件中顯示傳回的字串。

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}";
    }
}

類別 (.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 方法，並在下列元件中顯示傳回的字串。

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();
}

動態內容產生案例

若要使用 BuildRenderTree 產生動態內容，請使用 [Inject] 屬性：

[Inject]
IJSRuntime JS { get; set; }

預先轉譯

本節適用於會預先轉譯 Razor 元件的伺服器端應用程式。 預先轉譯 ASP.NET Core Razor 元件中會有預先轉譯的說明。

注意

在 Blazor Web App 中互動式路由的內部瀏覽並不涉及向伺服器要求新頁面內容。 因此，內部頁面要求不會發生預先轉譯。 如果應用程式採用互動式路由，請針對示範預先轉譯行為的元件範例執行完整頁面重載。 如需詳細資訊，請參閱預先轉譯 ASP.NET Core Razor 元件。

在預先轉譯期間，無法電話撥接 JavaScript（JS）。 下列範例示範如何透過與預先轉譯相容的方式，將 JS Interop 作為元件初始化邏輯的一部分。

下列 scrollElementIntoView 函式：

• 使用 scrollIntoView捲動至傳遞的元素。
• 從 getBoundingClientRect 方法傳回元素的 top 屬性值。

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

當 IJSRuntime.InvokeAsync 在元件程式碼呼叫 JS 函式時， ElementReference 僅在 OnAfterRenderAsync 使用，而不在任何先前的生命週期方法中使用，因為要等到元件轉譯後才會有 HTML DOM 元素。

呼叫 StateHasChanged (參考來源) 以使用從 JS Interop 呼叫所取得的新狀態，將元件的重新轉譯加入佇列 (如需詳細資訊，請參閱 ASP.NET Core Razor 元件轉譯)。 此程式碼不會無限迴圈，因為只有在 scrollPosition 是 null時才會呼叫 StateHasChanged 。

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();
        }
    }
}

上述範例會使用全域函式敗壞用戶端。 如需更適合生產應用程式的方法，請參閱 JavaScript 模組中的 JavaScript 隔離。

用戶端元件中的同步 JS Interop

本節僅適用於用戶端元件。

不論所呼叫的程式碼是同步還是非同步的，JS Interop 通話都是非同步的。 通話會預設為以非同步方式進行，以確保元件在伺服器端和用戶端轉譯模式可以相容。 在伺服器上，所有 JS Interop 呼叫都必須以非同步方式進行，因為這些呼叫會透過網路連線來傳送。

如果您確定元件只會在 WebAssembly 上執行，則可以選擇進行同步的 JS Interop 呼叫。 進行同步呼叫的額外負荷會略低於進行非同步呼叫，而且可減少轉譯週期，因為在等候結果時不會有中繼狀態。

若要在用戶端元件中進行從 .NET 到 JavaScript 的同步呼叫，請將 IJSRuntime 轉換成 IJSInProcessRuntime 以進行 JS Interop 呼叫：

@inject IJSRuntime JS

...

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

在 ASP.NET Core 5.0 或更新版本的用戶端元件中使用 IJSObjectReference 時，您可以改為以同步方式使用 IJSInProcessObjectReference。 IJSInProcessObjectReference 會實作 IAsyncDisposable/IDisposable，並應針對記憶體回收進行處置以防止記憶體流失，如下列範例所示：

@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)
        {
            try
            {
                await module.DisposeAsync();
            }
            catch (JSDisconnectedException)
            {
            }
        }
    }
}

JavaScript 位置

請使用 JavaScript 位置上文章中所述的任何方法載入 JavaScript (JS) 程式碼：

• 在 <head> 標記 中載入指令碼 (通常不建議使用)
• 在 <body> 標記中載入指令碼
• 從外部 JavaScript 檔案載入指令碼 (.js) 與元件共置
• 從外部 JavaScript 檔案載入指令碼 (.js)
• 在 Blazor 啟動前或啟動後插入指令碼

如需有關在 JS 模組中隔離指令碼的資訊，請參閱 JavaScript 模組中的 JavaScript 隔離一節。

警告

只有在元件保證採用靜態伺服器端轉譯 (靜態 SSR) 時，才會將 <script> 標籤放在元件檔案 (.razor) 中，因為 <script> 標籤無法動態更新。

JavaScript 模組中的 JavaScript 隔離

Blazor 會啟用標準 JavaScript 模組 (ECMAScript 規格) 中的 JavaScript (JS) 隔離。 Blazor 中的 JavaScript 模組載入運作方式與其他型別的 Web 應用程式相同，因此您可以任意地自訂在應用程式中定義模組的方式。 如需有關如何使用 JavaScript 模組的指南，請參閱 MDN Web 文件：JavaScript 模組。

JS 隔離提供下列優點：

• 已匯入的 JS 不再會產生全域命名空間問題。
• 不需要程式庫和元件的取用者即可匯入相關 JS。

ASP.NET Core 和 Blazor 支援使用 import() 運算子的動態匯入：

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

在上述範例中，{CONDITION} 預留位置代表用來判斷是否應該載入模組的條件式檢查。

關於瀏覽器相容性，請參閱我是否可以使用：JavaScript 模組：動態匯入。

在伺服器端案例中，JS中斷線路連線之後BlazorSignalR，無法發出 Interop 呼叫。 在元件處置期間沒有線路，或在線路不存在的任何其他時間，下列方法呼叫會失敗，並以 JSDisconnectedException 記錄線路中斷連線的訊息：

• JS Interop 方法會呼叫
  • IJSRuntime.InvokeAsync
  • JSRuntimeExtensions.InvokeAsync
  • JSRuntimeExtensions.InvokeVoidAsync)
• Dispose/DisposeAsync 會在任何 IJSObjectReference 上呼叫。

為了避免在伺服器端Blazor記錄JSDisconnectedException或記錄自定義資訊，請在語句中攔截例外狀況try-catch。

針對下列元件處置範例：

• 伺服器端元件會實作 IAsyncDisposable。
• moduleIJSObjectReference是模組的 JS 。
• JSDisconnectedException 已攔截且未記錄。
• 您可以選擇性地在 catch 陳述式中記錄自訂資訊，不論您偏好的記錄層級為何。 下列範例不會記錄自定義資訊。 程式代碼假設開發人員不在意元件處置期間線路何時或何處中斷連線。

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

如果您在伺服器端Blazor應用程式中遺失線路之後，必須清除自己的JS物件，或在用戶端上執行其他JS程式代碼，請在 MutationObserver JS 用戶端上使用 模式。 模式 MutationObserver 可讓您在從 DOM 移除項目時執行 JS 程式碼。

如需詳細資訊，請參閱下列文章：

• ASP.NET Core Blazor JavaScript 互操作性 （JS interop）：包含模式的程式 MutationObserver 代碼範例。
• 處理 ASP.NET Core Blazor 應用程式中的錯誤：JavaScript Interop 一節討論 JS Interop 案例中的錯誤處理。
• ASP.NET Core Razor 元件生命週期 ：使用 IDisposable 和 IAsyncDisposable 的元件處置一節說明如何在 Razor 元件中實作處置模式。

下列 JS 模組會匯出顯示 JS 瀏覽器視窗提示的 函式。 請將下列 JS 程式碼放在外部 JS 檔案中。

wwwroot/scripts.js：

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

將上述 JS 模組新增至應用程式或類別庫作為 wwwroot 資料夾中的靜態 Web 資產，然後在 IJSRuntime 執行個體上呼叫 InvokeAsync 以將該模組匯入 .NET 程式碼。

IJSRuntime 會將模組匯入為代表 .NET 程式碼中 JS 物件參考的 IJSObjectReference。 使用 IJSObjectReference 即可從模組叫用匯出的 JS 函式。

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)
            {
            }
        }
    }
}

在前述範例中:

• 依照慣例，import 識別碼是特別用於匯入 JS 模組的特殊識別碼。
• 使用模組的穩定靜態 Web 資產路徑指定模組的外部 JS 檔案：./{SCRIPT PATH AND FILE NAME (.js)}，其中：
  • 需要目前目錄 (./) 的路徑區段，才能建立 JS 檔案的正確靜態資產路徑。
  • {SCRIPT PATH AND FILE NAME (.js)} 預留位置是 wwwroot 下的路徑和檔案名稱。
• 在 IAsyncDisposable.DisposeAsync 中處置 IJSObjectReference以便進行記憶體回收。

要有網路要求才能動態匯入模組，因此您只能藉由呼叫 InvokeAsync 以非同步方式實現此作業。

IJSInProcessObjectReference 代表可於用戶端元件中以同步方式叫用函式之 JS 物件的參考。 如需詳細資訊，請參閱用戶端元件中的同步 JS Interop 一節。

注意

由 Razor 類別庫提供外部 JS 檔案時，請使用模組的穩定靜態 Web 資產路徑來指定模組的 JS 檔案：./_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}：

• 需要目前目錄 (./) 的路徑區段，才能建立 JS 檔案的正確靜態資產路徑。
• {PACKAGE ID} 預留位置是程式庫的封裝識別碼。 如果未在專案檔中指定 <PackageId>，則封裝識別碼預設為專案的組件名稱。 在下列範例中，程式庫的組件名稱是 ComponentLibrary，而且程式庫的專案檔未指定 <PackageId>。
• {SCRIPT PATH AND FILE NAME (.js)} 預留位置是 wwwroot 下的路徑和檔案名稱。 在下列範例中，外部 JS 檔案 (script.js) 會放在類別庫的 wwwroot 資料夾中。
• module 是元件類別 (private IJSObjectReference? module;) 的私人可為 Null IJSObjectReference。

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

如需詳細資訊，請參閱從 Razor 類別庫 (RCL) 取用 ASP.NET Core Razor。

整個 Blazor 文件的範例會針對模組檔案使用 .js 副檔名，而不是使用較新的 .mjs 副檔名 (RFC 9239)。 我們的文件會繼續使用 .js 副檔名，原因和 Mozilla Foundation 的文件會繼續使用 .js 副檔名的原因相同。 如需詳細資訊，請參閱 Aside - .mjs 與 .js （MDN 文件）。

擷取元素的參考

某些 JavaScript (JS) Interop 案例需要 HTML 元素的參考。 例如，UI 程式庫可能需要元素參考以進行初始化，或者您可能需要在元素上呼叫類似命令的 API，例如 click 或 play。

請使用下列方法擷取元件中 HTML 元素的參考：

• 將 @ref 屬性新增至 HTML 元素。
• 定義其名稱符合 @ref 屬性值的 ElementReference 型別欄位。

下列範例顯示如何擷取 username <input> 元素的參考：

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

@code {
    private ElementReference username;
}

警告

請只使用元素參考來變動不會與 Blazor 互動的空白元素內容。 在第三方 API 提供內容給該元素時，此案例很有用。 因為 Blazor 不會與該元素互動，因此該元素的 Blazor 表示法與 DOM 之間不可能發生衝突。

在下列範例中，透過 JS Interop 使用 MyList 來變動未排序清單 (ul) 的內容會很「危險」，因為 Blazor 會與 DOM 互動，從 Todos 物件填入這個元素的清單項目 (<li>)：

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

僅使用 MyList 元素參考來讀取 DOM 內容或觸發事件是受到支援的做法。

如果 JS Interop 針對元素 MyList 變動內容，而且 Blazor 嘗試將差異套用至該元素，則差異不會與 DOM 相符。 不支援使用 MyList 元素參考透過 JS Interop 修改清單的內容。

如需詳細資訊，請參閱 ASP.NET Core Blazor JavaScript 互通性 (JS Interop)。

ElementReference 會透過 JS Interop 傳遞至 JS 程式碼。 JS 程式碼會收到其可與一般 DOM API 搭配使用的 HTMLElement 執行個體。 例如，下列程式碼會定義能夠將滑鼠點擊傳送至元素的 .NET 擴充方法 (TriggerClickEvent)。

JS 函式 clickElement 會在所傳遞的 HTML 元素 (element) 上建立 click 事件：

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

若要呼叫未傳回值的 JS 函式，請使用 JSRuntimeExtensions.InvokeVoidAsync。 下列程式碼會藉由使用所擷取的 ElementReference 呼叫上述 JS 函式來觸發用戶端 click 事件：

@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);
    }
}

若要使用擴充方法，請建立會接收 IJSRuntime 執行個體的靜態擴充方法：

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

系統會直接在該物件上呼叫 clickElement 方法。 下列範例假設 TriggerClickEvent 方法可從 JsInteropClasses 命名空間取得：

@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);
    }
}

重要

只有在轉譯元件後才會填入 exampleButton 變數。 如果未填入的 ElementReference 傳遞至 JS 程式碼，JS 程式碼會收到 null 值。 若要在元件轉譯完成後操作元件參考，請使用 OnAfterRenderAsync 或 OnAfterRender 元件生命週期方法。

使用泛型型別並傳回值時，請使用 ValueTask<TResult>：

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

{JAVASCRIPT FUNCTION} 預留位置是 JS 函式識別碼。

系統會直接在具有某個型別的物件上呼叫 GenericMethod。 下列範例假設 GenericMethod 可從 JsInteropClasses 命名空間取得：

@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);
    }
}

跨元件來參考元素

ElementReference 無法在元件之間傳遞，因為：

• 只有在元件轉譯後 (也就是在元件的 OnAfterRender/OnAfterRenderAsync 方法執行期間或之後)，執行個體才一定會存在。
• ElementReference 是 struct，其無法以元件參數的形式來傳遞。

若要讓父元件能夠將元素參考提供給其他元件使用，父元件可以：

• 允許子元件註冊回呼。
• 在 OnAfterRender 事件期間使用所傳遞的元素參考叫用已註冊的回呼。 此方法可間接地讓子元件與父元件的元素參考互動。

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

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

注意

如需 JS 位置的一般指導和我們對於生產應用程式的建議，請參閱 ASP.NET Core Blazor 應用程式中的 JavaScript 位置

CallJs7.razor (父元件)：

@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);
    }
}

在上述範例中，應用程式的命名空間是 BlazorSample。 如果在本機測試程式碼，請更新命名空間。

SurveyPrompt.razor (子元件)：

<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);
    }
}

在上述範例中，應用程式的命名空間是 BlazorSample 與 Shared 資料夾中的共用元件。 如果在本機測試程式碼，請更新命名空間。

強化 JavaScript Interop 呼叫

本節僅適用於互動式伺服器元件，但如果條件適合，用戶端元件也可以設定 JS Interop 逾時。

在具有伺服器互動功能的伺服器端應用程式中，JavaScript (JS) Interop 可能會因為網路錯誤而失敗，因此請將其視為不可靠的應用程式。 Blazor 應用程式會針對 JS Interop 呼叫使用一分鐘的逾時。 如果應用程式可以容許更積極的逾時，請使用下列其中一種方法來設定逾時。

使用 CircuitOptions.JSInteropDefaultCallTimeout 在 Program.cs 中設定全域逾時：

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

{TIMEOUT} 預留位置是 TimeSpan (例如，TimeSpan.FromSeconds(80))。

在元件程式碼中設定個別叫用逾時。 指定的逾時會覆寫 JSInteropDefaultCallTimeout 所設定的全域逾時：

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

在前述範例中:

• {TIMEOUT} 預留位置是 TimeSpan (例如，TimeSpan.FromSeconds(80))。
• {ID} 預留位置是所要叫用函式的識別碼。 例如，值 someScope.someFunction 會叫用函式 window.someScope.someFunction。

雖然 JS Interop 失敗的常見原因是伺服器端元件發生網路失敗，但您可以為用戶端元件的 JS Interop 呼叫設定個別叫用逾時。 Blazor雖然用戶端元件沒有 -SignalR 線路存在，JS但 Interop 呼叫可能會因為其他適用的原因而失敗。

如需資源耗盡的詳細資訊，請參閱 ASP.NET Core Blazor 互動式伺服器端轉譯的威脅風險降低指導。

避免循環物件參考

包含循環參考的物件無法在用戶端上進行序列化以便發出：

• .NET 方法呼叫。
• 當傳回型別具有循環參考時，來自 C# 的 JavaScript 方法呼叫。

會轉譯 UI 的 JavaScript 程式庫

您有時可能會希望使用能在瀏覽器 DOM 內產生可見使用者介面元素的 JavaScript (JS) 程式庫。 乍看之下，這似乎很困難，因為 Blazor 的差異系統仰賴於對 DOM 元素樹狀結構的控制力，如果某些外部程式碼變動 DOM 樹狀結構而使其套用差異的機制失效，就會發生錯誤。 這不是 Blazor 特有的限制。 任何差異型 UI 架構都會發生相同的挑戰。

幸運的是，在 Razor 元件 UI 中可靠地內嵌外部產生的 UI 是很簡單的程序。 建議使用的技術是讓元件的程式碼 (.razor 檔案) 產生空白元素。 就 Blazor 的差異系統而言，元素一律會空白，因此轉譯器不會遞迴至元素，而是會不理會其內容。 這可讓其以任意的外部管理內容填入元素。

下列範例會示範此概念。 在 if 陳述式內，當 firstRender 是 true 時，請使用 JS Interop 在 Blazor 外部與 unmanagedElement 互動。 例如，呼叫外部 JS 程式庫以填入元素。 在此元件移除之前，Blazor 都不會理會元素的內容。 元件移除時，元件的整個 DOM 子樹狀結構也會移除。

<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)
        {
            ...
        }
    }
}

請考慮下列使用開放原始碼 Mapbox API 來轉譯互動式地圖的範例。

下列 JS 模組會放入應用程式，或設為可從 Razor 類別庫取得。

注意

若要建立 Mapbox 地圖，請透過 Mapbox 登入取得存取權杖，並在下列程式碼中出現 {ACCESS TOKEN} 的位置提供此存取權杖。

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]);
}

若要產生正確樣式，請將下列樣式表標籤新增至主機 HTML 頁面。

將下列 <link> 元素新增至 <head> 元素標記 (<head> 內容的位置)：

<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)
            {
            }
        }
    }
}

上述範例會產生互動式地圖 UI。 使用者：

• 可以進行拖曳以便捲動或縮放。
• 選取會跳至預先定義位置的按鈕。

在前述範例中:

• 就 Blazor 而言，<div> 與 @ref="mapElement" 會保持空白。 mapbox-gl.js 指令碼可以安全地填入元素並修改其內容。 請將這項技術與任何會轉譯 UI 的 JS 程式庫搭配使用。 您可以在 Razor 元件內嵌來自第三方 JS SPA 架構的元件，前提是這些第三方元件不會嘗試連線到頁面的其他部分並進行修改。 讓外部 JS 程式碼修改 Blazor 未視為空白的元素並不安全。
• 使用此方法時，請牢記有關 Blazor 如何保留或終結 DOM 元素的規則。 元件會安全地處理按鈕點擊事件，並更新現有的地圖執行個體，因為系統會盡可能地保留 DOM 元素。 如果您從 @foreach 迴圈內轉譯地圖元素清單，請使用 @key 確保元件執行個體會獲得保留。 否則，清單資料的變更可能會導致元件執行個體以您不想要的方式保留先前執行個體的狀態。 如需詳細資訊，請參閱如何使用 @key 指示詞屬性來保留元素、元件和模型物件之間的關聯性。
• 此範例會在 JavaScript 模組內封裝 JS 邏輯和相依性，並使用 import 識別碼動態載入模組。 如需詳細資訊，請參閱 JavaScript 模組中的 JavaScript 隔離。

位元組陣列支援

Blazor 支援可避免將位元組陣列編碼/解碼為 Base64 的最佳化位元組陣列 JavaScript (JS) Interop。 下列範例使用 JS Interop 將位元組陣列傳遞至 JavaScript。

請提供 receiveByteArrayJS 函式。 系統會使用 InvokeVoidAsync 來呼叫此函式，而且此函式不會傳回值：

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

注意

如需 JS 位置的一般指導和我們對於生產應用程式的建議，請參閱 ASP.NET Core Blazor 應用程式中的 JavaScript 位置

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);
    }
}

從 .NET 串流至 JavaScript

Blazor 支援直接從 .NET 將資料串流至 JavaScript (JS)。 串流是使用 DotNetStreamReference 建立的。

DotNetStreamReference 代表 .NET 串流，並使用下列參數：

• stream：傳送至 JS 的串流。
• leaveOpen：判斷串流是否在傳輸後保持開啟。 如果未提供值，則 leaveOpen 會預設為 false。

在 JS 中，使用陣列緩衝區或可讀取的串流來接收資料：

• 使用 ArrayBuffer：

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

• 使用 ReadableStream：

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

在 C# 程式碼中：

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

在前述範例中:

• {STREAM} 預留位置代表傳送至 JS 的 Stream。
• JS 是所插入的 IJSRuntime 執行個體。

通常不需要處置 DotNetStreamReference 執行個體。 當 leaveOpen 設為其預設值 false 時，基礎 Stream 會在傳輸至 JS 之後自動處置。

如果 leaveOpen 是 true，則處置 DotNetStreamReference 不會處置其基礎 Stream。 應用程式的程式碼會決定處置基礎 Stream 的時機。 決定如何處置基礎 Stream 時，請考慮下列事項：

• 在傳輸至 JS 時處置 Stream 會被視為應用程式錯誤，並可能導致未處理的例外狀況發生。
• Stream 傳輸會在 DotNetStreamReference 作爲引數傳遞至 JS Interop 呼叫時立即開始，不論資料流是否實際用於 JS 邏輯。

鑒於這些特性，建議您只在 JS 完全取用基礎 Stream 之後，才處置基礎 (arrayBuffer 或 stream 解析所傳回的承諾)。 接著，只有在 JS 邏輯無條件地取用 DotNetStreamReference 時，才應該將它傳遞至 JS。

在 ASP.NET Core Blazor 中從 JavaScript 函式呼叫 .NET 方法會說明反向作業：從 JavaScript 串流至 .NET。

ASP.NET Core Blazor 檔案下載會說明如何在 Blazor 中下載檔案。

攔截 JavaScript 例外狀況

若要攔截 JS 例外狀況，請將 JS Interop 包裝在 try-catch 區塊中，並攔截 JSException。

在下列範例中，nonFunctionJS 函式不存在。 找不到函式時，便會截獲 JSException，並有 Message 指出下列錯誤：

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}";
        }
    }
}

中止長時間執行的 JavaScript 函式

在元件中使用 JSAbortController 和 CancellationTokenSource，從 C# 程式碼中止長時間執行的 JavaScript 函式。

下列 JSHelpers 類別包含模擬的長時間執行函式 longRunningFn，此函式會一直計算，直到 AbortController.signal 指出系統已呼叫 AbortController.abort 為止。 sleep 函式僅供示範之用，目的是為了模擬長時間執行的函式執行速度緩慢的情況，因此不會出現在生產程式碼中。 當元件呼叫 stopFn 時，系統便會透過 AbortSignal.aborted 上的 while 迴圈條件式檢查向 longRunningFn 發出中止訊號。

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

注意

如需 JS 位置的一般指導和我們對於生產應用程式的建議，請參閱 ASP.NET Core Blazor 應用程式中的 JavaScript 位置

下列 元件：

• 會在選取 Start Task 按鈕時叫用 JS 函式 longRunningFn。 系統會使用 CancellationTokenSource 來管理長時間執行函式的執行。 CancellationToken.Register 會設定 JS Interop 呼叫委派，以在 CancellationTokenSource.Token 取消時執行 JS 函式 stopFn。
• 選取了 Cancel Task 按鈕時，會透過呼叫 Cancel 取消 CancellationTokenSource.Token。
• 系統會在 Dispose 方法中處置 CancellationTokenSource。

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();
    }
}

瀏覽器的開發人員工具主控台會在已選取 Start Task 按鈕後，以及在選取 Cancel Task 按鈕後中止函式時，指出長時間執行的 JS 函式的執行狀況：

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

JavaScript [JSImport]/[JSExport] Interop

本節適用於用戶端元件。

除了根據 IJSRuntime 介面使用 Blazor 的 JS Interop 機制在用戶端元件中與 JavaScript (JS) 互動外，以 .NET 7 或更新版本為目標的應用程式也可以使用 JS[JSImport]/[JSExport] Interop API。

如需詳細資訊，請參閱 JavaScript JSImport/JSExport Interop 搭配 ASP.NET Core Blazor。

已解除封送的 JavaScript Interop

本節適用於用戶端元件。

使用 IJSUnmarshalledRuntime 介面解除封送 Interop 的做法已淘汰，請使用 JavaScript [JSImport]/[JSExport] Interop 加以取代。

如需詳細資訊，請參閱 JavaScript JSImport/JSExport Interop 搭配 ASP.NET Core Blazor。

處置 JavaScript Interop 物件參考

JavaScript (JS) Interop 文章中的範例會示範典型的物件處置模式：

• 如本文所述從 .NET 呼叫 JS 時，請處置任何從 .NET 或從 JS 建立的 IJSObjectReference/IJSInProcessObjectReference/JSObjectReference，以免流失 JS 記憶體。

• 如在 ASP.NET Core Blazor 中從 JavaScript 函式呼叫 .NET 方法中所述從 JS 呼叫 .NET 時，請處置從 .NET 或從 JS 建立的 DotNetObjectReference，以免流失 .NET 記憶體。

JS Interop 物件參考會實作為對應，且會由建立參考的 JS Interop 呼叫端上的識別碼建立索引鍵。 從 .NET 或 JS 端起始物件處置時，Blazor 會從對應中移除該項目，只要物件沒有其他強式參考存在，就可以對物件進行記憶體回收。

至少，請一律處置在 .NET 端建立的物件，以免 .NET 受控記憶體流失。

元件處置期間的 DOM 清除工作

如需詳細資訊，請參閱 ASP.NET Core Blazor JavaScript 互通性 (JS Interop)。

沒有線路的 JavaScript Interop 呼叫

如需詳細資訊，請參閱 ASP.NET Core Blazor JavaScript 互通性 (JS Interop)。

其他資源

• 從 ASP.NET Core Blazor 中的 .NET 方法呼叫 JavaScript 函式
• InteropComponent.razor 範例 (dotnet/AspNetCore GitHub 存放庫 main 分支)：main 分支代表產品單位針對下一版 ASP.NET Core 的目前開發項目。 若要選取不同版本的分支（例如， release/{VERSION}佔 {VERSION} 位元是發行版本），請使用 [ 切換分支或標籤 ] 下拉式清單來選取分支。 對於已不存在的分支，請使用 [ 捲標] 索引標籤 來尋找 API （例如 ， v7.0.0。
• Blazor 範例 GitHub 存放庫 (dotnet/blazor-samples) (如何下載)
• 處理 ASP.NET Core Blazor 應用程式中的錯誤 (JavaScript Interop 區段)
• 威脅風險降低：從 .NET 叫用的 JavaScript 函式