Chamar funções JavaScript a partir de métodos .NET no ASP.NET Core Blazor

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

Para obter informações sobre como chamar métodos .NET a partir de JS, consulte chamar métodos .NET de funções JavaScript no ASP.NET Core Blazor.

Invocar funções JS

IJSRuntime está registado pelo framework Blazor. Para chamar JS do .NET, injete a abstração IJSRuntime e chame um dos seguintes métodos:

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

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

• O identificador de função (String) é relativo ao âmbito global (window). Para chamar window.someScope.someFunction, o identificador é someScope.someFunction. Não há necessidade de registar a função antes de ser chamada.
• Passe qualquer número de argumentos serializáveis por 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 em JSON. TValue deve corresponder ao tipo .NET que melhor corresponde ao tipo JSON devolvido.
• Um JS Promise é retornado para InvokeAsync métodos. InvokeAsync desembrulha o Promise e devolve o valor aguardado pelo Promise.

Para aplicativos Blazor com 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, consulte a seção de 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 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 C#, decodifica a matriz e retorna o texto ao componente para exibição.

HTML

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

Nota

Para obter orientações gerais sobre JS local e nossas recomendações para aplicativos de produção, consulte localização JavaScript em ASP.NET aplicativos 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:

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 a gestos do usuário

Esta seção se aplica aos 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 o Fullscreen API (documentação MDN). Essas APIs não podem ser chamadas por meio do mecanismo de interoperabilidade JS em componentes do lado do servidor porque a manipulação de eventos da interface do usuário é executada de forma assíncrona e, geralmente, não mais no contexto do gesto do usuário. O aplicativo deve manipular o evento da interface do usuário completamente em JavaScript, portanto, use onclick em vez do atributo de diretiva Blazor do @onclick.

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

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

HTML

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

Nota

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

Componente (.razor) exemplo (InvokeVoidAsync)

TickerChanged chama o método handleTickerChanged1 no componente seguinte.

CallJs2.razor:

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:

C#

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

CallJs3.razor:

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

Invoque funções JavaScript e leia um valor retornado (InvokeAsync)

Use InvokeAsync quando o .NET deve ler o resultado de uma chamada JavaScript (JS).

Forneça uma função displayTickerAlert2JS. O exemplo a seguir retorna uma cadeia de caracteres para exibição pelo chamador:

HTML

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

Nota

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

Componente (.razor) exemplo (InvokeAsync)

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

CallJs4.razor:

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:

C#

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:

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

razor

