在 ASP.NET Core Blazor 中从 .NET 方法调用 JavaScript 函数

本文介绍如何从 .NET 调用 JavaScript (JS) 函数。

有关如何从 JS 调用 .NET 方法的信息，请参阅JS。

调用 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。 有关详细信息，请参阅预呈现部分。

下面的示例基于 TextDecoder（一种基于 JS 的解码器）。 此示例展示了如何通过 C# 方法调用 JS 函数，以将要求从开发人员代码卸载到现 JS API。 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 互操作机制来调用这些 API，因为 UI 事件处理是异步执行的，通常不再在用户手势的上下文中执行。 应用必须完全在 JavaScript 中处理 UI 事件，因此，要使用 onclick 而不是 Blazor 的 @onclick 指令属性。

调用 JavaScript 函数，而不读取返回的值 (InvokeVoidAsync)

在以下情况下使用 InvokeVoidAsync：

• .NET 不需要读取 JavaScript (JS) 调用的结果。
• JS 函数返回 JS 或 undefined。

提供 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 中的交互式路由的内部导航不涉及从服务器请求新页面内容。 因此，内部页面请求不会发生预呈现。 如果应用采用交互式路由，请对演示预呈现行为的组件示例执行完整页面重载。 有关详细信息，请参阅 Prerender ASP.NET Core Razor 组件。

在预呈现期间，无法调用 JavaScript (JS)。 以下组件演示了如何以一种与预呈现兼容的方式将 JS 互操作用作组件初始化逻辑的一部分。

以下 scrollElementIntoView 函数：

• 使用 scrollIntoView 滚动到传递的元素。
• 从 getBoundingClientRect 方法返回元素的 top 属性值。

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

如果 IJSRuntime.InvokeAsync 调用组件代码中的 JS 函数，则 ElementReference 仅在 OnAfterRenderAsync 中使用，而不在任何更早的生命周期方法中使用，因为呈现组件后才会有 HTML DOM 元素。

调用 StateHasChanged（引用源），以使用从 JS 互操作调用获得的新状态将组件的重新呈现加入队列（有关详细信息，请参阅 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 互操作

本部分仅适用于客户端组件。

JS 互操作调用是异步的，无论调用的代码是同步还是异步。 调用是异步的，以确保组件在服务器端和客户端呈现模式之间都兼容。 在服务器上，所有 JS 互操作调用都必须是异步的，因为它们通过网络连接发送。

如果你确定组件只在 WebAssembly 上运行，则可以选择执行同步 JS 互操作调用。 这比进行异步调用的开销略少，并且可能会导致呈现周期更少，因为在等待结果时没有中间状态。

若要在客户端组件中进行从 .NET 到 JavaScript 的同步调用，请将 IJSRuntime 强制转换为 IJSInProcessRuntime 以进行 JS 互操作调用：

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

JavaScript 位置

使用有关 JavaScript 位置一文介绍的任何方法加载 JavaScript（JS）代码：

• 在 <head> 标记中加载脚本（通常不推荐）
• 在 <body> 标记中加载脚本
• 从与组件并置的外部 JavaScript 文件 (.js) 加载脚本
• 从外部 JavaScript 文件 (.js) 加载脚本
• 在 Blazor 启动前/后注入脚本

有关在 JS 模块中隔离脚本的信息，请参阅 JavaScript 模块中的 JavaScript 隔离部分。

警告

仅当保证组件采用静态服务器端呈现（静态 SSR）时，才会将 <script> 标记放置在组件文件 (.razor) 中，因为无法动态更新 <script> 标记。

JavaScript 模块中的 JavaScript 隔离

Blazor 在标准 Blazor（JS）中启用 JavaScript (JS) 隔离。 JavaScript 模块加载在 Blazor 中的工作方式与在其他类型的 Web 应用中相同，你可以随意自定义模块在应用中的定义方式。 有关如何使用 JavaScript 模块的指南，请参阅 MDN Web文档：JavaScript 模块。

JS 隔离具有以下优势：

• 导入的 JS 不再污染全局命名空间。
• 库和组件的使用者不需要导入相关的 JS。

ASP.NET Core 和 Blazor 支持使用 import() 运算符的动态导入：

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

在前面的示例中，{CONDITION} 占位符表示用于确定是否应加载模块的条件检查。

有关浏览器兼容性，请参阅是否可以使用：JavaScript 模块：动态导入。

