Вызов функций JavaScript из методов .NET в ASP.NET Core Blazor

В этой статье объясняется, как вызывать функции JavaScript (JS) из .NET.

Сведения о том, как вызывать методы .NET из JS, смотрите в разделе Вызов методов .NET из функций JavaScript в Blazor ASP.NET Core.

JS Вызов функций

IJSRuntime регистрируется платформой Blazor. Для вызова JS из .NET внедрите абстракцию IJSRuntime и вызовите один из следующих методов:

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

Для предыдущих методов .NET, которые вызывают функции JS:

• Идентификатор функции (String) задается относительно глобальной области (window). Чтобы вызвать функцию window.someScope.someFunction, необходимо использовать идентификатор someScope.someFunction. Регистрировать функцию перед ее вызовом не требуется.
• Передайте в функцию Object[] любое количество аргументов, сериализуемых в JS формате JSON.
• Токен отмены (CancellationToken) распространяет уведомление о том, что операции должны быть отменены.
• TimeSpan представляет предельное время для операции JS.
• Возвращаемый TValue тип также должен быть сериализуемым в формате JSON. Тип TValue должен соответствовать типу .NET, который лучше всего соответствует возвращаемому типу JSON.
• Для методов JS Promise возвращается InvokeAsync. InvokeAsync распаковывает Promise и возвращает ожидаемое значение Promise.

Для Blazor приложений с включенной предварительной отрисовкой, которая используется по умолчанию для серверных приложений, вызов JS не возможен во время предварительной отрисовки. Дополнительные сведения см. в разделе Предварительная отрисовка.

Приведенный ниже пример основан на TextDecoder, декодере на базе JS. В примере показано, как вызвать функцию JS из метода C#, которая переносит требование из кода разработчика в существующий API 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 расположению и наши рекомендации для рабочих приложений см. в статье "Расположение JavaScript в приложениях ASP.NET CoreBlazor".

Приведенный ниже компонент:

• Вызывает функцию convertArrayJS с помощью метода InvokeAsync при нажатии кнопки (Convert Array).
• После вызова функции 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));
}

API JavaScript ограничены жестами пользователя

Этот раздел относится к компонентам на стороне сервера.

Некоторые API JavaScript (JS) браузера могут выполняться только в контексте пользовательского жеста, например с помощью Fullscreen API. Эти API не могут вызываться через JS механизм взаимодействия в компонентах на стороне сервера, так как обработка событий пользовательского интерфейса выполняется асинхронно и обычно не в контексте жеста пользователя. Приложение должно полностью обрабатывать событие интерфейса в JavaScript, поэтому используйте onclick вместо директивного атрибута Blazor@onclick.

Вызов функций JavaScript без считывания возвращаемого значения (InvokeVoidAsync)

InvokeVoidAsync следует использовать в следующих случаях:

• Для считывания результата вызова JavaScript (JS) .NET не требуется.
• для функций JS, возвращающих значение void(0)/void 0 или undefined.

Укажите функцию displayTickerAlert1JS. Функция вызывается с помощью метода InvokeVoidAsync и не возвращает значение:

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

Примечание.

Общие рекомендации по JS расположению и наши рекомендации для рабочих приложений см. в статье "Расположение JavaScript в приложениях ASP.NET CoreBlazor".

Пример (.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)

Используйте InvokeAsync, если .NET нужно считать результат вызова JavaScript (JS).

Укажите функцию 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 расположению и наши рекомендации для рабочих приложений см. в статье "Расположение JavaScript в приложениях ASP.NET CoreBlazor".

