Chamar as funções JavaScript dos métodos .NET no ASP.NET Core Blazor

Este artigo explica como invocar as funções JavaScript (JS) a partir do .NET.

Para obter informações sobre como chamar os métodos do .NET a partir do JS, confira Chamar os métodos do .NET a partir das funções JavaScript no Blazor ASP.NET Core.

Invocar funções JS

IJSRuntime é registrado pela estrutura Blazor. Para chamar o JS a partir do .NET, injete a abstração IJSRuntime e chame um dos seguintes métodos:

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

Para os métodos do .NET anteriores que invocam as funções JS:

• O identificador de função (String) é relativo ao escopo global (window). Para chamar window.someScope.someFunction, o identificador é someScope.someFunction. Não é necessário registrar a função antes que seja chamada.
• Passe qualquer número de argumentos serializáveis JSON em Object[] para uma função JS.
• O token de cancelamento (CancellationToken) propaga uma notificação de que as operações devem ser canceladas.
• TimeSpan representa um limite de tempo para uma operação JS.
• O tipo de retorno TValue também deve ser serializável JSON. TValue deve corresponder ao tipo do .NET que melhor mapeia para o tipo JSON retornado.
• Um JS Promise é retornado para métodos InvokeAsync. InvokeAsync cancela quebra de linha do Promise e retorna o valor aguardado pelo Promise.

Para aplicativos Blazor com a pré-renderização habilitada, que é o padrão para aplicativos do lado do servidor, a chamada para JS não é possível durante a pré-renderização. Para obter mais informações, confira a seção Pré-renderização.

O exemplo a seguir é baseado em TextDecoder, um decodificador baseado em JS. O exemplo demonstra como invocar uma função JS de um método do C# que descarrega um requisito do código do desenvolvedor para uma API JS existente. A função JS aceita uma matriz de bytes de um método do C#, decodifica a matriz e retorna o texto para o componente para exibição.

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

Observação

Para obter diretrizes gerais sobre o local JS e nossas recomendações para aplicativos de produção, consulte Localização do JavaScript em aplicativos ASP.NET Core Blazor.

O seguinte componente :