例如，以下 JS 模块导出用于显示JS的 JS 函数。 将以下 JS 代码置于外部 JS 文件中。

wwwroot/scripts.js：

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

将前面的 JS 模块作为 wwwroot 文件夹中的静态 Web 资产添加到应用或类库中，然后通过调用 IJSRuntime 实例上的 InvokeAsync 将该模块导入 .NET 代码。

IJSRuntime 将模块作为 IJSObjectReference 导入，它表示对 .NET 代码中 JS 对象的引用。 使用 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)
        {
            await module.DisposeAsync();
        }
    }
}

在上面的示例中：

• 按照约定，import 标识符是专门用于导入 JS 模块的特殊标识符。
• 使用稳定的静态 Web 资产路径 ./{SCRIPT PATH AND FILE NAME (.js)} 指定该模块的外部 JS 文件，其中：
  • 若要创建 JS 文件的正确静态资产路径，需要当前目录 (./) 的路径段。
  • {SCRIPT PATH AND FILE NAME (.js)} 占位符是 wwwroot 下的路径和文件名。
• 在 IAsyncDisposable.DisposeAsync 中为IJSObjectReference 处置 IJSObjectReference。

动态导入模块需要网络请求，因此只能通过调用 InvokeAsync 来异步实现。

IJSInProcessObjectReference 表示对某个 JS 对象的引用，该对象的函数可以在客户端组件中同步调用。 有关详细信息，请参阅客户端组件中的同步 JS 互操作部分。

注意

当外部 JS 文件由 JS提供时，使用其稳定的静态 Web 资产路径 ./_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)} 指定模块的 JS 文件：

• 若要创建 JS 文件的正确静态资产路径，需要当前目录 (./) 的路径段。
• {PACKAGE ID} 占位符是库的包 ID。 如果项目文件中没有指定 <PackageId>，则包 ID 默认为项目的程序集名称。 在下面的示例中，库的程序集名称为 ComponentLibrary，并且库的项目文件未指定 <PackageId>。
• {SCRIPT PATH AND FILE NAME (.js)} 占位符是 wwwroot 下的路径和文件名。 在以下实例中，外部 JS 文件 (script.js) 置于类库的 wwwroot 文件夹中。
• module 是组件类 (private IJSObjectReference? module;) 的私有可为空 IJSObjectReference。

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

有关详细信息，请参阅使用 Razor 类库 (RCL) 中的 ASP.NET Core Razor 组件。

在整个 Blazor 文档中，示例对模块文件使用 .js 文件扩展名，而不是较新的 .mjs 文件扩展名 (RFC 9239)。 我们的文档继续使用 .js 文件扩展名，原因与 Mozilla 基金会的文档继续使用 .js 文件扩展名的原因相同。 有关详细信息，请参阅 Aside — .mjs 与 js（MDN 文档）。

捕获对元素的引用

某些 JavaScript (JS) 互操作方案需要引用 HTML 元素。 例如，一个 UI 库可能需要用于初始化的元素引用，或者你可能需要对元素调用类似于命令的 API（如 click 或 play）。

使用以下方法在组件中捕获对 HTML 元素的引用：

• 向 HTML 元素添加 @ref 属性。
• 定义一个类型为 ElementReference 字段，其名称与 @ref 属性的值匹配。

以下示例演示如何捕获对 username <input> 元素的引用：

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

@code {
    private ElementReference username;
}

警告

只使用元素引用改变不与 Blazor 交互的空元素的内容。 当第三方 API 向元素提供内容时，此方案十分有用。 由于 Blazor 不与元素交互，因此在 Blazor 的元素表示形式与 DOM 之间不可能存在冲突。

在下面的示例中，使用 MyList 通过 JS 互操作改变无序列表 (ul) 的内容具有危险性，因为 Blazor 会与 DOM 交互以填充此来自 Todos 对象的元素的列表项 (<li>)：

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

支持使用 MyList 元素引用来仅读取 DOM 内容或触发事件。

如果 JS 互操作改变元素 MyList 的内容，并且 Blazor 尝试将差异应用于元素，则差异与 DOM 不匹配。 不支持通过 JS 互操作使用 MyList 元素引用来修改列表内容。

有关详细信息，请参阅 ASP.NET Core BlazorJavaScript 互操作性（JS 互操作）。