Пример (.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 компоненты. Предварительная отрисовка рассматривается в компоненты Prerender ASP.NET CoreRazor.

Примечание.

Внутренняя навигация для интерактивной маршрутизации в Blazor Web Apps не включает запрос нового содержимого страницы с сервера. Поэтому предварительное отображение не выполняется для внутренних запросов страниц. Если приложение использует интерактивную маршрутизацию, выполните полную перезагрузку страницы для примеров компонентов, демонстрирующих поведение предварительного рендеринга. Дополнительные сведения см. в разделе Предварительный рендеринг компонентов ASP.NET CoreRazor.

Во время предварительной подготовки обращение к JavaScript (JS) невозможно. В следующем примере показано, как использовать JS взаимодействие в рамках логики инициализации компонента таким образом, который совместим с предварительным рендерингом.

Следующая функция scrollElementIntoView :

• Прокручивается до переданного элемента с помощью scrollIntoView.
• Возвращает значение свойства элемента top из getBoundingClientRect метода.

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

В коде компонента IJSRuntime.InvokeAsync вызывает функцию JS, и ElementReference используется только в OnAfterRenderAsync, а не в более ранних методах жизненного цикла, поскольку элемент HTML DOM не существует до отрисовки компонента.

StateHasChanged (ссылочный источник) вызывается для постановки в очередь повторного рендеринга компонента с новым состоянием, полученным в результате вызова взаимодействия JS (для получения дополнительной информации см. рендеринг компонентов Razor в ASP.NET Core). Бесконечный цикл не создается, потому что StateHasChanged вызывается только тогда, когда scrollPosition является null.

PrerenderedInterop.razor:

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

<PageTitle>Prerendered Interop</PageTitle>

<h1>Prerendered Interop Example</h1>

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

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

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

            StateHasChanged();
        }
    }
}

В предыдущем примере клиент загрязняет глобальную функцию. Более эффективный подход для приложений в рабочей среде приведен в разделе Изоляция 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 реализует IAsyncDisposable/IDisposable и должен быть корректно освобожден для сборки мусора, чтобы предотвратить утечку памяти, как показано в следующем примере:

@inject IJSRuntime JS
@implements IDisposable

...

@code {
    ...
    private IJSInProcessObjectReference? module;

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

    ...

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

В предыдущем примере JSDisconnectedException не блокируется во время удаления модуля, потому что в Blazor приложении нет SignalR-Blazor WebAssembly цепи, которую можно потерять. Дополнительные сведения см. в разделе JS.

Расположение JavaScript

Загрузите код JavaScript (JS) с помощью любого из подходов, описанных в статье о расположении JavaScript:

• Загрузите скрипт в разметке <head> (обычно не рекомендуется).
• Загрузите сценарий в разметку <body>.
• Загрузите скрипт из внешнего файла JavaScript (.js), размещенного совместно с компонентом
• Загрузите скрипт из внешнего файла JavaScript (.js)
• Внедрение скрипта до или после Blazor запуска

Сведения об изоляции скриптов в модулях JS см. в разделе Изоляция JavaScript в модулях JavaScript.

Предупреждение

Только поместите <script> тег в файл компонента (.razor), если компонент гарантированно использует статическую отрисовку на стороне сервера (статический SSR), так как <script> тег не может быть динамически обновлен.

Изоляция JavaScript в JavaScript-модулях

Blazor реализует изоляцию JavaScript (JS) в стандартных модулях JavaScript (см. спецификацию ECMAScript). Загрузка модуля JavaScript работает так же в Blazor, как и для других типов веб-приложений, и вы можете настраивать способ, которым определяются модули в вашем приложении. См. MDN Web Docs: модули JavaScript для руководства по использованию модулей JavaScript.

Изоляция JS обеспечивает следующие преимущества:

• Импортированный JS не засоряет глобальное пространство имен.
• Пользователям библиотеки и компонентов не требуется импортировать связанный код JS.

Динамический import() импорт с оператором поддерживается с ASP.NET Core и Blazor:

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

В предыдущем примере заполнитель {CONDITION} представляет условную проверку, чтобы определить, следует ли загрузить модуль.

Сведения о совместимости браузера см. в разделе "Можно ли использовать: модули JavaScript: динамический импорт".

В сценариях JS на стороне сервера вызовы межоперационного взаимодействия не могут быть выданы после отключения BlazorSignalR канала. Без канала во время удаления компонентов или в любое другое время, когда канал не существует, следующий метод вызывает сбой и записывает сообщение о том, что канал отключен как:JSDisconnectedException

• JS Вызовы метода взаимодействия
  • IJSRuntime.InvokeAsync
  • JSRuntimeExtensions.InvokeAsync
  • JSRuntimeExtensions.InvokeVoidAsync)
• Dispose / DisposeAsync вызывает любого IJSObjectReference.