• Invoca a função convertArrayJS com InvokeAsync ao selecionar um botão (Convert Array).
• Depois que a função JS é chamada, a matriz passada é convertida em uma cadeia de caracteres. A cadeia de caracteres é retornada ao componente para exibição (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 restrita aos gestos do usuário

Esta seção se aplica a componentes do lado do servidor.

Algumas APIs JavaScript (JS) do navegador só podem ser executadas no contexto de um gesto do usuário, como usar a Fullscreen API (documentação de MDN). Essas APIs não podem ser chamadas por meio do mecanismo de interoperabilidade JS em componentes do lado do servidor, pois a manipulação de eventos da interface do usuário é executada de forma assíncrona e geralmente não está mais no contexto do gesto do usuário. O aplicativo deve manipular o evento de interface do usuário completamente em JavaScript. Portanto, use onclick em vez do atributo de diretiva Blazor do @onclick.

Invocar funções JavaScript sem ler um valor retornado (InvokeVoidAsync)

Use InvokeVoidAsync quando:

• O .NET não é necessário para ler o resultado de uma chamada JavaScript (JS).
• As funções JS retornam void(0)/void 0 ou indefinido.

Forneça uma função displayTickerAlert1JS. A função é chamada com InvokeVoidAsync e não retorna um valor:

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

Observação

Para obter diretrizes gerais sobre o local JS e nossas recomendações para aplicativos de produção, consulte Localização do JavaScript em aplicativos ASP.NET Core Blazor.

Exemplo de componente (.razor) (InvokeVoidAsync)

TickerChanged chama o método handleTickerChanged1 no componente a seguir.

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

Exemplo de classe (.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 chama o método handleTickerChanged1 no componente a seguir.

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

Invocar funções JavaScript e ler um valor retornado (InvokeAsync)

Use InvokeAsync quando for necessário que o .NET leia o resultado de uma chamada JavaScript (JS).

Forneça uma função displayTickerAlert2JS. O exemplo a seguir retorna uma cadeia de caracteres que será exibida pelo chamador:

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

Observação

Para obter diretrizes gerais sobre o local JS e nossas recomendações para aplicativos de produção, consulte Localização do JavaScript em aplicativos ASP.NET Core Blazor.

Exemplo de componente (.razor) (InvokeAsync)

TickerChanged chama o método handleTickerChanged2 e exibe a cadeia de caracteres retornada no componente a seguir.

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

Exemplo de classe (.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 chama o método handleTickerChanged2 e exibe a cadeia de caracteres retornada no componente a seguir.

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

Cenários de geração de conteúdo dinâmico

Para geração de conteúdo dinâmico com BuildRenderTree, use o atributo [Inject]:

[Inject]
IJSRuntime JS { get; set; }

Pré-renderização

Esta seção se aplica a aplicativos do lado do servidor que pré-renderizam componentes Razor. A pré-renderização é abordada em Pre-renderizar componentes Razor do ASP.NET Core.

Observação

A navegação interna de roteamento interativo em Blazor Web Apps não envolve a solicitação de novo conteúdo de página a partir do servidor. Portanto, a pré-geração não ocorre para solicitações de página internas. Se o aplicativo adotar o roteamento interativo, execute um recarregamento de página inteira para obter exemplos de componente que demonstram o comportamento de pré-geração. Para mais informações, confira Pré-renderizar componentes Razor do ASP.NET Core.

Durante a pré-renderização, não é possível chamar JavaScript (JS). O exemplo a seguir demonstra como usar a interoperabilidade JS como parte da lógica de inicialização de um componente de uma maneira compatível com a pré-renderização.

A seguinte função de scrollElementIntoView:

• Rola para o elemento passado com scrollIntoView.
• Retorna o valor da propriedade top do elemento pelo método getBoundingClientRect.

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

Onde IJSRuntime.InvokeAsync chama a função JS no código do componente, ElementReference é usado somente em OnAfterRenderAsync e não em métodos de ciclo de vida anteriores porque não há nenhum elemento HTML DOM até que o componente seja renderizado.

StateHasChanged (fonte de referência) é chamado para enfileirar a nova renderização do componente com o novo estado obtido da chamada de interoperabilidade JS (para mais informações, confira Renderização do componente Razor do ASP.NET Core). Não é criado um loop infinito, pois StateHasChanged é chamado apenas quando 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();
        }
    }
}

O exemplo anterior polui o cliente com uma função global. Para obter uma abordagem melhor em aplicativos de produção, confira Isolamento de JavaScript em módulos JavaScript.

Interoperabilidade JS síncrona em componentes do lado do cliente

Esta seção se aplica somente a componentes do lado do cliente.

As chamadas de interoperabilidade de JS são assíncronas, independentemente do código chamado ser síncrono ou assíncrono. As chamadas são assíncronas para garantir que os componentes sejam compatíveis nos modos de renderização do lado do servidor e do lado cliente. No servidor, todas as chamadas de interoperabilidade de JS devem ser assíncronas porque são enviadas por uma conexão de rede.

Se tiver certeza de que seu componente só é executado no WebAssembly, você pode optar por fazer chamadas de interoperabilidade de JS síncronas. Isso tem um pouco menos sobrecarga do que fazer chamadas assíncronas e pode resultar em menos ciclos de renderização, pois não há estado intermediário enquanto aguarda resultados.

Para fazer uma chamada síncrona do .NET para o JavaScript em um componente do lado do cliente, converta IJSRuntime em IJSInProcessRuntime para fazer a chamada de interoperabilidade de JS:

@inject IJSRuntime JS

...

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

Ao trabalhar com IJSObjectReference em componentes do lado do cliente do ASP.NET Core 5.0 ou posterior, você pode usar IJSInProcessObjectReference de forma síncrona. IJSInProcessObjectReference implementa IAsyncDisposable/IDisposable e deve ser descartado para coleta de lixo, para evitar uma perda de memória, como demonstra o exemplo a seguir:

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

Localização do JavaScript

Carregue o código JavaScript (JS) usando qualquer uma das abordagens descritas no artigo sobre a localização do JavaScript:

• Carregar um script na marcação de <head> (geralmente, não recomendado)
• Carregar um script na marcação de <body>
• Carregar um script de um arquivo JavaScript externo (.js) agrupado com um componente
• Carregar um script de um arquivo JavaScript externo (.js)
• Injetar um script antes ou após o início de Blazor