通过 JS 互操作将 ElementReference 传递给 JS 代码。 JS 代码会收到一个 HTMLElement 实例，该实例可以与常规 DOM API 一起使用。 例如，下面的代码定义了一个 .NET 扩展方法 (TriggerClickEvent)，该方法的作用是将鼠标单击事件发送到某个元素。

JS 函数 clickElement 在已传递的 HTML 元素 (element) 上创建 click 事件：

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

若要调用不返回值的 JS 函数，请使用 JSRuntimeExtensions.InvokeVoidAsync。 下面的代码使用捕获的 click 调用上面的 JS 函数，触发客户端 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);
    }
}

若要使用扩展方法，请创建接收 IJSRuntime 实例的静态扩展方法：

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

clickElement 方法在对象上直接调用。 下面的示例假设可从 JsInteropClasses 命名空间使用 TriggerClickEvent 方法：

@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 在具有类型的对象上直接调用。 下面的示例假设可从 JsInteropClasses 命名空间使用 GenericMethod：

@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，不能作为ElementReference传递。

若要使父组件可以向其他组件提供元素引用，父组件可以：

• 允许子组件注册回调。
• 在 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 互操作调用

本部分仅适用于交互式服务器组件，但如果条件允许，客户端组件也可设置 JS 互操作超时。

在具有服务器交互性的服务器端应用中，JavaScript (JS) 互操作可能会由于网络错误而失败，因此应被视为不可靠。 Blazor 应用对 JS 互操作调用使用一分钟超时。 如果应用可以容忍更激进的超时，请使用以下方法之一设置超时。

通过 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 互操作失败的一个常见原因是服务器端组件发生网络故障，但可以针对客户端组件的 JS 互操作调用设置每个调用超时。 尽管客户端组件不存在 SignalR 线路，但 JS 互操作调用可能会由于适用的的其他原因而失败。

有关资源耗尽的详细信息，请参阅 ASP.NET Core Blazor 交互式服务器端呈现的威胁缓解指南。

避免循环引用对象

不能在客户端上针对以下调用就包含循环引用的对象进行序列化：

• .NET 方法调用。
• 返回类型具有循环引用时，从 C# 发出的 JavaScript 方法调用。

呈现 UI 的 JavaScript 库

有时你可能需要使用在浏览器 DOM 内生成可见用户界面元素的 JavaScript (JS) 库。 乍一想，这似乎很难，因为 Blazor 的 diffing 系统依赖于对 DOM 元素树的控制，并且如果某个外部代码使 DOM 树发生变化并为了应用 diff 而使其机制失效，就会产生错误。 这并不是一个特定于 Blazor 的限制。 任何基于 diff 的 UI 框架都会面临同样的问题。

幸运的是，将外部生成的 UI 可靠地嵌入到 Razor 组件 UI 非常简单。 推荐的方法是让组件的代码（.razor 文件）生成一个空元素。 就 Blazor 的 diffing 系统而言，该元素始终为空，这样呈现器就不会递归到元素中，而是保留元素内容不变。 这样就可以安全地用外部托管的任意内容来填充元素。

以下示例演示了这一概念。 在 if 语句中，当 firstRender 为 true 时，使用 JS 互操作与 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)
        {
            await mapInstance.DisposeAsync();
        }

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

前面的示例会生成一个交互式地图 UI。 用户：

• 拖动鼠标可以滚动或缩放。
• 选择相关按钮可跳转到预定义的位置。

在上面的示例中：

• 就 Blazor 而言，具有 @ref="mapElement" 的 <div> 保留为空。 mapbox-gl.js 脚本可以安全地填充元素并修改其内容。 将此方法与呈现 UI 的任何 JS 库配合使用。 可以在 Razor 组件中嵌入第三方 JS SPA 框架中的组件，只要它们不会尝试访问和改变页面的其他部分。 对于外部 代码，修改 Blazor 不视为空元素的元素是不安全的。
• 使用此方法时，请记得有关 Blazor 保留或销毁 DOM 元素的方式的规则。 组件之所以能够安全处理按钮单击事件并更新现有的地图实例，是因为在可能的情况下会保留 DOM 元素。 如果之前要从 @foreach 循环内呈现地图元素的列表，则需要使用 @key 来确保保留组件实例。 否则，列表数据的更改可能导致组件实例以不合适的方式保留以前实例的状态。 有关详细信息，请参阅如何使用 @key 指令属性来保留元素、组件和模型对象之间的关系。
• 该示例在 JavaScript 模块中封装 JS 逻辑和依赖项，并使用 import 标识符动态加载模块。 有关详细信息，请参阅 JavaScript 模块中的 JavaScript 隔离。

