Llamada a funciones de JavaScript con métodos de .NET en Blazor de ASP.NET Core

En este artículo se explica cómo invocar funciones de JavaScript (JS) desde .NET.

Para obtener información sobre cómo llamar a métodos de .NET desde JS, consulta Llamada a métodos de .NET desde funciones de JavaScript en ASP.NET Core Blazor.

Invocar funciones JS

El marco Blazor registra IJSRuntime. Para llamar a JS desde .NET, inserta la abstracción IJSRuntime y llama a uno de los métodos siguientes:

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

Para los métodos de .NET anteriores que invocan funciones de JS:

• El identificador de función (String) es relativo al ámbito global (window). Para llamar a window.someScope.someFunction, el identificador es someScope.someFunction. No es necesario registrar la función para poder llamarla.
• Pasa cualquier número de argumentos serializables de JSON en Object[] a una función de JS.
• El token de cancelación (CancellationToken) propaga una notificación de que se deben cancelar las operaciones.
• TimeSpan representa un límite de tiempo para una operación de JS.
• El tipo de valor devuelto TValue también debe ser serializable con JSON. TValue debe coincidir con el tipo de .NET que mejor asignación tenga con el tipo de JSON devuelto.
• Se devuelve un objeto JS Promise para los métodos InvokeAsync. InvokeAsync desencapsula el objeto Promise y devuelve el valor que el objeto Promise espera.

Para aplicaciones Blazor con representación previa activada, que es el valor por defecto para aplicaciones del lado del servidor, llamar a JS no es posible durante la representación previa. Para obtener más información, consulta la sección Representación previa.

El siguiente ejemplo se basa en TextDecoder, un descodificador basado en JS. En el ejemplo se muestra cómo invocar una función de JS desde un método de C# que descarga un requisito del código de desarrollador a una API de JS existente. La función de JS acepta una matriz de bytes procedente de un método de C#, la descodifica y devuelve el texto al componente para que lo muestre.

<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 obtener una guía general sobre la ubicación de JS y nuestras recomendaciones para aplicaciones de producción, consulta Ubicación de JavaScript en aplicaciones Blazor de ASP.NET Core.

El componente siguiente:

• Invoca la función de convertArrayJS con InvokeAsync al seleccionar un botón (Convert Array).
• Después de llamar a la función de JS, la matriz que se ha pasado se convierte en una cadena. Dicha cadena se devuelve al componente para que la muestre (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 de JavaScript restringida a los gestos del usuario

Esta sección se aplica a los componentes del lado del servidor.

Algunas API de JavaScript (JS) del explorador solo se pueden ejecutar en el contexto de un gesto del usuario, como el uso de Fullscreen API (documentación de MDN). Estas API no pueden invocarse a través del mecanismo de interoperabilidad JS en componentes del lado del servidor porque la administración de eventos de interfaz de usuario se realiza de forma asíncrona y, por lo general, ya no en el contexto del gesto del usuario. La aplicación debe controlar completamente el evento de interfaz de usuario en JavaScript, por lo que debe usar onclick en lugar del atributo de directiva @onclickde Blazor.

Invocación de funciones de JavaScript sin leer un valor devuelto (InvokeVoidAsync)

Utiliza InvokeVoidAsync si:

• .NET no es necesario para leer el resultado de una llamada de JavaScript (JS).
• Las funciones de JS devuelven void(0)/void 0 o undefined.

Proporciona una función displayTickerAlert1 de JS. Se llama a la función con InvokeVoidAsync y no se devuelve un valor:

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

Nota:

Para obtener una guía general sobre la ubicación de JS y nuestras recomendaciones para aplicaciones de producción, consulta Ubicación de JavaScript en aplicaciones Blazor de ASP.NET Core.

Ejemplo (InvokeVoidAsync) de componente (.razor)

TickerChanged llama al método handleTickerChanged1 en el siguiente componente.

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

Ejemplo (InvokeVoidAsync) de clase (.cs)

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 llama al método handleTickerChanged1 en el siguiente componente.

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

Invocación de funciones de JavaScript y lectura de un valor devuelto (InvokeAsync)

Usa InvokeAsync cuando .NET debe leer el resultado de una llamada de JavaScript (JS).

Proporciona una función displayTickerAlert2 de JS. En el ejemplo siguiente se devuelve una cadena para que la muestre el llamador:

<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 obtener una guía general sobre la ubicación de JS y nuestras recomendaciones para aplicaciones de producción, consulta Ubicación de JavaScript en aplicaciones Blazor de ASP.NET Core.

Ejemplo (InvokeAsync) de componente (.razor)

TickerChanged llama al método handleTickerChanged2 y muestra la cadena devuelta en el siguiente componente.

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

Ejemplo (InvokeAsync) de clase (.cs)

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 llama al método handleTickerChanged2 y muestra la cadena devuelta en el siguiente componente.

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

Escenarios de generación de contenido dinámico

Para generar contenido dinámico con BuildRenderTree, usa el atributo [Inject]:

[Inject]
IJSRuntime JS { get; set; }

Representación previa

Esta sección se dirige a las aplicaciones del lado servidor que ofrecen una representación previa de los componentes de Razor. La representación previa se describe en Representación previa de componentes Razor de ASP.NET Core.

Nota:

La navegación interna para el enrutamiento interactivo en Blazor Web App no implica solicitar contenido de página nuevo desde el servidor. Por lo tanto, la representación previa no se produce para las solicitudes de página internas. Si la aplicación adopta el enrutamiento interactivo, realiza una recarga de página completa para los ejemplos de componentes que muestran el comportamiento de representación previa. Para obtener más información, consulta Representación previa de componentes Razor de ASP.NET Core .

Durante la representación previa, no es posible llamar a JavaScript (JS). En el ejemplo siguiente se muestra cómo usar la interoperabilidad de JS como parte de la lógica de inicialización de un componente de una manera compatible con la representación previa.

La siguiente función scrollElementIntoView:

• Se desplaza hasta el elemento pasado con scrollIntoView.
• Devuelve el valor de la propiedad top del elemento proporcionado desde el método getBoundingClientRect.

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

Cuando IJSRuntime.InvokeAsync llama a la función JS en el código de componente, ElementReference solo se utiliza en OnAfterRenderAsync y no en ningún otro método de ciclo de vida anterior porque no existe ningún elemento HTML de DOM hasta después de representar el componente.

Se llama a StateHasChanged (origen de referencia) para volver a representar el componente con el nuevo estado obtenido de la llamada de interoperabilidad de JS (consulta Representación de componentes de Razor de ASP.NET Core para obtener más información). No se crea un bucle infinito porque solo se llama a StateHasChanged cuando scrollPosition es 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();
        }
    }
}

En el ejemplo anterior se contamina el cliente con una función global. Para obtener un mejor enfoque en las aplicaciones de producción, consulta Aislamiento de JavaScript en módulos de JavaScript.

JS Interoperabilidad sincrónica en componentes del lado cliente

Esta sección solo se aplica a los componentes del lado cliente.

Las llamadas de interoperabilidad de JS son asincrónicas, independientemente de si el código al que se llama es sincrónico o asincrónico. Las llamadas son asíncronas para garantizar que los componentes sean compatibles entre los modos de representación del lado del servidor y del lado del cliente. En el servidor, todas las llamadas de interoperabilidad de JS deben ser asincrónicas porque se envían a través de una conexión de red.

Si sabes con certeza que la aplicación solo se ejecuta en WebAssembly, puedes optar por realizar llamadas de interoperabilidad de JS sincrónicas. Esto tiene una sobrecarga ligeramente menor que la realización de llamadas asincrónicas y puede dar lugar a menos ciclos de representación porque no hay ningún estado intermedio mientras se esperan los resultados.

Para realizar una llamada sincrónica de .NET a JavaScript en un componente del lado cliente, convierte IJSRuntime en IJSInProcessRuntime para realizar la llamada de interoperabilidad de JS :

@inject IJSRuntime JS

...

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

Al trabajar con componentes del lado del cliente de IJSObjectReferenceASP.NET Core 5.0 o posterior, puedes usarIJSInProcessObjectReference sincrónicamente en su lugar. IJSInProcessObjectReference implementa IAsyncDisposable/IDisposable y debe eliminarse para la recolección de elementos no utilizados para evitar una fuga de memoria, como se muestra en el ejemplo siguiente:

@inject IJSRuntime JS
@implements IAsyncDisposable

...

@code {
    ...
    private IJSInProcessObjectReference? module;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            module = await JS.InvokeAsync<IJSInProcessObjectReference>("import", 
            "./scripts.js");
        }
    }

    ...

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