Para obter informações sobre como isolar scripts nos módulos JS, confira a seção Isolamento do JavaScript nos módulos do JavaScript.

Aviso

Coloque apenas uma tag <script> em um arquivo de componente (.razor), caso o componente tenha a garantia de adotar a SSR estática (renderização estática do lado do servidor) porque a tag <script> não pode ser atualizada de forma dinâmica.

Isolamento de JavaScript em módulos JavaScript

Blazor habilita o isolamento de JavaScript (JS) em módulos JavaScript padrão (especificação ECMAScript). O carregamento do módulo JavaScript funciona da mesma maneira em Blazor que para outros tipos de aplicativos Web, e você é livre para personalizar como os módulos são definidos em seu aplicativo. Para obter um guia sobre como usar módulos JavaScript, confira Docs da Web do MDN: módulos JavaScript.

O isolamento de JS oferece os seguintes benefícios:

• O JS importado não polui mais o namespace global.
• Os consumidores de uma biblioteca e componentes não precisam importar o JS relacionado.

Há suporte para importação dinâmica com o import() operador com ASP.NET Core e Blazor:

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

No exemplo anterior, o espaço reservado {CONDITION} representa uma verificação condicional para determinar se o módulo deve ser carregado.

Para obter compatibilidade com o navegador, confira Posso usar: módulos JavaScript: importação dinâmica.

Em cenários do lado do servidor, JS as chamadas de interoperabilidade não podem ser emitidas depois Blazorque o circuito do SignalR é desconectado. Sem um circuito durante o descarte de componentes ou em qualquer outro momento em que um circuito não exista, as chamadas de método a seguir falham e registram uma mensagem, informando que o circuito está desconectado como um JSDisconnectedException:

• chamadas de método de interoperabilidade JS
  • IJSRuntime.InvokeAsync
  • JSRuntimeExtensions.InvokeAsync
  • JSRuntimeExtensions.InvokeVoidAsync)
• Dispose/DisposeAsync chama em qualquer IJSObjectReference.

Para evitar o registro em log JSDisconnectedException ou registrar informações personalizadas no lado Blazordo servidor, capture a exceção em uma try-catch instrução.

No seguinte exemplo de descarte de componentes:

• O componente do lado do servidor implementa IAsyncDisposable.
• module é um IJSObjectReference para um JS módulo.
• JSDisconnectedException é capturado e não registrado.
• Opcionalmente, você pode registrar informações personalizadas na instrução catch em qualquer nível de log que preferir. O exemplo a seguir não registra informações personalizadas. O código pressupõe que o desenvolvedor não se importa com quando ou onde os circuitos são desconectados durante o descarte de componentes.

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

Se você precisar limpar seus próprios JS objetos ou executar outro JS código no cliente depois que um circuito for perdido em um aplicativo do lado Blazor do servidor, use o MutationObserver padrão no JS cliente. O MutationObserver padrão permite que você execute JS código quando um elemento é removido do DOM.

Para obter mais informações, consulte os seguintes artigos:

• ASP.NET Interoperabilidade do JavaScript principal Blazor (JS interoperabilidade): inclui um exemplo de código do MutationObserver padrão.
• Tratar erros em aplicativos Blazor do ASP.NET Core: a seção Interoperabilidade do JavaScript discute o tratamento de erros em cenários de interoperabilidade JS.
• Ciclo de vida do componente Razor do ASP.NET Core: a seção Descarte de componentes com IDisposable e IAsyncDisposable descreve como implementar padrões de descarte em componentes Razor.

O módulo a seguir JS exporta uma JS função para mostrar um prompt de janela do navegador. Coloque o código JS a seguir em um arquivo JS externo.

wwwroot/scripts.js:

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

Adicione o módulo JS anterior a um aplicativo ou biblioteca de classes como um ativo Web estático na pasta wwwroot e importe o módulo para o código .NET chamando InvokeAsync na instância IJSRuntime.

IJSRuntime importa o módulo como um IJSObjectReference, que representa uma referência a um objeto JS no código .NET. Use o IJSObjectReference para invocar as funções JS exportadas do módulo.

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