字节数组支持

Blazor 支持优化的字节数组 JavaScript (JS) 互操作，这可以避免将字节数组编码/解码为 Base64。 以下示例使用 JS 互操作将字节数组传递给 JavaScript。

提供 receiveByteArrayJS 函数。 该函数通过 InvokeVoidAsync 进行调用，不返回值：

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

注意

有关生产应用的 JS 位置和建议的一般指南，请参阅 “ASP.NET CoreBlazor 应用中的 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 互操作调用后立即开始（无论流是否实际用于 JS 逻辑中）。

鉴于这些特征，建议仅在 JS 完全使用基础 Stream（解析 arrayBuffer 或 stream 返回的承诺）后才释放它。 因此，仅当 DotNetStreamReference 将被 JS 逻辑无条件地使用时，才应将它传递到 JS。

在 ASP.NET Core Blazor 中从 JavaScript 函数调用 .NET 方法介绍了反向操作，即从 JavaScript 流式传输到 .NET。

ASP.NET Core Blazor 文件下载介绍了如何在 Blazor 中下载文件。

捕获 JavaScript 异常

若要捕获 JS 异常，请将 JS 互操作包装在 JS中，并捕获一个 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 时，longRunningFn 通过对 AbortSignal.aborted 的 while 循环条件检查，收到中止信号。

<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 互操作调用委托，以在 CancellationTokenSource.Token 被取消时执行 JS 函数 stopFn。
• 选择“Cancel Task”按钮后，CancellationTokenSource.Token 被取消，并发生对 Cancel 的调用。
• 在 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] 互操作

本部分适用于客户端组件。

作为基于 IJSRuntime 接口使用 Blazor 的 JS 互操作机制与客户端组件中的 JavaScript (JS) 交互的替代方法，JS[JSImport]/[JSExport] 互操作 API 可用于面向 .NET 7 或更高版本的应用。

有关详细信息，请参阅 JavaScript JSImport/JSExport 与 ASP.NET Core Blazor 互操作。

未封装的 JavaScript 互操作

本部分适用于客户端组件。

使用 IJSUnmarshalledRuntime 接口未封装的互操作已过时，应替换为 JavaScript [JSImport]/[JSExport] 互操作。

有关详细信息，请参阅 JavaScript JSImport/JSExport 与 ASP.NET Core Blazor 互操作。

JavaScript 互操作对象引用的释放

JavaScript (JS) 互操作文章中的示例演示了典型的对象释放模式：

• 从 .NET 调用 JS 时，如本文中所述，释放从 .NET 或从 JS 创建的 IJSObjectReference/IJSInProcessObjectReference/JSObjectReference，以避免泄漏 JS 内存。

• 从 JS 调用 .NET 时，如在 ASP.NET Core Blazor 中从 JavaScript 函数调用 .NET 方法中所述，释放从 .NET 或从 JS 创建的 DotNetObjectReference，以避免泄漏 .NET 内存。

JS 互操作对象引用作为映射实现，该映射按创建引用的 JS 互操作调用端的标识符键控。 从 .NET 或 JS 端启动对象释放时，Blazor 会从映射中删除该条目，只要不存在对对象的其他强引用，就可以对对象进行垃圾回收。

至少应始终释放在 .NET 端创建的对象，避免泄漏 .NET 托管内存。

组件处置期间的 DOM 清理任务

有关详细信息，请参阅 ASP.NET Core BlazorJavaScript 互操作性（JS 互操作）。

无线路的 JavaScript 互操作调用

有关详细信息，请参阅 ASP.NET Core BlazorJavaScript 互操作性（JS 互操作）。

其他资源

• 在 ASP.NET Core Blazor 中从 JavaScript 函数调用 .NET 方法
• InteropComponent.razor 示例（dotnet/AspNetCore GitHub 存储库 main 分支）：main 分支表示产品单元针对下一个 ASP.NET Core 版本的当前开发。 要为其他版本（例如 release/5.0）选择分支，请使用“切换分支或标记”下拉列表来选择分支。
• Blazor 示例 GitHub 存储库 (dotnet/blazor-samples)（下载方法）
• 处理 ASP.NET Core Blazor 应用中的错误（“JavaScript 互操作”部分）
• 威胁缓解措施：从 .NET 调用的 JavaScript 函数