En el ejemplo anterior, JSDisconnectedException un no está atrapado durante la eliminación del módulo porque no hay ningún BlazorSignalR circuito en una Blazor WebAssembly aplicación para perder. Para obtener más información, consulta Interoperabilidad de JavaScript en ASP.NET Core Blazor (interoperabilidad de JS).

Ubicación de JavaScript

Carga el código de JavaScript (JS) mediante cualquiera de los enfoques descritos en el artículo sobre la ubicación de JavaScript:

• Carga de un script en el marcado <head> (en general, no se recomienda)
• Carga de un script en el marcado <body>
• Carga de un script desde un archivo JavaScript externo (.js) colocado con un componente
• Carga de un script desde un archivo JavaScript externo (.js)
• Inserción de un script antes o después de después del inicio de Blazor

Para obtener información sobre cómo aislar scripts en los módulos JS, consulta la sección Aislamiento de JavaScript en módulos de JavaScript.

Advertencia

Coloca solo una etiqueta <script> en un archivo de componente (.razor) si se garantiza que el componente adoptará la representación estática del lado servidor (SSR estática) porque la etiqueta <script> no se puede actualizar de forma dinámica.

Aislamiento de JavaScript en módulos de JavaScript

Blazor permite el aislamiento de JavaScript (JS) en módulos de JavaScript estándar (especificación de ECMAScript). La carga de módulos de JavaScript funciona de la misma manera en Blazor que en otros tipos de aplicaciones web, y puede personalizar cómo se definen los módulos en su aplicación. Para obtener una guía sobre cómo usar módulos de JavaScript, consulta Documentación web de MDN: módulos de JavaScript.

El aislamiento de JS proporciona las siguientes ventajas:

• El JS importado no contamina el espacio de nombres global.
• No es necesario que los consumidores de una biblioteca y los componentes importen el código de JS relacionado.

La importación dinámica con el operador import() se admite con ASP.NET Core y Blazor:

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

En el ejemplo anterior, el marcador de posición {CONDITION} representa una comprobación condicional para determinar si se debe cargar el módulo.

Para la compatibilidad del explorador, consulta ¿Puedo utilizar: Módulos JavaScript: importación dinámica?

En escenarios del lado servidor, JS las llamadas de interoperabilidad no se pueden emitir después Blazorde desconectar el SignalR circuito. Sin un circuito durante la eliminación de componentes o en cualquier otro momento en que no exista un circuito, se produce un error en las siguientes llamadas de método y se registra un mensaje que indica que el circuito está desconectado como JSDisconnectedException:

• Llamadas de método de interoperabilidad JS
  • IJSRuntime.InvokeAsync
  • JSRuntimeExtensions.InvokeAsync
  • JSRuntimeExtensions.InvokeVoidAsync)
• Dispose/DisposeAsync llama a cualquier IJSObjectReference.

Para evitar el registro JSDisconnectedException o para registrar información personalizada en el lado Blazorservidor , capture la excepción en una try-catch instrucción .

Para el ejemplo de eliminación de componentes siguiente:

• El componente del lado servidor implementa IAsyncDisposable.
• module es para IJSObjectReference un JS módulo.
• JSDisconnectedException se captura y no se registra.
• Opcionalmente, puede registrar información personalizada en la instrucción catch en el nivel de registro que prefiera. En el ejemplo siguiente no se registra información personalizada. El código supone que el desarrollador no le importa cuándo o dónde se desconectan los circuitos durante la eliminación de componentes.

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

Si debe limpiar sus propios JS objetos o ejecutar otro JS código en el cliente después de que se pierda un circuito en una aplicación del lado Blazor servidor, use el MutationObserver patrón en JS en el cliente. El MutationObserver patrón permite ejecutar JS código cuando se quita un elemento del DOM.

Vea los siguientes artículos para más información:

• ASP.NET interoperabilidad de JavaScript core Blazor (JS interoperabilidad): incluye un ejemplo de código del MutationObserver patrón.
• Control de errores en aplicaciones de Blazor de ASP.NET Core: en la sección Interoperabilidad de JavaScript se describe el control de errores en escenarios de interoperabilidad de JS.
• Ciclo de vida de los componentes Razor de ASP.NET Core: en la sección Eliminación de componentes con IDisposable y IAsyncDisposable se describe cómo implementar patrones de eliminación en componentes Razor.

El módulo siguiente JS exporta una JS función para mostrar un símbolo del sistema de ventana del explorador. Coloca el código de JS siguiente en un archivo de JS externo.

wwwroot/scripts.js:

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