No exemplo anterior:

• Por convenção, o identificador import é um identificador especial usado especificamente para importar um módulo JS.
• Especifique o arquivo JS externo do módulo usando o caminho de ativo Web estático estável: ./{SCRIPT PATH AND FILE NAME (.js)}, onde:
  • O segmento de linha para o diretório atual (./) é necessário para criar o caminho de ativo estático correto para o arquivo JS.
  • O espaço reservado {SCRIPT PATH AND FILE NAME (.js)} é o caminho e o nome do arquivo em wwwroot.
• Descarta o IJSObjectReference para coleta de lixo em IAsyncDisposable.DisposeAsync.

A importação dinâmica de um módulo exige uma solicitação de rede. Portanto, só pode ser realizada de forma assíncrona chamando InvokeAsync.

IJSInProcessObjectReference representa uma referência a um objeto JS, cujas funções podem ser invocadas de forma síncrona em componentes do lado do cliente. Para obter mais informações, confira a seção Interoperabilidade JS síncrona em componentes do lado do cliente .

Observação

Quando o arquivo JS externo é fornecido por uma biblioteca de classes Razor, especifique o arquivo JS do módulo usando o caminho de ativo da Web estático estável: ./_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}:

• O segmento de linha para o diretório atual (./) é necessário para criar o caminho de ativo estático correto para o arquivo JS.
• O espaço reservado {PACKAGE ID} é a ID do pacote da biblioteca. A ID do pacote terá como valor padrão o nome do assembly do projeto, se <PackageId> não for especificado no arquivo de projeto. No exemplo a seguir, o nome do assembly da biblioteca é ComponentLibrary e o arquivo de projeto da biblioteca não especifica <PackageId>.
• O espaço reservado {SCRIPT PATH AND FILE NAME (.js)} é o caminho e o nome do arquivo em wwwroot. No exemplo a seguir, o arquivo JS externo (script.js) é colocado na pasta wwwroot da biblioteca de classes.
• module é uma anulável privada IJSObjectReference da classe de componente (private IJSObjectReference? module;).

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

Para obter mais informações, consulte Consumir componentes Razor do ASP.NET Core de uma RCL (biblioteca de classes) Razor.

Na Blazor documentação, os exemplos usam a .js extensão de arquivo nos arquivos de módulo, não a extensão de arquivo .mjs mais recente (RFC 9239). Nossa documentação continua a usar a .js extensão de arquivo pelos mesmos motivos pelos quais a documentação da Fundação Mozilla continua a usar a .js extensão de arquivo. Para mais informações, consulte Aside — .mjs versus .js (documentação do MDN).

Capturar referências a elementos

Alguns cenários de interoperabilidade do JavaScript (JS) exigem referências a elementos HTML. Por exemplo, uma biblioteca de interface do usuário pode exigir uma referência de elemento para inicialização ou talvez seja necessário chamar APIs semelhantes a comandos em um elemento, como click ou play.

Capture as referências a elementos HTML em um componente usando a seguinte abordagem:

• Adicione um atributo @ref ao elemento HTML.
• Defina um campo do tipo ElementReference cujo nome corresponde ao valor do atributo @ref.

O exemplo a seguir mostra a captura de uma referência ao elemento username <input>:

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

@code {
    private ElementReference username;
}

Aviso

Use apenas uma referência de elemento para modificar o conteúdo de um elemento vazio que não interage com Blazor. Esse cenário é útil quando uma API de terceiros fornece conteúdo para o elemento. Como Blazor não interage com o elemento, não há possibilidade de conflito entre a representação do Blazor do elemento e o DOM.

No exemplo a seguir, é perigoso alterar o conteúdo da lista não ordenada (ul) usando MyList por meio da interoperabilidade JS, pois Blazor interage com o DOM para preencher os itens de lista desse elemento (<li>) no objeto Todos:

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

Há suporte para usar a referência de elemento MyList apenas para ler o conteúdo do DOM ou disparar um evento.

Se a interoperabilidade JS modificar o conteúdo do elemento MyList e Blazor tentar aplicar diferenças ao elemento, as diferenças não corresponderão ao DOM. A modificação do conteúdo da lista por meio da interoperabilidade JS com a referência do elemento MyList não é compatível.