Чтобы избежать ведения журнала JSDisconnectedException или регистрировать пользовательские сведения на стороне сервера Blazor, ловите исключение в инструкции try-catch.

Для примера утилизации компонентов:

• Серверный компонент реализует IAsyncDisposable.
• module — это IJSObjectReference для JS модуля.
• JSDisconnectedException перехватывается и не регистрируется.
• Кроме того, вы можете записывать пользовательские сведения в инструкцию catch на любом выбранном уровне журнала. В следующем примере не регистрируются пользовательские сведения. В коде предполагается, что разработчик не заботится о том, когда или где каналы отключены во время удаления компонентов.

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

Если необходимо очистить собственные JS объекты или выполнить другой JS код на клиенте после потери канала в серверном Blazor приложении, используйте MutationObserver шаблон JS в клиенте. Шаблон MutationObserver позволяет выполнять JS код при удалении элемента из DOM.

Дополнительные сведения см. в следующих статьях:

• ASP.NET Core Blazor Взаимодействие с JavaScript (JS interop): включает пример MutationObserver шаблона кода.
• Обработка ошибок в приложениях Blazor: В разделе взаимодействия JavaScript обсуждается обработка ошибок в сценариях взаимодействия.
• ASP.NET Core Razor утилизация компонентов: в статье описывается, как реализовать шаблоны утилизации в компонентах Razor.

JS Данный модуль экспортирует JS функцию для отображения подсказки в окне браузера. Поместите следующий код JS во внешний файл JS.

wwwroot/scripts.js:

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

Добавьте предыдущий модуль JS в приложение или библиотеку классов в виде статического веб-ресурса в папке wwwroot, а затем импортируйте модуль в код .NET, вызвав InvokeAsync для экземпляра IJSRuntime.

IJSRuntime импортирует модуль как IJSObjectReference. Это представление ссылки на объект JS из кода .NET. Используйте 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.
• Укажите внешний JS файл модуля, используя стабильный путь к статическим веб-ресурсам: ./{SCRIPT PATH AND FILE NAME (.js)}, где:
  • Сегмент пути для текущего каталога (./) необходим для создания корректного пути к статическому ресурсу в файле JS.
  • Заполнитель {SCRIPT PATH AND FILE NAME (.js)} — это путь и имя файла в папке wwwroot.
• Уничтожает IJSObjectReference для сборки мусора в IAsyncDisposable.DisposeAsync.
• Не помещайте тег <script> для скрипта после скрипта Blazor, так как модуль загружается и кэшируется автоматически при вызове динамического import().

Для динамического импорта модуля требуется сетевой запрос, поэтому его можно выполнить только асинхронно, вызвав InvokeAsync.

IJSInProcessObjectReference представляет ссылку на JS объект, функции которого можно вызывать синхронно в клиентских компонентах. Дополнительные сведения см. в разделе синхронного JS взаимодействия в клиентских компонентах.

Примечание.

Если внешний файл JS предоставляется библиотекой классов Razor, укажите файл 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 является приватным полем IJSObjectReference, которое может принимать значение null, в классе компонента (private IJSObjectReference? module;).

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

Дополнительные сведения см. в статье Использование компонентов Razor в ASP.NET Core из библиотеки классов Razor (RCL).

Blazor В документации примеры используют .js расширение файла для файлов модулей, а не более новое .mjs расширение файла (RFC 9239). Наша документация продолжает использовать .js расширение файла по тем же причинам, что документация Mozilla Foundation продолжает использовать .js расширение файла. Дополнительные сведения см. в разделе Aside — сравнение .mjs с .js (документация по MDN).

Получение ссылок на элементы

Некоторые сценарии взаимодействия JavaScript (JS) требуют ссылки на HTML-элементы. Например, ссылка на элемент может требоваться библиотеке пользовательского интерфейса для инициализации либо необходимо вызывать командные интерфейсы API для элемента, такого как click или play.

Для получения ссылок на элементы HTML в компоненте используйте описанный ниже подход.

• Добавьте атрибут @ref к элементу HTML.
• Определите поле типа ElementReference, имя которого совпадает со значением атрибута @ref.

В следующем примере показано получение ссылки на элемент username<input>:

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