Agrega el módulo de JS anterior a una aplicación o biblioteca de clases como un recurso web estático en la carpeta wwwroot y luego importa dicho módulo al código .NET llamando a InvokeAsync en la instancia IJSRuntime.

IJSRuntime importa el módulo como un elemento IJSObjectReference, que es una referencia a un objeto de JS hecha desde código .NET. Usa IJSObjectReference para invocar funciones de JS exportadas desde el 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)
            {
            }
        }
    }
}

En el ejemplo anterior:

• Por convención, el identificador de import es un identificador especial que se usa específicamente para importar un módulo de JS.
• Especifica el archivo JS externo del módulo mediante su ruta de acceso de recurso web estático estable: ./{SCRIPT PATH AND FILE NAME (.js)}, donde:
  • El segmento de trazado del directorio actual (./) es necesario para crear la ruta de recurso estático correcta para el archivo JS.
  • El marcador de posición {SCRIPT PATH AND FILE NAME (.js)} es la ruta de acceso y el nombre de archivo en wwwroot.
• Elimina el elemento IJSObjectReference para la recolección de elementos no utilizados en IAsyncDisposable.DisposeAsync.

La importación dinámica de un módulo requiere una solicitud de red, por lo que solo se puede lograr de forma asincrónica llamando a InvokeAsync.

IJSInProcessObjectReference representa una referencia a un objeto JS cuyas funciones pueden invocarse de forma sincrónica en componentes del lado del cliente. Para obtener más información, consulta la sección Interoperabilidad síncrona JS en componentes del lado del cliente.

Nota:

Cuando una biblioteca de clases de Razor proporciona el archivo externo JS, especifica el archivo JS del módulo mediante su ruta de acceso estática estable del recurso web: ./_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}:

• El segmento de trazado del directorio actual (./) es necesario para crear la ruta de recurso estático correcta para el archivo JS.
• El marcador de posición {PACKAGE ID} es el id. de paquete de la biblioteca. El id. de paquete tiene como valor predeterminado el nombre de ensamblado del proyecto si <PackageId> no se especifica en el archivo del proyecto. En el ejemplo siguiente, el nombre del ensamblado de la biblioteca es ComponentLibrary y el archivo de proyecto de la biblioteca no especifica <PackageId>.
• El marcador de posición {SCRIPT PATH AND FILE NAME (.js)} es la ruta de acceso y el nombre de archivo en wwwroot. En el ejemplo siguiente, el archivo JS externo (script.js) se coloca en la carpeta wwwroot de la biblioteca de clases.
• module es un valor nullable privado IJSObjectReference de la clase de componente (private IJSObjectReference? module;).

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

Para obtener más información, consulta Consumo de componentes Razor de ASP.NET Core a partir de una biblioteca de clases de Razor (RCL).

En la documentación de Blazor, los ejemplos usan la extensión de archivo .js para los archivos de módulo, no la extensión de archivo .mjs más reciente (RFC 9239). Nuestra documentación sigue usando la extensión de archivo .js por los mismos motivos por los que la documentación de Mozilla Foundation sigue usando la extensión de archivo .js. Para obtener más información, consulta Reflexión — .mjs versus .js (documentación MDN).

Captura de referencias a elementos

Algunos escenarios de interoperabilidad de JavaScript (JS) requieren referencias a elementos HTML. Por ejemplo, una biblioteca de interfaz de usuario puede requerir una referencia de elemento para inicializarse, o puede que necesites llamar a API de tipo comando en un elemento, como click o play.

Usa el siguiente método para capturar referencias a elementos HTML en un componente:

• Agrega un atributo @ref al elemento HTML.
• Define un campo de tipo ElementReference cuyo nombre coincida con el valor del atributo @ref.

En el siguiente ejemplo se muestra la captura de una referencia al elemento <input> username:

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

@code {
    private ElementReference username;
}

Advertencia

Usa únicamente una referencia de elemento para mutar el contenido de un elemento vacío que no interactúa con Blazor. Este escenario es útil cuando una API de terceros proporciona contenido al elemento. Dado que Blazor no interactúa con el elemento, no existe ninguna posibilidad de que se produzca un conflicto entre la representación de Blazor del elemento y el DOM.

En el siguiente ejemplo, es peligroso mutar el contenido de la lista desordenada (ul) con MyList mediante JS porque Blazor interactúa con el DOM para rellenar los elementos de lista de este elemento (<li>) del objeto Todos:

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