Para obter mais informações, confira Interoperabilidade ASP.NET Core Blazor JavaScript (interoperabilidade JS).

Um ElementReference é passado para o código JS por meio da interoperabilidade JS. O código JS recebe uma instância HTMLElement, que pode ser usada com APIs de DOM normais. Por exemplo, o código a seguir define um método de extensão do .NET (TriggerClickEvent) que permite enviar um clique do mouse para um elemento.

A JS função clickElement cria um evento click no elemento HTML passado (element):

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

Para chamar uma função JS que não retorna um valor, use JSRuntimeExtensions.InvokeVoidAsync. O código a seguir dispara um evento click do lado do cliente chamando a função JS anterior com o ElementReference capturado:

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

Para usar um método de extensão, crie um método de extensão estático que recebe a instância IJSRuntime:

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

O método clickElement é chamado diretamente no objeto . O exemplo a seguir pressupõe que o método TriggerClickEvent esteja disponível no namespace 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);
    }
}

Importante

A variável exampleButton só será preenchida depois que o componente for renderizado. Se um ElementReference não preenchido for passado para o código JS, o código JS receberá um valor de null. Para manipular referências de elemento após a renderização do componente, use os métodos de ciclo de vida do componente OnAfterRenderAsync ou OnAfterRender.

Ao trabalhar com tipos genéricos e retornar um valor, use ValueTask<TResult>:

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

O espaço reservado {JAVASCRIPT FUNCTION} é o identificador da função JS.

GenericMethod é chamado diretamente no objeto com um tipo. O exemplo a seguir pressupõe que o GenericMethod esteja disponível no namespace 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);
    }
}

Elementos de referência entre componentes

Um ElementReference não pode ser passado entre componentes porque:

• A existência da instância só é garantida depois que o componente é renderizado, o que ocorre durante ou após a execução do método OnAfterRender/OnAfterRenderAsync de um componente.
• Um ElementReference é um struct, que não pode ser passado como parâmetro de componente.

Para que um componente pai disponibilize uma referência de elemento para outros componentes, o componente pai pode:

• Permitir que componentes filho registrem retornos de chamada.
• Invocar os retornos de chamada registrados durante o evento OnAfterRender com a referência de elemento passada. Indiretamente, essa abordagem permite que os componentes filho interajam com a referência de elemento do pai.

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

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

Observação

Para obter diretrizes gerais sobre o local JS e nossas recomendações para aplicativos de produção, consulte Localização do JavaScript em aplicativos ASP.NET Core Blazor.

CallJs7.razor (componente pai):

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

No exemplo anterior, o namespace do aplicativo é BlazorSample. Se estiver testando o código localmente, atualize o namespace.

SurveyPrompt.razor (componente filho):

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

No exemplo anterior, o namespace do aplicativo é BlazorSample com componentes compartilhados na pasta Shared. Se estiver testando o código localmente, atualize o namespace.

Proteger chamadas de interoperabilidade do JavaScript

Esta seção só se aplica a componentes do Servidor Interativo, mas componentes do lado do cliente também podem definir tempos limite de interoperabilidade JS se as condições permitirem.

Em aplicativos do lado do servidor com interatividade do servidor, a interoperabilidade do JavaScript (JS) pode falhar devido a erros de rede e deve ser tratada como não confiável. Os aplicativos Blazor usam um tempo limite de um minuto para chamadas de interoperabilidade de JS. Se um aplicativo puder tolerar um tempo limite mais agressivo, defina o tempo limite usando uma das abordagens a seguir.

Defina um tempo limite global no Program.cs com CircuitOptions.JSInteropDefaultCallTimeout:

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

O espaço reservado {TIMEOUT} é um TimeSpan (por exemplo, TimeSpan.FromSeconds(80)).

Defina um tempo limite por invocação no código do componente. O tempo limite especificado substitui o tempo limite global definido por JSInteropDefaultCallTimeout:

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

No exemplo anterior:

• O espaço reservado {TIMEOUT} é um TimeSpan (por exemplo, TimeSpan.FromSeconds(80)).
• O espaço reservado {ID} é o identificador da função a ser invocada. Por exemplo, o valor someScope.someFunction invoca a função window.someScope.someFunction.