[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 componentes de Prerender do ASP.NET Core Razor.

Nota

A navegação interna em para roteamento interativo no Blazor Web Apps não envolve a solicitação de novo conteúdo de página ao servidor. Portanto, a pré-renderização não ocorre para solicitações de página internas. Se o aplicativo adotar roteamento interativo, execute uma recarga de página inteira para exemplos de componentes que demonstrem o comportamento de pré-renderização. Para obter mais informações, consulte Pré-renderização de componentes do ASP.NET Core Razor.

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

A seguinte função scrollElementIntoView:

• Desloca para o elemento especificado com scrollIntoView.
• Retorna o valor da propriedade top do elemento do método getBoundingClientRect.

JavaScript

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

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

StateHasChanged (fonte de referência) é chamada para enfileirar a rerenderização do componente com o novo estado obtido da chamada de interoperabilidade JS (para obter mais informações, consulte ASP.NET Core Razor de renderização do componente). Um loop infinito não é criado porque StateHasChanged só é chamado quando scrollPosition é null.

PrerenderedInterop.razor:

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 uma melhor abordagem para aplicações em produção, consulte isolamento de JavaScript em módulos de JavaScript.

Interoperabilidade JS síncrona em componentes do lado do cliente

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

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

Se tiveres a certeza de que o teu componente só funciona em WebAssembly, podes optar por realizar chamadas de interoperabilidade JS síncronas. Isso tem um pouco menos de sobrecarga do que fazer chamadas assíncronas e pode resultar em menos ciclos de renderização porque não há nenhum estado intermediário enquanto aguarda resultados.

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

razor

@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, pode utilizar IJSInProcessObjectReference de forma síncrona. IJSInProcessObjectReference implementa IAsyncDisposable/IDisposable e deve ser descartado para coleta de lixo para evitar um vazamento de memória, como demonstra o exemplo a seguir:

razor

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

No exemplo anterior, um JSDisconnectedException não fica preso durante o descarte do módulo porque não há um circuito Blazor-SignalR em uma aplicação Blazor WebAssembly para perder. Para obter mais informações, consulte ASP.NET Interoperabilidade do Core Blazor JavaScript (JS interoperabilidade).

Localização em JavaScript

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

• Carregar um script na marcação <head> (Geralmente não recomendado)
• Carregar um script em <body> marcação
• Carregar um script a partir de um ficheiro JavaScript externo (.js) colocado com um componente
• Carregar um script a partir de um ficheiro JavaScript externo (.js)
• Injete um script antes ou depois de Blazor começar

Para obter informações sobre como isolar scripts nos módulos JS, consulte a seção de isolamento de JavaScript em módulos de JavaScript.

Aviso

Coloque apenas uma tag <script> em um arquivo de componente (.razor) se o componente tiver a garantia de adotar renderização estática do lado do servidor (SSR estático) porque a tag <script> não pode ser atualizada dinamicamente.

Isolamento de JavaScript em módulos JavaScript

Blazor permite o isolamento de JavaScript (JS) em módulos JavaScript padrão (especificação ECMAScript). O carregamento de módulos JavaScript funciona da mesma forma no Blazor que em 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, consulte MDN Web Docs: JavaScript modules.

JS isolamento oferece os seguintes benefícios:

• Os JS importados não poluem mais o namespace global.
• Os consumidores de uma biblioteca e componentes não são obrigados a importar os JSrelacionados .

Importação dinâmica com o operador import() é suportada com ASP.NET Core e Blazor:

JavaScript

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 informações sobre a compatibilidade do navegador, consulte Posso usar: módulos JavaScript: importação dinâmica.

Em cenários no lado do servidor, chamadas de interoperação JS não podem ser emitidas depois que o circuito Blazor do SignalRé desconectado. Sem um circuito durante o descartamento de componentes ou em qualquer outro momento em que não exista um circuito, as chamadas de método a seguir falham e registam uma mensagem indicando que o circuito está desconectado como JSDisconnectedException:

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

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

Para o seguinte exemplo de eliminação de componentes:

• O componente do lado do servidor implementa IAsyncDisposable.
• module é um IJSObjectReference para um módulo JS.
• JSDisconnectedException é capturado e não é registado em log.
• 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 a eliminação do componente.

C#

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

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

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

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

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

wwwroot/scripts.js:

JavaScript

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

Adicione o módulo JS antecedente a uma aplicação ou biblioteca de classes como um ativo web estático na pasta wwwroot e, em seguida, importe o módulo para o código .NET ao chamar InvokeAsync na instância IJSRuntime.

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

CallJs6.razor:

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 ficheiro externo JS do módulo, utilizando o seu caminho estático de recurso web estável: ./{SCRIPT PATH AND FILE NAME (.js)}, onde:
  • O segmento de caminho para o diretório atual (./) é necessário para criar o caminho de recurso 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.
• Elimina o IJSObjectReference para de recolha de lixo em IAsyncDisposable.DisposeAsync.
• Não coloque uma tag de <script> para o script após o script Blazor porque o módulo é carregado e armazenado em cache automaticamente quando o dinâmico import() é invocado.

A importação dinâmica de um módulo requer uma solicitação de rede, portanto, ela só pode ser obtida 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, consulte a seção interoperabilidade síncrona de em componentes do lado do cliente.

Nota

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

• O segmento de caminho para o diretório atual (./) é necessário para criar o caminho de recurso estático correto para o arquivo JS.
• O substituto {PACKAGE ID} é o ID de pacote da biblioteca. O ID do pacote assume como padrão o nome do assembly do projeto se <PackageId> não for especificado no arquivo do 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 é um IJSObjectReference privado anulável da classe de componente (private IJSObjectReference? module;).

C#

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

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

Em toda a documentação do Blazor, os exemplos usam a extensão de ficheiro .js para arquivos de módulo, em vez da extensão de ficheiro mais recente .mjs (RFC 9239). Nossa documentação continua a usar a extensão de arquivo .js pelas mesmas razões que a documentação da Fundação Mozilla continua a usar a extensão de arquivo .js. Para obter mais informações, consulte Aside — .mjs versus .js (documentação do MDN).

Capturar referências a elementos

Alguns cenários de interoperabilidade JavaScript (JS) requerem 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 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 corresponda ao valor do atributo @ref.

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

razor

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

@code {
    private ElementReference username;
}

Aviso

Use apenas uma referência de elemento para mutar o conteúdo de um elemento vazio que não interaja 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 elemento por Blazore o DOM.

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

razor

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

Há suporte para o uso da referência do elemento MyList para apenas ler o conteúdo do DOM ou acionar um evento.

Se JS interoperabilidade mutar o conteúdo do elemento MyList e Blazor tentativas de aplicar diffs ao elemento, os diffs não corresponderão ao DOM. A modificação do conteúdo da lista por meio de interoperabilidade JS com a referência do elemento MyListnão é suportada.

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

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

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

JavaScript

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

razor

@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 receba a instância IJSRuntime:

C#

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:

razor

@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ó é preenchida depois que o componente é renderizado. Se um ElementReference não preenchido for passado ao código JS, o código JS receberá um valor de null. Para manipular referências de elementos após a finalização da 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>:

C#

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

O marcador de posição {JAVASCRIPT FUNCTION} é o identificador da função JS.

GenericMethod é chamado diretamente sobre o objeto com um tipo. O exemplo a seguir pressupõe que o GenericMethod esteja disponível no namespace JsInteropClasses:

razor

@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

Uma ElementReference não pode ser passada entre componentes porque:

• A instância só tem garantia de existir depois que o componente é renderizado, ou seja, durante ou depois que o método OnAfterRender/OnAfterRenderAsync de um componente é executado.
• Um ElementReference é um struct, que não pode ser passado como um 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.
• Invoque os callbacks registados 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.

HTML

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

HTML

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

Nota

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

CallJs7.razor (componente pai):

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:

C#

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

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:

C#

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.

Proteja as chamadas de interoperabilidade JavaScript

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

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

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

C#

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:

C#

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

No exemplo anterior:

• O espaço reservado {TIMEOUT} é um TimeSpan (por exemplo, TimeSpan.FromSeconds(80)).
• O marcador {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 JS para componentes do lado do cliente. Embora não exista um circuito Blazor-SignalR para um componente do lado do cliente, as chamadas de interoperabilidade JS podem falhar por outras razões que possam ser aplicáveis.

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

Evitar referências a objetos circulares

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

• Chamadas de método .NET.
• Quando chamadas de métodos JavaScript são feitas a partir de C#, e o tipo de retorno tem referências circulares.

Bibliotecas JavaScript que processam a interface do usuário

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

Felizmente, é simples incorporar a interface do usuário gerada externamente em uma interface do usuário de 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 diferenciação de Blazor, o elemento está sempre vazio, de modo que o renderizador não entra no elemento e deixa o seu conteúdo inalterado. Isso torna seguro preencher o elemento com conteúdo arbitrário gerenciado externamente.

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

razor

<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 Mapbox de código aberto.

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

Nota

Para criar o mapa Mapbox, obtenha um token de acesso em Mapbox Inicie sessão e forneça-o onde {ACCESS TOKEN} está no código seguinte.

wwwroot/mapComponent.js:

JavaScript

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 estilo à página HTML hospedeira.

Adicione o seguinte elemento <link> à marcação do elemento <head> (local do conteúdo <head>):

HTML

<link href="https://api.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.css" 
    rel="stylesheet" />

CallJs8.razor:

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 interativa de mapa. O utilizador:

• Pode arrastar para rolar ou ampliar.
• Selecione botões para ir para locais predefinidos.

No exemplo anterior:

• O <div> com @ref="mapElement" é deixado vazio no que diz respeito a 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 de JS que renderize a interface do usuário. Você pode incorporar componentes de uma estrutura de SPA de terceiros JS dentro de componentes Razor, desde que eles não tentem acessar ou modificar outras partes da página. Não é seguro para o código JS externo modificar elementos que Blazor não considera vazios.
• Ao usar essa abordagem, tenha em mente as regras sobre como Blazor retém ou destrói elementos DOM. O componente manipula com segurança eventos de clique de botão e atualiza a instância de mapa existente porque os elementos DOM são retidos sempre que possível. Se estiver a renderizar uma lista de elementos de mapa dentro de um loop de @foreach, deve usar @key para garantir a preservação das instâncias dos componentes. Caso contrário, as alterações nos dados da lista podem fazer com que as instâncias de componentes mantenham o estado das instâncias anteriores de maneira indesejável. Para obter mais informações, consulte como usar o atributo de diretiva @key para preservar a relação entre elementos, componentes e objetos de modelo.
• O exemplo encapsula JS lógica e dependências dentro de um módulo JavaScript e carrega o módulo dinamicamente usando o identificador import. Para obter mais informações, consulte isolamento de JavaScript em módulos JavaScript.

Suporte a matriz de bytes

Blazor suporta interoperabilidade JavaScript (JS) de matriz de bytes otimizada que evita codificação/decodificação de matrizes de bytes em Base64. O exemplo a seguir usa JS interop para passar um array de bytes para JavaScript.

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

HTML

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

Nota

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

CallJs9.razor:

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

Transmissão do .NET para o JavaScript

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

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

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

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

• Usando um ArrayBuffer:

  JavaScript

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

• Usando um ReadableStream:

  JavaScript

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

No código C#:

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 IJSRuntime injetada.

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

Se leaveOpen é true, então descartar um DotNetStreamReference não descarta a sua Streamsubjacente. O código do aplicativo determina quando descartar o Streamsubjacente. Ao decidir como eliminar os Streamsubjacentes, considere o seguinte:

• Eliminar 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 DotNetStreamReference é passado como argumento para uma chamada de interoperação JS, sem importar se o fluxo é realmente usado na lógica JS.

Dadas essas características, recomendamos descartar o Stream subjacente somente depois de ser totalmente consumido por JS (ou seja, quando a promessa retornada por arrayBuffer ou stream for resolvida). Conclui-se que um DotNetStreamReference só deve ser passado para JS se for consumido de forma incondicional pela lógica de JS.

Chamar métodos .NET a partir de funções JavaScript no ASP.NET Core Blazor aborda a operação inversa, transmissão de JavaScript para .NET.

Blazor aborda downloads de arquivos e descreve como baixar um arquivo no Blazor.

Capturar exceções de JavaScript

Para capturar exceções JS, envolva a interoperabilidade JS em um bloco try-catch 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 uma Message que indica o seguinte erro:

Could not find 'nonFunction' ('nonFunction' was undefined).

CallJs11.razor:

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

Interromper uma função JavaScript de longa duração

Use um JSAbortController com um CancellationTokenSource no componente para abortar uma função JavaScript de longa execução a partir do código C#.

A classe JSHelpers a seguir contém uma função de longa execução 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 longa execução e não estaria presente no código de produção. Quando um componente chama stopFn, o longRunningFn é sinalizado para abortar através da verificação condicional do loop de while em AbortSignal.aborted.

HTML

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

Nota

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

O seguinte componente:

• Invoca a função JSlongRunningFn quando o botão Start Task é selecionado. Um CancellationTokenSource é usado para gerir a execução da função de execução prolongada. CancellationToken.Register define um JS delegado de chamada de interoperabilidade para executar a função JSstopFn quando o CancellationTokenSource.Token é cancelado.
• Quando o botão Cancel Task é selecionado, o CancellationTokenSource.Token é cancelado com uma chamada para Cancel.
• O CancellationTokenSource é eliminado no método Dispose.

CallJs12.razor:

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 desenvolvimento de um navegador indica a execução da função de longa duração JS após o botão Start Task ser selecionado e quando a função é abortada após o botão Cancel Task ser selecionado.

Console

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

Interoperabilidade JavaScript [JSImport]/[JSExport]

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

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

Para obter mais informações, consulte JavaScript, interoperabilidade deJSImport/JSExport com ASP.NET Core Blazor.

Interoperabilidade JavaScript sem processamento

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

A interoperabilidade não organizada usando a interface IJSUnmarshalledRuntime é obsoleta e deve ser substituída por interoperabilidade JavaScript [JSImport]/[JSExport].

Para obter mais informações, consulte JavaScript, interoperabilidade deJSImport/JSExport com ASP.NET Core Blazor.

Eliminação de referências de interoperabilidade de objetos JavaScript

Exemplos em todos os artigos de interoperabilidade JavaScript (JS) demonstram padrões típicos de eliminação de objetos:

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

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

JS referências de objeto de interoperabilidade são implementadas como um mapa chaveado por um identificador no lado da chamada de interoperabilidade que cria a referência de JS. Quando o descarte do objeto é iniciado a partir do lado .NET ou JS, o Blazor remove a entrada do mapa e o objeto pode ser coletado como lixo, contanto que não haja nenhuma outra referência forte ao objeto presente.

No mínimo, sempre descarte objetos criados no lado do .NET para evitar fugas de memória gerida pelo .NET.

Tarefas de limpeza do DOM durante o descarte de componentes

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

Chamadas de interoperabilidade JavaScript sem um circuito

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

Recursos adicionais

• Chamar métodos .NET a partir de funções JavaScript no ASP.NET Core Blazor
• InteropComponent.razor exemplo (dotnet/AspNetCore repositório GitHub main ramificação): A ramificação 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}, onde o espaço reservado {VERSION} é a versão de versão), use a lista suspensa Alternar ramificações ou tags 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 exemplos de repositório GitHub (dotnet/blazor-samples) (como fazer o download)
• Manipular erros no de aplicativos ASP.NET Core (seção de interoperabilidadeJavaScript)
• Mitigação de ameaças: funções JavaScript invocadas a partir do .NET