Se admite el uso de la referencia de elemento MyList para leer simplemente contenido DOM o desencadenar un evento.

Si la interoperabilidad de JSmuta el contenido del elemento MyList y Blazor intenta aplicar diferencias con ese elemento, las diferencias no coincidirán con el DOM. Modificar el contenido de la lista mediante la interoperabilidad de JS con la referencia de elemento MyListno se admite.

Para obtener más información, consulta Interoperabilidad de JavaScript en Blazor de ASP.NET Core (interoperabilidad de JS).

ElementReference se pasa al código de JS por medio de la interoperabilidad de JS. El código de JS recibe una instancia de HTMLElement que puede usar con las API de DOM habituales. Por ejemplo, el siguiente código define un método de extensión de .NET (TriggerClickEvent) que permite enviar un clic del mouse a un elemento.

La función de JSclickElement crea un evento click en el elemento HTML pasado (element):

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

Para llamar a una función de JS que no devuelve un valor, use JSRuntimeExtensions.InvokeVoidAsync. El siguiente código desencadena un evento click de cliente al llamar a la función de JS anterior con el elemento 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 un método de extensión, crea un método de extensión estático que reciba la instancia de IJSRuntime:

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

Se llama al método clickElement directamente en el objeto. En el siguiente ejemplo se da por hecho que el método TriggerClickEvent está disponible en el espacio de nombres 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

La variable exampleButton solo se rellena después de que el componente se represente. Si se pasa un elemento ElementReference sin rellenar al código de JS, el código de JS recibe un valor null. Para manipular referencias de elemento una vez finalizada la representación del componente, usa los métodos de ciclo de vida del componente OnAfterRenderAsync o OnAfterRender.

Cuando se trabaje con tipos genéricos y se devuelva un valor, use ValueTask<TResult>:

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

El marcador de posición {JAVASCRIPT FUNCTION} es el identificador de la función JS.

Se llama al método GenericMethod directamente en el objeto con un tipo. En el siguiente ejemplo se da por hecho que el método GenericMethod está disponible en el espacio de nombres 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);
    }
}

Referencia a elementos en componentes

ElementReference no se puede pasar entre componentes porque:

• Solo se garantiza que la instancia vaya a existir después de que se represente el componente, lo que es durante o después de la ejecución del método OnAfterRender/OnAfterRenderAsync del componente.
• Un ElementReference es un struct, que no se puede pasar como parámetro de componente de .

Para que un componente primario haga que una referencia de elemento esté disponible para otros componentes, el componente primario puede:

• Permitir que los componentes secundarios registren devoluciones de llamada.
• Invoca las devoluciones de llamada registradas durante el evento OnAfterRender con la referencia de elemento que se ha pasado. Este método permite de forma indirecta que los componentes secundarios interactúen con la referencia del elemento primario.

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

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

Nota:

Para obtener una guía general sobre la ubicación de JS y nuestras recomendaciones para aplicaciones de producción, consulta Ubicación de JavaScript en aplicaciones Blazor de ASP.NET Core.

CallJs7.razor (componente primario):

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

En el ejemplo anterior, el espacio de nombres de la aplicación es BlazorSample. Si pruebas el código de forma local, actualiza el espacio de nombres.

SurveyPrompt.razor (componente secundario):

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

En el ejemplo anterior, el espacio de nombres de la aplicación es BlazorSample con componentes compartidos en la carpeta Shared. Si pruebas el código de forma local, actualiza el espacio de nombres.

Protección de las llamadas de interoperabilidad de JavaScript

Esta sección solo se aplica a los componentes del Servidor interactivo., pero los componentes del lado del cliente también pueden establecer tiempos de espera de interoperabilidad JS si las condiciones lo justifican.

En aplicaciones del lado del servidor con interactividad del servidor, la interoperabilidad de JavaScript (JS) puede fallar debido a errores de red y debe tratarse como no fiable. Las aplicaciones Blazor usan un tiempo de espera de un minuto para las llamadas de interoperabilidad de JS. Si una aplicación puede tolerar un tiempo de espera más restrictivo, establécelo recurriendo a uno de los siguientes métodos.

Establece un tiempo de espera global en Program.cs con CircuitOptions.JSInteropDefaultCallTimeout:

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

El marcador de posición {TIMEOUT} es un TimeSpan (por ejemplo, TimeSpan.FromSeconds(80)).

Establece un tiempo de espera por cada invocación en el código de componente. El tiempo de espera especificado invalida el tiempo de espera global establecido por JSInteropDefaultCallTimeout:

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