Embora uma causa comum de falhas de interoperabilidade JS sejam falhas de rede com componentes do lado do servidor, os tempos limite por invocação podem ser definidos para chamadas de interoperabilidade de JS para componentes do lado do cliente. Embora não exista nenhum Blazorcircuito paraSignalR um componente do lado do cliente, JS as chamadas de interoperabilidade podem falhar por outros motivos que se aplicam.

Para obter mais informações sobre o esgotamento de recursos, consulte as Diretrizes de mitigação de ameaças para a renderização interativa do ASP.NET Core Blazor do lado do servidor.

Evitar referências de objeto circular

Os objetos que contêm referências circulares não podem ser serializados no cliente para:

• Chamadas de método do .NET.
• O método do JavaScript chama a partir do C# quando o tipo de retorno tem referências circulares.

Bibliotecas JavaScript que renderizam a interface do usuário

Às vezes, você pode querer usar bibliotecas JavaScript (JS) que produzem elementos visíveis da interface do usuário no DOM do navegador. À primeira vista, isso pode parecer difícil porque o sistema de comparação do Blazor depende de ter controle sobre a árvore de elementos do DOM e incorre em erros se algum código externo alterar a árvore de DOM e invalidar o mecanismo de aplicação de comparações. Essa não é uma limitação específica do Blazor. O mesmo desafio ocorre com qualquer estrutura de interface do usuário baseada em comparação.

Felizmente, é simples inserir a interface do usuário gerada externamente em uma interface do usuário do componente Razor de forma confiável. A técnica recomendada é fazer com que o código do componente (arquivo .razor) produza um elemento vazio. No que diz respeito ao sistema de comparação do Blazor, o elemento está sempre vazio. Portanto, o renderizador não considera o elemento. Isso faz com que seja seguro preencher o elemento com o conteúdo arbitrário gerenciado externamente.

O exemplo a seguir demonstra o conceito. Na instrução if, quando firstRender é true, interaja com unmanagedElement fora do Blazor usando a interoperabilidade JS. Por exemplo, chame uma biblioteca JS externa para preencher o elemento. Blazor ignora o elemento até que esse componente seja removido. Quando o componente é removido, toda a subárvore de DOM do componente também é removida.

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

Considere o exemplo a seguir que renderiza um mapa interativo usando APIs do Mapbox de software livre.

O módulo JS a seguir é colocado no aplicativo ou disponibilizado em uma biblioteca de classes Razor.

Observação

Para criar o mapa do Mapbox, obtenha um token de acesso na Entrada do Mapbox e forneça-o onde o {ACCESS TOKEN} aparece no código a seguir.

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

Para produzir o estilo correto, adicione a seguinte marca de folha de estilos à página HTML do host.

Adicione o elemento <link> a seguir à marcação do elemento <head> (local do conteúdo <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)
            {
            }
        }
    }
}

O exemplo anterior produz uma interface do usuário de mapa interativo. O usuário:

• Pode arrastar para rolar ou ampliar a página.
• Selecionar botões para ir para locais predefinidos.

No exemplo anterior:

• O <div> com @ref="mapElement" é deixado vazio no que diz respeito ao Blazor. O script mapbox-gl.js pode preencher com segurança o elemento e modificar seu conteúdo. Use essa técnica com qualquer biblioteca JS que renderize a interface do usuário. Você pode inserir componentes de uma estrutura de SPA JS de terceiros dentro dos componentes Razor, desde que eles não tentem acessar e modificar outras partes da página. Não é seguro para o código JS externo modificar elementos que o Blazor não considere vazios.
• Ao usar essa abordagem, tenha em mente as regras sobre como Blazor retém ou destrói elementos de DOM. O componente manipula com segurança os eventos de clique de botão e atualiza a instância de mapa existente, pois os elementos de DOM são mantidos sempre que possível. Se você estava renderizando uma lista de elementos de mapa de dentro de um loop @foreach, convém usar @key para garantir a preservação das instâncias de componente. Caso contrário, as alterações nos dados da lista podem fazer com que as instâncias de componente mantenham o estado das instâncias anteriores de maneira indesejável. Para obter mais informações, consulte como usar o @key atributo de diretiva para preservar a relação entre elementos, componentes e objetos de modelo.
• O exemplo encapsula a lógica JS e as dependências em um módulo JavaScript e carrega o módulo dinamicamente usando o identificador import. Para obter mais informações, confira Isolamento do JavaScript nos módulos JavaScript.