@code {
    private ElementReference username;
}

Предупреждение

Ссылку на элемент следует использовать только для изменения содержимого пустого элемента, который не взаимодействует с Blazor. Этот сценарий полезен, если сторонний интерфейс API предоставляет содержимое элементу. Так как Blazor не взаимодействует с элементом, риск конфликта между представлением Blazor элемента и моделью DOM отсутствует.

В следующем примере опасно модифицировать содержимое неупорядоченного списка (ul) с помощью MyList через JS взаимодействие, потому что Blazor взаимодействует с DOM, чтобы заполнить элементы списка этого элемента (<li>) из объекта Todos.

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

MyList Использование ссылки на элемент для простого чтения содержимого DOM или активации события поддерживается.

Если JS interop изменяет содержимое элемента MyList, и Blazor пытается применить диффы к элементу, диффы не будут соответствовать DOM. Изменение содержимого списка через взаимодействие с ссылкой на элемент не поддерживается.

Дополнительные сведения см. в разделе JS.

ElementReference передается в код JS посредством взаимодействия с JS. Код JS получает экземпляр HTMLElement, который может использоваться с обычными интерфейсами API DOM. Например, в приведенном ниже коде определяется метод расширения .NET (TriggerClickEvent), который позволяет отправить щелчок мыши в элемент.

Функция JSclickElement создает событие click в переданном элементе HTML (element):

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 вызывается для объекта напрямую. В следующем примере предполагается, что метод 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 расположению и наши рекомендации для рабочих приложений см. в статье "Расположение JavaScript в приложениях ASP.NET CoreBlazor".

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 вызовов взаимодействия. Если для приложения допустимо более короткое время ожидания, установите его одним из указанных ниже способов.

Установите глобальное время ожидания в Program.cs с использованием CircuitOptions.JSInteropDefaultCallTimeout:

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

Заполнитель {TIMEOUT} — это TimeSpan (например, TimeSpan.FromSeconds(80)).

Задайте время ожидания для отдельного вызова в коде компонента. Указанное время ожидания переопределяет глобальное время ожидания, установленное свойством JSInteropDefaultCallTimeout:

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

В предыдущем примере:

• Заполнитель {TIMEOUT} — это TimeSpan (например, TimeSpan.FromSeconds(80)).
• Заполнитель {ID} является идентификатором вызываемой функции. Например, значение someScope.someFunction вызывает функцию window.someScope.someFunction.

Хотя распространенными причинами JS сбоев взаимодействия являются сбои сети с компонентами на стороне сервера, время ожидания для каждого вызова можно задать для JS вызовов взаимодействия для клиентских компонентов. Хотя канал BlazorSignalR не существует для клиентского компонента, JS вызовы взаимодействия могут сбоить по другим применимым причинам.

Для получения дополнительных сведений об исчерпании ресурсов смотрите Руководство по смягчению угроз для интерактивного серверного рендеринга в ASP.NET Core.

Исключение циклических ссылок на объекты

Объекты, содержащие циклические ссылки, не могут быть сериализованы на клиенте по причине:

• Вызовы методов .NET.
• Вызовы методов JavaScript из C#, когда тип возвращаемого значения имеет циклические ссылки.

Библиотеки JavaScript, отображающие пользовательский интерфейс

Иногда может потребоваться использовать библиотеки JavaScript (JS), которые создают видимые элементы пользовательского интерфейса в браузере DOM. На первый взгляд, это может показаться сложным, так как система различий Blazor предполагает контроль над деревом элементов DOM и сталкивается с ошибками, если какой-либо внешний код изменяет дерево DOM, нарушая механизм применения различий. Это ограничение не относится лишь к Blazor. Такая же проблема возникает при использовании любого фреймворка пользовательского интерфейса на основе различий.

К счастью, в пользовательский интерфейс компонента Razor можно легко внедрить внешний пользовательский интерфейс. Рекомендуемым методом является создание пустого элемента кодом компонента (в файле .razor). С точки зрения системы выявления различий Blazor, элемент всегда пуст, поэтому отрисовщик не углубляется в элемент и оставляет его содержимое нетронутым. Это позволяет спокойно заполнить элемент произвольным содержимым, управляемым извне.