En el ejemplo anterior:

• El marcador de posición {TIMEOUT} es un TimeSpan (por ejemplo, TimeSpan.FromSeconds(80)).
• El marcador de posición {ID} es el identificador de la función que se va a invocar. Por ejemplo, el valor someScope.someFunction invoca la función window.someScope.someFunction.

Aunque una causa común de fallos de interoperabilidad JS son los fallos de red con componentes del lado del servidor, se pueden establecer tiempos de espera por invocación para llamadas de interoperabilidad JS para componentes del lado del cliente. Aunque no existe ningún BlazorSignalR circuito para un componente del lado cliente, JS las llamadas de interoperabilidad pueden producir errores por otros motivos que se aplican.

Para obtener más información sobre el agotamiento de recursos, consulta la Guía de mitigación de amenazas para Blazor la representación interactiva en el lado del servidor de ASP.NET Core.

Evitar referencias de objetos circulares

Los objetos que contienen referencias circulares no se pueden serializar en el cliente para:

• Llamadas de método .NET.
• Llamadas de método JavaScript desde C# cuando el tipo de valor devuelto tiene referencias circulares.

Bibliotecas de JavaScript que representan la interfaz de usuario

En ocasiones, es posible que quieras usar bibliotecas de JavaScript (JS) que generen elementos de la interfaz de usuario visibles en el DOM del explorador. A primera vista, esto podría parecer difícil porque el sistema de comparación de Blazor se basa en tener control sobre el árbol de elementos DOM y encuentra errores si algún código externo muta el árbol DOM e invalida su mecanismo para aplicar las comparaciones. No se trata de una limitación específica de Blazor. El mismo desafío se produce con cualquier marco de interfaz de usuario basado en comparaciones.

Afortunadamente, es sencillo insertar una interfaz de usuario generada externamente dentro de una interfaz de usuario de componentes de Razor de forma confiable. La técnica recomendada consiste en hacer que el código del componente (archivo .razor) produzca un elemento vacío. En lo que se refiere al sistema de comparación de Blazor, el elemento siempre está vacío, por lo que el representador no recorre en el elemento y no interferirá con sus contenidos. Esto hace que sea seguro rellenar el elemento con contenido arbitrario administrado externamente.

En el siguiente ejemplo se muestra el concepto. Dentro de la instrucción if cuando firstRender es true, interactúe con unmanagedElement fuera de Blazor mediante la interoperabilidad de JS. Por ejemplo, llama a una biblioteca de JS externa para rellenar el elemento. Blazor no hará nada con el contenido del elemento hasta que se quite este componente. Cuando se quite el componente, también se quitará el subárbol DOM completo del componente.

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

Considera el ejemplo siguiente que representa un mapa interactivo mediante las API de código abierto de Mapbox.

El módulo de JS siguiente se coloca en la aplicación o está disponible en una biblioteca de clases de Razor.

Nota

Para crear el mapa de Mapbox, obtén un token de acceso de Inicio de sesión de Mapbox y proporciónalo donde aparece {ACCESS TOKEN} en el código siguiente.

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 generar el estilo correcto, agrega la siguiente etiqueta de hoja de estilos a la página HTML del host.

Agrega el elemento <link> siguiente al marcado del elemento <head> (ubicación del contenido de <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)
            {
            }
        }
    }
}

En el ejemplo anterior se genera una interfaz de usuario de mapa interactiva. El usuario:

• Puedes arrastrar para desplazarte o hacer zoom.
• Puedes hacer clic en los botones para saltar a ubicaciones predefinidas.

En el ejemplo anterior:

• En cuanto a Blazor, <div> con @ref="mapElement" se deja vacío. El script mapbox-gl.js puede rellenar de forma segura el elemento y modificar su contenido. Utiliza esta técnica con cualquier biblioteca de JS que represente la interfaz de usuario. Puedes insertar componentes de un marco de JS SPA de terceros dentro de los componentes de Razor, siempre y cuando no intenten modificar otras partes de la página. No es seguro que el código JS externo modifique los elementos que Blazor no considere vacíos.
• Al utilizar este enfoque, ten en cuenta las reglas sobre cómo Blazor conserva o destruye los elementos DOM. El componente controla de forma segura los eventos de clic de botón y actualiza la instancia de asignación existente, porque los elementos DOM se conservan siempre que sea posible. Si estuvieras representando una lista de elementos de mapa desde dentro de un bucle @foreach, querrías usar @key para garantizar la preservación de las instancias del componente. De lo contrario, los cambios en los datos de la lista podrían hacer que las instancias del componente conservaran el estado de las instancias anteriores de forma no deseada. Para obtener más información, consulta cómo usar el atributo @key de directiva para conservar la relación entre elementos, componentes y objetos de modelo.
• El ejemplo encapsula la lógica de JS y las dependencias dentro de un módulo JavaScript y carga el módulo dinámicamente mediante el identificador import. Para obtener más información, consulta Aislamiento de JavaScript en módulos de JavaScript.