Suporte à matriz de bytes

Blazor dá suporte à interoperabilidade do JavaScript (JS) da matriz de bytes otimizada que evita codificar/decodificar matrizes de bytes em Base64. O exemplo a seguir usa a interoperabilidade do JS para passar uma matriz de bytes para o JavaScript.

Forneça uma função receiveByteArrayJS. A função é chamada com InvokeVoidAsync e não retorna um valor:

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

Observação

Para obter diretrizes gerais sobre o local JS e nossas recomendações para aplicativos de produção, consulte Localização do JavaScript em aplicativos ASP.NET Core Blazor.

CallJs9.razor:

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

<h1>Call JS Example 9</h1>

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

<p>
    @result
</p>

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

@code {
    private string? result;

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

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

Transmitir do .NET para o JavaScript

Blazor dá suporte a streaming de dados diretamente do .NET para JavaScript (JS). Os fluxos são criados usando um DotNetStreamReference.

DotNetStreamReference representa um fluxo do .NET e usa os seguintes parâmetros:

• stream: o fluxo enviado para JS.
• leaveOpen: determina se o fluxo foi deixado aberto após a transmissão. Se um valor não for fornecido, leaveOpen usa false como padrão.

Em JS, use um buffer de matriz ou um fluxo legível para receber os dados:

• Usando um ArrayBuffer:

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

• Usando um ReadableStream:

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

No código C#:

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

No exemplo anterior:

• O espaço reservado {STREAM} representa o Stream enviado para JS.
• JS é uma instância injetada IJSRuntime.

Descartar uma instância DotNetStreamReference geralmente é desnecessário. Quando leaveOpen é definido como o seu valor padrão de false, o Stream subjacente é descartado automaticamente após a transmissão para JS.

Se leaveOpen for true, a eliminação de um DotNetStreamReference não descarta seu Stream subjacente. O código do aplicativo determina quando descartar o Stream subjacente. Ao decidir como descartar o Stream subjacente, considere o seguinte:

• Descartar um Stream enquanto ele está sendo transmitido para JS é considerado um erro de aplicativo e pode causar uma exceção sem tratamento.
• A transmissão Stream começa assim que o argumento DotNetStreamReference é passado como um argumento para uma chamada de interoperabilidade JS, independentemente de o fluxo ser realmente usado na lógica JS.

Dadas essas características, recomendamos descartar o Stream subjacente somente depois que ele for totalmente consumido por JS (a promessa retornada por arrayBuffer ou stream for resolvida). Além disso, um DotNetStreamReference só deve ser passado para JS se ele vai ser incondicionalmente consumido pela lógica JS.

Chamar os métodos do .NET a partir do JavaScript no Blazor do ASP.NET Core abrange a operação inversa, transmitindo do JavaScript para o .NET.

A seção Downloads de arquivos Blazor ASP.NET Core abrange como baixar um arquivo em Blazor.

Capturar exceções do JavaScript

Para capturar exceções JS, encapsule a interoperabilidade JS em um try-catch bloco e capture um JSException.

No exemplo a seguir, a função nonFunctionJS não existe. Quando a função não é encontrada, o JSException fica preso com um Message que indica o seguinte erro:

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

Anular uma função JavaScript de execução prolongada

Use um JSAbortController com um CancellationTokenSource no componente para anular uma função JavaScript de execução prolongada no código C#.

A classe JSHelpers a seguir contém uma função de execução prolongada simulada, longRunningFn, para contar continuamente até que o AbortController.signal indique que AbortController.abort foi chamado. A função sleep é para fins de demonstração para simular a execução lenta da função de execução prolongada e não estaria presente no código de produção. Quando um componente chama stopFn, o longRunningFn é sinalizado para anular por meio da verificação condicional de loop while em 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>

Observação

Para obter diretrizes gerais sobre o local JS e nossas recomendações para aplicativos de produção, consulte Localização do JavaScript em aplicativos ASP.NET Core Blazor.

O seguinte componente :

• Invoca a JS função longRunningFn quando o botão Start Task é selecionado. Um CancellationTokenSource é usado para gerenciar a execução da função de execução prolongada. CancellationToken.Register define um delegado de chamada de interoperabilidade JS para executar a JS função stopFn quando o CancellationTokenSource.Token é cancelado.
• Quando o botão Cancel Task é selecionado, o CancellationTokenSource.Token é cancelado com uma chamada para Cancel.
• O CancellationTokenSource é descartado no método 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();
    }
}