Данный принцип демонстрируется в приведенном ниже примере. В инструкции if, когда firstRender имеет значение true, взаимодействуйте с unmanagedElement за пределами Blazor с использованием JS межоперационного взаимодействия. Например, вызовите внешнюю библиотеку 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)
        {
            ...
        }
    }
}

Рассмотрим указанный ниже пример, который отрисовывает интерактивную карту с помощью интерфейсов API Mapbox с открытым кодом.

Следующий модуль JS помещается в приложение или предоставляется из библиотеки классов Razor.

Примечание.

Чтобы создать карту Mapbox, получите маркер доступа от Mapbox Sign in и укажите его в том месте, где в следующем коде отображается {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)
            {
            }
        }
    }
}

В предыдущем примере создается интерактивный пользовательский интерфейс карты. Пользователь:

• Можно прокручивать или масштабировать, перетаскивая.
• Выберите кнопки для перехода к заданным местам.

В предыдущем примере:

• <div> с @ref="mapElement", если говорить о Blazor, остается пустым. С помощью скрипта mapbox-gl.js можно безопасно заполнять элемент и изменять его содержимое. Используйте этот метод с любой библиотекой JS, которая отрисовывает пользовательский интерфейс. В компоненты JS можно встраивать компоненты из стороннего фреймворка SPA Razor, если они не пытаются изменить другие части страницы. Небезопасно, когда внешний код изменяет элементы, которые JS не считает пустыми.
• При использовании этого подхода необходимо учитывать то, как Blazor удерживает или уничтожает элементы DOM. Компонент безопасно обрабатывает события нажатия кнопки и обновляет существующий экземпляр карты, так как элементы DOM сохраняются по возможности. При отрисовке списка элементов карты из цикла @foreach необходимо использовать @key, чтобы гарантировать сохранность экземпляров компонента. В противном случае изменения в данных списка могут приводить к нежелательному сохранению состояния предыдущих экземпляров компонента. Дополнительные сведения см. в статье об использовании атрибута @key директивы для сохранения связи между элементами, компонентами и объектами модели.
• Пример инкапсулирует JS логику и зависимости в модуле JavaScript и загружает модуль динамически с помощью идентификатора 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 расположению и наши рекомендации для рабочих приложений см. в статье "Расположение JavaScript в приложениях 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);
    }
}

Передача данных из .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} представляет собой информацию Stream, отправленную в JS.
• JS является внедренным экземпляром IJSRuntime.

Удаление экземпляра DotNetStreamReference обычно не требуется. Если leaveOpen задано значение false по умолчанию, базовый объект Stream автоматически удаляется после передачи в JS.

Если leaveOpen является true, то удаление DotNetStreamReference не удаляет его базовый Stream объект. Код приложения определяет, когда нужно удалить базовый Stream объект. При принятии решения о том, как удалить базовый Streamобъект, рассмотрите следующее:

• Удаление Stream во время его передачи в JS считается ошибкой приложения и может привести к возникновению необработанного исключения.
• Stream передача начинается сразу после DotNetStreamReference передачи в виде аргумента для JS вызова interop, независимо от того, используется ли поток в логике JS.

Учитывая эти характеристики, рекомендуется освободить базовый Stream только после полного использования JS (промис, возвращенный arrayBuffer или stream, выполнится). Из этого следует, что DotNetStreamReference должен передаваться в JS только в том случае, если он безусловно будет использоваться логикой JS.

В статье Вызов методов .NET из функций JavaScript в Blazor ASP.NET Core рассматривается обратная операция, потоковая передача данных из JavaScript в .NET.

Статья Загрузки файлов Blazor ASP.NET Core содержит сведения о скачивании файла в Blazor.

Перехват исключений JavaScript

Чтобы перехватить исключения JS, оберните взаимодействие JS в блок 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 в компоненте, чтобы прервать выполнение длительной функции JavaScript из кода на C#.

Следующий класс JSHelpers содержит смоделированную длительную функцию longRunningFn, которая непрерывно будет считать до тех пор, пока AbortController.signal не проинформирует о вызове AbortController.abort. Функция sleep предназначена для демонстрации для имитации медленного выполнения длительной функции. Она не будет присутствовать в рабочем коде. Когда компонент вызывает stopFn, longRunningFn получает сигнал о прерывании через условную проверку цикла while по адресу 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>