Compatibilidad con matrices de bytes

Blazor admite la interoperabilidad de JavaScript de matriz de bytes optimizada (JS) que evita la codificación o descodificación de matrices de bytes en Base64. En el ejemplo siguiente se usa la interoperabilidad de JS para pasar una matriz de bytes a JavaScript.

Proporciona una función receiveByteArray de JS. Se llama a la función con InvokeVoidAsync y no se devuelve un valor:

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

Nota:

Para obtener una guía general sobre la ubicación de JS y nuestras recomendaciones para aplicaciones de producción, consulta Ubicación de JavaScript en aplicaciones Blazor de ASP.NET Core.

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

Transmisión de .NET a JavaScript

Blazor admite la transmisión de datos directamente desde .NET a JavaScript (JS). Los flujos se crean mediante el objeto DotNetStreamReference.

DotNetStreamReference representa una secuencia de .NET y usa los parámetros siguientes:

• stream: secuencia enviada a JS.
• leaveOpen: determina si la secuencia sigue abierta después de la transmisión. Si no se proporciona un valor, leaveOpen tiene como valor predeterminado false.

En JS, usa un búfer de matriz o una secuencia legible para recibir los datos:

• Mediante un objeto ArrayBuffer:

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

• Mediante un objeto ReadableStream:

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

En código de C#:

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

En el ejemplo anterior:

• El marcador de posición {STREAM} representa el objeto Stream enviado a JS.
• JS es una instancia de IJSRuntime insertada.

La eliminación de una instancia DotNetStreamReference suele ser innecesaria. Cuando leaveOpen se establece en su valor predeterminado de false, el subyacente Stream se elimina automáticamente después de la transmisión a JS.

Si leaveOpen es true, la eliminación de un DotNetStreamReference no elimina su subyacente Stream. El código de la aplicación determina cuándo eliminar el subyacente Stream. Al decidir cómo eliminar el subyacente Stream, tenga en cuenta lo siguiente:

• La eliminación de un Stream mientras que se transmite a JS se considera un error de aplicación y puede provocar que se produzca una excepción no controlada.
• La transmisión Stream comienza tan pronto como DotNetStreamReference se pasa como argumento a una llamada de interoperabilidad JS, independientemente de si la secuencia se usa realmente en la lógica JS.

Dadas estas características, se recomienda eliminar el subyacente Stream solo después de que sea consumido por completo por JS (la promesa devuelta por arrayBuffer o stream soluciones). A continuación se indica que solo se debe pasar un DotNetStreamReference a JS si va a ser consumido incondicionalmente por JS.

En Llamada a métodos de .NET desde funciones de JavaScript en ASP.NET Core Blazor se describe la operación inversa, el streaming de JavaScript a .NET.

En Descargas de archivos Blazor de ASP.NET Core se describe cómo descargar un archivo en Blazor.

Detección de excepciones de JavaScript

Para detectar excepciones JS, encapsula la interoperabilidad de JS en un bloque try-catch y detecta una excepción JSException.

En el siguiente ejemplo, la función nonFunctionJS no existe. Cuando no se encuentra la función, el objeto JSExceptionqueda atrapado con una excepción Message que indica el siguiente error:

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

Anulación de una función de JavaScript de ejecución larga

Usa JSAbortController con CancellationTokenSource en el componente para anular una función de JavaScript de ejecución larga desde código de C#.

La clase JSHelpers siguiente contiene una función simulada de ejecución larga, longRunningFn, que se cuenta continuamente hasta que AbortController.signal indica que se ha llamado a AbortController.abort. La función sleep tiene fines de demostración para simular la ejecución lenta de la función de ejecución larga y no estaría presente en el código de producción. Cuando un componente llama a stopFn, se indica a longRunningFn que se anule a través de la comprobación condicional del bucle while en 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>

Nota:

Para obtener una guía general sobre la ubicación de JS y nuestras recomendaciones para aplicaciones de producción, consulta Ubicación de JavaScript en aplicaciones Blazor de ASP.NET Core.

El componente siguiente:

• Invoca la función JSlongRunningFn cuando se selecciona el botón Start Task. CancellationTokenSource se usa para administrar la ejecución de la función de ejecución larga. CancellationToken.Register establece un delegado de llamada de interoperabilidad JS para ejecutar la función JSstopFn cuando CancellationTokenSource.Token se cancela.
• Cuando se selecciona el botón Cancel Task, CancellationTokenSource.Token se cancela con una llamada a Cancel.
• CancellationTokenSource se elimina en el 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();
    }
}

La consola de herramientas del desarrollador de un explorador indica la ejecución de la función de duración larga JS después de seleccionar el botón Start Task y cuando se anula la función después de seleccionar el botón Cancel Task:

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

Interoperabilidad [JSImport]/[JSExport] de JavaScript

Esta sección se aplica a los componentes del lado cliente.

Como alternativa a la interacción con JavaScript (JS) en los componentes del lado del cliente mediante el mecanismo de interoperabilidad de Blazor's JS basado en la interfaz IJSRuntime, existe una API de interoperabilidad JS[JSImport]/[JSExport] disponible para las aplicaciones orientadas a .NET 7 o posterior.

Para obtener más información, consulta Interoperabilidad JSImport/JSExport de JavaScript con ASP.NET Core Blazor.

Interoperabilidad de JavaScript deserializada

Esta sección se aplica a los componentes del lado cliente.

La interoperabilidad deserializada mediante la interfaz IJSUnmarshalledRuntime está obsoleta y debe reemplazarse por la interoperabilidad [JSImport]/[JSExport] de JavaScript.

Para obtener más información, consulta Interoperabilidad JSImport/JSExport de JavaScript con ASP.NET Core Blazor.

Eliminación de referencias de objetos de interoperabilidad de JavaScript

Los ejemplos de los artículos de interoperabilidad de JavaScript (JS) muestran patrones típicos de eliminación de objetos:

• Al llamar a JS desde .NET, como se describe en este artículo, elimine cualquier IJSObjectReference/IJSInProcessObjectReference/JSObjectReference creado desde .NET o desde JS para evitar fugas de memoria de JS.

• Al llamar a .NET desde JS, como se describe en Llamada a métodos de .NET desde funciones de JavaScript en Blazor de ASP.NET Core, elimine una clase DotNetObjectReference creada desde .NET o desde JS para evitar la fuga de memoria de .NET.

Las referencias de objeto de interoperabilidad JS se implementan como un mapa con clave por un identificador en el lado de la llamada de interoperabilidad JS que crea la referencia. Cuando se inicia la eliminación de objetos desde el lado de .NET o JS, Blazor quita la entrada del mapa y el objeto se puede recopilar como elemento no utilizado siempre que no haya ninguna otra referencia sólida al objeto presente.

Como mínimo, elimina siempre los objetos creados en .NET para evitar la pérdida de memoria administrada de .NET.

Tareas de limpieza del DOM durante la eliminación de componentes

Para más información, consulta Interoperabilidad de JavaScript en Blazor de ASP.NET Core (interoperabilidad de JS).

Llamadas de interoperabilidad de JavaScript sin un circuito

Para obtener más información, consulta Interoperabilidad de JavaScript en ASP.NET Core Blazor (interoperabilidad de JS).

Recursos adicionales

• Llamada a métodos de .NET desde funciones de JavaScript en ASP.NET Core Blazor
• Ejemplo de InteropComponent.razor (rama main del repositorio de GitHub dotnet/AspNetCore): la rama main representa el desarrollo actual de la unidad de producto para la próxima versión de ASP.NET Core. Para seleccionar la rama para una versión diferente (por ejemplo, release/{VERSION}, donde el marcador de posición es la {VERSION} versión de lanzamiento), use la lista desplegable Cambiar ramas o etiquetas para seleccionar la rama. Para una rama que ya no existe, use la pestaña Etiquetas para buscar la API (por ejemplo, v7.0.0).
• Repositorio de GitHub con ejemplos Blazor (dotnet/blazor-samples) (cómo descargar)
• Administración de errores en aplicaciones ASP.NET Core Blazor(sección de interoperabilidad de JavaScript)
• Mitigación de amenazas: Funciones JavaScript invocadas desde .NET