O console das ferramentas de desenvolvedor de um navegador indica a execução da função JS de execução prolongada, após a seleção do botão Start Task e quando a função é anulada após a seleção do botão Cancel Task:

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

Interoperabilidade [JSImport]/[JSExport] JavaScript

Esta seção se aplica a componentes do lado do cliente.

Como alternativa à interação com o JavaScript (JS) em componentes do lado do cliente que usam o mecanismo de interoperabilidade JS de Blazor com base na interface IJSRuntime, uma API de interoperabilidade JS[JSImport]/[JSExport] está disponível para aplicativos direcionados ao .NET 7 ou posterior.

Para obter mais informações, consulte Interoperabilidade de JSImport/JSExport de JavaScript com o ASP.NET Core Blazor.

Interoperabilidade JavaScript com unmarshaling

Esta seção se aplica a componentes do lado do cliente.

A interoperabilidade com unmarshaling usando a interface IJSUnmarshalledRuntime é obsoleta e deve ser substituída pela interoperabilidade [JSImport]/[JSExport] JavaScript.

Para obter mais informações, consulte Interoperabilidade de JSImport/JSExport de JavaScript com o ASP.NET Core Blazor.

Descarte de referências de objeto de interoperabilidade do JavaScript

Os exemplos em todos os artigos de interoperabilidade do JavaScript (JS) demonstram padrões típicos de descarte de objetos:

• Ao chamar o JS a partir do .NET, conforme descrito neste artigo, descarte qualquer IJSObjectReference/IJSInProcessObjectReference/JSObjectReference criado a partir do .NET ou do JS para evitar o vazamento de memória do JS.

• Ao chamar o .NET a partir do JS, conforme descrito em Chamar métodos do .NET a partir das funções JavaScript no Blazor do ASP.NET Core, descarte um DotNetObjectReference criado a partir do .NET ou do JS para evitar perda de memória do .NET.

As referências de objeto de interoperabilidade JS são implementadas como um mapa com chave de um identificador no lado da chamada de interoperabilidade JS que cria a referência. Quando o descarte de objetos é iniciado no .NET ou do lado do JS, Blazor remove a entrada do mapa e o objeto pode ser coletado como lixo, desde que nenhuma outra referência forte ao objeto esteja presente.

No mínimo, sempre descarte objetos criados no lado do .NET para evitar o vazamento de memória gerenciada do .NET.

Tarefas de limpeza do DOM no descarte de componentes

Para obter mais informações, confira Interoperabilidade ASP.NET Core Blazor JavaScript (interoperabilidade JS).

Chamadas de interoperabilidade do JavaScript sem um circuito

Para obter mais informações, confira Interoperabilidade ASP.NET Core Blazor JavaScript (interoperabilidade JS).

Recursos adicionais

• Chamar métodos .NET de funções JavaScript no ASP.NET Core Blazor
• Exemplo InteropComponent.razor (branch main do repositório do GitHub dotnet/AspNetCore): o branch main representa o desenvolvimento atual da unidade de produto para a próxima versão do ASP.NET Core. Para selecionar a ramificação para uma versão diferente (por exemplo, release/{VERSION}, em que o espaço reservado {VERSION} é a versão de lançamento), use a lista suspensa Alternar ramificações ou marcas para selecionar a ramificação. Para uma ramificação que não existe mais, use a guia Tags para localizar a API (por exemplo, v7.0.0).
• Blazor amostras do repositório GitHub (dotnet/blazor-samples) (como baixar)
• Tratar erros em aplicativos Blazor do ASP.NET Core (seção Interoperabilidade do JavaScript)
• Mitigação de ameaças: funções JavaScript invocadas no .NET