Примечание.

Общие рекомендации по JS расположению и наши рекомендации для рабочих приложений см. в статье "Расположение JavaScript в приложениях ASP.NET CoreBlazor".

Приведенный ниже компонент:

• Активирует функцию JSlongRunningFn, когда выбрана кнопка Start Task. CancellationTokenSource используется для управления выполнением длительной функции. CancellationToken.Register задает делегат вызова взаимодействия JS для выполнения функции JSstopFn при отмене CancellationTokenSource.Token.
• Если нажать кнопку Cancel Task, CancellationTokenSource.Token отменяется путем вызова Cancel.
• CancellationTokenSource удаляется в методе Dispose.

CallJs12.razor:

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

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

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

@code {
    private CancellationTokenSource? cts;

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

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

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

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

Консоль средств разработчика в браузере показывает выполнение длительной функции JS после выбора кнопки Start Task и прерывание выполнения функции после выбора кнопки Cancel Task:

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

Взаимодействие JavaScript [JSImport]/[JSExport]

Этот раздел относится к клиентским компонентам.

Как альтернатива взаимодействию с JavaScript (JS) в клиентских компонентах, используя механизм взаимодействия BlazorJS, основанного на интерфейсе IJSRuntime, API взаимодействия JS[JSImport]/[JSExport] доступен для приложений, предназначенных для .NET 7 или более поздних версий.

Дополнительные сведения см. в статье JavaScript JSImport/JSExport interop with ASP.NET Core Blazor.

Демаршалированные вызовы взаимодействия с JavaScript

Этот раздел относится к клиентским компонентам.

Немаршоллированное взаимодействие, используя интерфейс IJSUnmarshalledRuntime, устарело и должно быть заменено взаимодействием JavaScript [JSImport]/[JSExport].

Дополнительные сведения см. в статье JavaScript JSImport/JSExport interop with ASP.NET Core Blazor.

Удаление ссылок на объекты взаимодействия JavaScript

Примеры в статьях взаимодействия JavaScript (JS) демонстрируют типичные шаблоны удаления объектов:

• При вызове JS из .NET, как описано в этой статье, избавляйтесь от любого созданного IJSObjectReference/IJSInProcessObjectReference/JSObjectReference или из JS, чтобы избежать утечки памяти JS.

• При вызове .NET из JS, как описано в Call .NET methods from JavaScript functions in ASP.NET Core Blazor, удалите созданный DotNetObjectReference либо из .NET, либо из JS, чтобы избежать утечки памяти .NET.

JS Ссылки на объекты взаимодействия реализуются как карта, где используется идентификационный ключ на стороне JS вызова взаимодействия, создающего ссылку. Если удаление объекта инициируется как со стороны .NET, так и со стороны JS, Blazor удаляет запись из карты, и объект может подлежать сборке мусора до тех пор, пока на него нет других строгих ссылок.

Как минимум, всегда удалять объекты, созданные на стороне .NET, чтобы избежать утечки управляемой памяти .NET.

Задачи очистки DOM во время удаления компонентов

Дополнительные сведения см. в разделе JS.

Вызовы взаимодействия JavaScript без схемы

Дополнительные сведения см. в разделе JS.

Дополнительные ресурсы

• Вызов методов .NET из функций JavaScript в Blazor ASP.NET Core
• InteropComponent.razor пример (dotnet/AspNetCore ветвь репозитория main GitHub): main ветвь представляет текущую разработку подразделения продукта для следующего выпуска ASP.NET Core. Чтобы выбрать ветвь для другого выпуска (например, release/{VERSION}, где {VERSION} обозначает версию выпуска), используйте раскрывающийся список Переключение ветвей или тегов для выбора ветви. Для ветви, которая больше не существует, используйте вкладку "Теги ", чтобы найти API (например, v7.0.0).
• Blazorпримеры репозитория GitHub (dotnet/blazor-samplesкак скачать)
• Обработка ошибок в приложениях ASP.NET Core (раздел взаимодействия с JavaScript)
• Устранение угроз: функции JavaScript, вызываемые из .NET