Appeler des fonctions JavaScript à partir de méthodes .NET dans ASP.NET Core Blazor

Cet article explique comment appeler des fonctions JavaScript (JS) à partir de .NET.

Pour plus d’informations sur l’appel de méthodes .NET à partir de JS, consultez Appeler des méthodes .NET à partir de fonctions JavaScript dans ASP.NET Core Blazor.

Invoquer les fonctions JS

IJSRuntime est inscrit par le framework Blazor. Pour appeler JS à partir de .NET, injectez l’abstraction IJSRuntime et appelez l’une des méthodes suivantes :

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

Pour les méthodes .NET précédentes qui appellent des fonctions JS :

• L’identificateur de fonction (String) est relatif à l’étendue globale (window). Pour appeler window.someScope.someFunction, l’identificateur est someScope.someFunction. Il n’est pas nécessaire d’inscrire la fonction avant de l’appeler.
• Transmettez n’importe quel nombre d’arguments sérialisables JSON dans Object[] à une fonction JS.
• Le jeton d’annulation (CancellationToken) propage une notification indiquant que les opérations doivent être annulées.
• TimeSpan représente une limite de temps pour une opération JS.
• Le type de retour TValue doit également être sérialisable JSON. TValue doit correspondre au type .NET qui correspond le mieux au type JSON retourné.
• Un JS Promise est retournée pour les méthodes InvokeAsync. InvokeAsync désenveloppe le Promise et retourne la valeur attendue par le Promise.

Pour les applications Blazor avec le prérendu activé, qui est le comportement par défaut pour les applications côté serveur, l’appel à JS n’est pas possible lors du prérendu. Pour plus d’informations, consultez la section Prérendu.

L’exemple suivant est basé sur TextDecoder, un décodeur basé sur JS. L’exemple montre comment appeler une fonction JS à partir d’une méthode C# qui décharge une exigence du code du développeur vers une API JS existante. La fonction JS accepte un tableau d’octets à partir d’une méthode C#, décode le tableau et retourne le texte au composant à afficher.

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

Remarque

Pour obtenir une aide générale sur l’emplacement deJS et nos recommandations pour les applications de production, consultez Emplacement de JavaScript dans les applications Blazor ASP.NET Core.

Le composant suivant :

• Appelle la fonction convertArrayJS avec InvokeAsync lors de la sélection d’un bouton (Convert Array).
• Une fois la fonction JS appelée, le tableau passé est converti en chaîne. La chaîne est retournée au composant pour l’affichage (text).

CallJs1.razor:

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

<PageTitle>Call JS 1</PageTitle>

<h1>Call JS Example 1</h1>

<p>
    <button @onclick="ConvertArray">Convert Array</button>
</p>

<p>
    @text
</p>

<p>
    Quote ©2005 <a href="https://www.uphe.com">Universal Pictures</a>: 
    <a href="https://www.uphe.com/movies/serenity-2005">Serenity</a><br>
    <a href="https://www.imdb.com/name/nm0472710/">David Krumholtz on IMDB</a>
</p>

@code {
    private MarkupString text;

    private uint[] quoteArray = 
        new uint[]
        {
            60, 101, 109, 62, 67, 97, 110, 39, 116, 32, 115, 116, 111, 112, 32,
            116, 104, 101, 32, 115, 105, 103, 110, 97, 108, 44, 32, 77, 97,
            108, 46, 60, 47, 101, 109, 62, 32, 45, 32, 77, 114, 46, 32, 85, 110,
            105, 118, 101, 114, 115, 101, 10, 10,
        };

    private async Task ConvertArray()
    {
        text = new(await JS.InvokeAsync<string>("convertArray", quoteArray));
    }
}

API JavaScript limitée aux mouvements de l’utilisateur

Cette section s’applique aux composants côté serveur.

Certaines API JavaScript (JS) du navigateur ne peuvent être exécutées que dans le contexte d’un mouvement utilisateur, par exemple à l’aide de Fullscreen API (documentation MDN). Ces API ne peuvent pas être appelées par le biais du mécanisme d’interopérabilité JS dans les composants côté serveur, car la gestion des événements d’interface utilisateur est effectuée de manière asynchrone et généralement hors du contexte du mouvement utilisateur. L’application doit gérer complètement l’événement d’interface utilisateur en JavaScript. Utilisez donc onclick au lieu de l’attribut de directive @onclick de Blazor.

Appeler des fonctions JavaScript sans lire une valeur retournée (InvokeVoidAsync)

Utilisez InvokeVoidAsync quand :

• .NET n’est pas nécessaire pour lire le résultat d’un appel JavaScript (JS).
• Les fonctions JS retournent void(0)/void 0 ou undefined.

Fournissez une fonction displayTickerAlert1JS. La fonction est appelée avec InvokeVoidAsync et ne retourne pas de valeur :

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

Remarque

Pour obtenir une aide générale sur l’emplacement deJS et nos recommandations pour les applications de production, consultez Emplacement de JavaScript dans les applications Blazor ASP.NET Core.

Exemple (InvokeVoidAsync) de composant (.razor)

TickerChanged appelle la méthode handleTickerChanged1 dans le composant suivant.

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

Exemple (InvokeVoidAsync) de classe (.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);
    }

    public void Dispose()
    {
        // The following prevents derived types that introduce a
        // finalizer from needing to re-implement IDisposable.
        GC.SuppressFinalize(this);
    }
}

TickerChanged appelle la méthode handleTickerChanged1 dans le composant suivant.

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

Appeler des fonctions JavaScript et lire une valeur retournée (InvokeAsync)

Utilisez InvokeAsync quand .NET doit lire le résultat d’un appel JavaScript (JS).

Fournissez une fonction displayTickerAlert2JS. L’exemple suivant retourne une chaîne pour l’affichage par l’appelant :

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

Remarque

Pour obtenir une aide générale sur l’emplacement deJS et nos recommandations pour les applications de production, consultez Emplacement de JavaScript dans les applications Blazor ASP.NET Core.

Exemple (InvokeAsync) de composant (.razor)

TickerChanged appelle la méthode handleTickerChanged2 et affiche la chaîne retournée dans le composant suivant.

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

Exemple (InvokeAsync) de classe (.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)
    {
        return await js.InvokeAsync<string>("displayTickerAlert2", symbol, price);
    }

    public void Dispose()
    {
        // The following prevents derived types that introduce a
        // finalizer from needing to re-implement IDisposable.
        GC.SuppressFinalize(this);
    }
}

TickerChanged appelle la méthode handleTickerChanged2 et affiche la chaîne retournée dans le composant suivant.

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

Scénarios de génération de contenu dynamique

Pour la génération de contenu dynamique avec BuildRenderTree, utilisez l’attribut [Inject] :

[Inject]
IJSRuntime JS { get; set; }

Prérendu

Cette section s’applique aux applications côté serveur et hébergées qui effectuent un pré-rendu des composants Razor. Le prérendu est couvert dans Prérendu des composants ASP.NET Core Razor.

Remarque

La navigation interne pour le routage interactif dans les applications web Blazor n’implique pas de demander le nouveau contenu de la page auprès du serveur. Par conséquent, un prérendu n’est pas effectué pour les demandes de pages internes. Si l’application adopte le routage interactif, effectuez un rechargement de la page complète pour les exemples de composants qui illustrent le comportement de prérendu. Pour plus d’informations, consultez Prévisualiser les composants ASP.NET Core Razor.

Lorsqu’une application est en cours de prérendu, certaines actions, comme l’appel à JavaScript (JS), ne sont pas possibles.

Dans l’exemple suivant, la fonction setElementText1 est appelée avec JSRuntimeExtensions.InvokeVoidAsync et ne retourne pas de valeur.

Remarque

Pour obtenir une aide générale sur l’emplacement deJS et nos recommandations pour les applications de production, consultez Emplacement de JavaScript dans les applications Blazor ASP.NET Core.

<script>
  window.setElementText1 = (element, text) => element.innerText = text;
</script>

Avertissement

L’exemple précédent modifie le modèle DOM directement à des fins de démonstration uniquement. La modification directe du DOM avec JS n’est pas recommandée dans la plupart des scénarios, car JS peut interférer avec le suivi des modifications de Blazor. Pour plus d’informations, consultez Interopérabilité JavaScript et ASP.NET Core Blazor (interopérabilité JS).

L’événement de cycle de vie OnAfterRender{Async} n’est pas appelé pendant le processus de prérendu sur le serveur. Remplacez la méthode OnAfterRender{Async} pour retarder les appels d’interopérabilité JS jusqu’à ce que le composant soit rendu et interactif sur le client après le prérendu.

PrerenderedInterop1.razor:

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

<PageTitle>Prerendered Interop 1</PageTitle>

<h1>Prerendered Interop Example 1</h1>

<div @ref="divElement">Text during render</div>

@code {
    private ElementReference divElement;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            await JS.InvokeVoidAsync(
                "setElementText1", divElement, "Text after render");
        }
    }
}

Remarque

L’exemple précédent pollue le client avec des fonctions globales. Pour une meilleure approche dans les applications de production, consultez Isolation JavaScript dans les modules JavaScript.

Exemple :

export setElementText1 = (element, text) => element.innerText = text;

Le composant suivant montre comment utiliser l’interopérabilité JS dans le cadre de la logique d’initialisation d’un composant d’une manière compatible avec le prérendu. Le composant indique qu’il est possible de déclencher une mise à jour de rendu à partir de OnAfterRenderAsync. Le développeur doit veiller à éviter de créer une boucle infinie dans ce scénario.

Dans l’exemple suivant, la fonction setElementText2 est appelée avec IJSRuntime.InvokeAsync et retourne une valeur.

Remarque

Pour obtenir une aide générale sur l’emplacement deJS et nos recommandations pour les applications de production, consultez Emplacement de JavaScript dans les applications Blazor ASP.NET Core.

<script>
  window.setElementText2 = (element, text) => {
    element.innerText = text;
    return text;
  };
</script>

Avertissement

L’exemple précédent modifie le modèle DOM directement à des fins de démonstration uniquement. La modification directe du DOM avec JS n’est pas recommandée dans la plupart des scénarios, car JS peut interférer avec le suivi des modifications de Blazor. Pour plus d’informations, consultez Interopérabilité JavaScript et ASP.NET Core Blazor (interopérabilité JS).

Là où JSRuntime.InvokeAsync est appelé, ElementReference est utilisé uniquement dans OnAfterRenderAsync et non dans une méthode de cycle de vie antérieure, car aucun élément DOM HTML n’est présent tant que le composant n’est pas affiché.

StateHasChanged est appelé pour renvoyer le composant avec le nouvel état obtenu à partir de l’appel d’interopérabilité JS (pour plus d’informations, consultez Rendu de composants ASP.NET Core Razor). Le code ne crée pas de boucle infinie, car StateHasChanged est appelé uniquement lorsque data est null.

PrerenderedInterop2.razor:

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

<PageTitle>Prerendered Interop 2</PageTitle>

<h1>Prerendered Interop Example 2</h1>

<p>
    Get value via JS interop call:
    <strong id="val-get-by-interop">@(infoFromJs ?? "No value yet")</strong>
</p>

<p>
    Set value via JS interop call: 
    <strong id="val-set-by-interop" @ref="divElement"></strong>
</p>



@code {
    private string? infoFromJs;
    private ElementReference divElement;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender && infoFromJs == null)
        {
            infoFromJs = await JS.InvokeAsync<string>(
                "setElementText2", divElement, "Hello from interop call!");

            StateHasChanged();
        }
    }
}

Remarque

L’exemple précédent pollue le client avec des fonctions globales. Pour une meilleure approche dans les applications de production, consultez Isolation JavaScript dans les modules JavaScript.

Exemple :

export setElementText2 = (element, text) => {
  element.innerText = text;
  return text;
};

Interopérabilité JS synchrone dans les composants côté client

Cette section s’applique uniquement aux composants côté client.

Les appels d’interopérabilité JS sont asynchrones par défaut, que le code appelé soit synchrone ou asynchrone. Les appels sont asynchrones par défaut pour garantir que les composants sont compatibles entre les modes de rendu côté serveur et côté client. Sur le serveur, tous les appels interop JS doivent être asynchrones car ils sont envoyés via une connexion réseau.

Si vous savez avec certitude que votre composant s'exécute uniquement sur WebAssembly, vous pouvez choisir d'effectuer des appels interop synchrones JS. Cela représente un peu moins de surcharge que d’effectuer des appels asynchrones, et peut entraîner moins de cycles de rendu, car il n’y a pas d’état intermédiaire lors de l’attente des résultats.

Pour effectuer un appel synchrone de .NET vers JavaScript dans un composant côté client, convertissez IJSRuntime en IJSInProcessRuntime pour effectuer l'appel d'interopérabilité JS :

@inject IJSRuntime JS

...

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

Lorsque vous travaillez avec IJSObjectReference des composants côté client dans ASP.NET Core 5.0 ou version ultérieure, vous pouvez utiliser IJSInProcessObjectReference de manière synchrone. IJSInProcessObjectReference implémente IAsyncDisposable/IDisposable et doit être supprimé à des fins de nettoyage de la mémoire pour empêcher une fuite de mémoire, comme l’illustre l’exemple suivant :

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

Emplacement JavaScript

Chargez le code JavaScript (JS) en utilisant une des approches décrites par l’article sur l’emplacement de JavaScript :

• Charger un script dans le balisage <head> (pas généralement recommandé)
• Charger un script dans le balisage <body>
• Charger un script à partir d’un fichier JavaScript externe (.js) colocalisé avec un composant
• Charger un script à partir d’un fichier JavaScript externe (.js)
• Injecter un script avant ou après que Blazor démarre

Pour plus d’informations sur l’isolation des scripts dans les modules JS, consultez la section Isolation JavaScript dans les modules JavaScript.

Avertissement

Placez une balise <script> dans un fichier de composant (.razor) uniquement si vous avez l’assurance que le composant adoptera le rendu statique côté serveur (SSR statique), car la balise <script> ne peut pas être mise à jour dynamiquement.

Isolation JavaScript dans les modules JavaScript

Blazor active l’isolation JavaScript (JS) dans les modules JavaScript standard (spécification ECMAScript). Le chargement de module JavaScript fonctionne de la même manière dans Blazor que pour d’autres types d’applications web, et vous êtes libre de personnaliser la façon dont les modules sont définis dans votre application. Pour obtenir un guide sur l’utilisation des modules JavaScript, consultez MDN Web Docs : modules JavaScript.

L’isolation JS offre les avantages suivants :

• Le code JS importé ne pollue plus l’espace de noms global.
• Les consommateurs d’une bibliothèque et de composants ne sont pas tenus d’importer le code JS associé.

L’importation dynamique avec l’import()opérateur est prise en charge avec ASP.NET Core et Blazor :

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

Dans l’exemple précédent, l’espace {CONDITION} réservé représente une vérification conditionnelle pour déterminer si le module doit être chargé.

Pour la compatibilité du navigateur, consultez Puis-je utiliser : modules JavaScript : importation dynamique.

Par exemple, le module JS suivant exporte une fonction JS pour afficher une invite de fenêtre de navigateur. Placez le code JS suivant dans un fichier JS externe.

wwwroot/scripts.js:

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

Ajoutez le module JS précédent à une application ou une bibliothèque de classes en tant que ressource web statique dans le dossier wwwroot, puis importez le module dans le code .NET en appelant InvokeAsync sur l’instance IJSRuntime.

IJSRuntime importe le module en tant que IJSObjectReference, qui représente une référence à un objet JS à partir du code .NET. Utilisez IJSObjectReference pour appeler des fonctions JS exportées à partir du module.

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 some text");
    }

    public async ValueTask<string?> Prompt(string message) =>
        module is not null ? 
            await module.InvokeAsync<string>("showPrompt", message) : null;

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

Dans l'exemple précédent :

• Par convention, l’identificateur import est un identificateur spécial utilisé spécifiquement pour importer un module JS.
• Spécifiez le fichier JS externe du module à l’aide de son chemin d’accès de ressource web statique stable : ./{SCRIPT PATH AND FILE NAME (.js)}, où :
  • Le segment de chemin pour le répertoire actuel (./) est requis pour créer le chemin de ressource statique correct vers le fichier JS.
  • L’espace réservé {SCRIPT PATH AND FILE NAME (.js)} correspond au chemin et au nom de fichier sous wwwroot.
• Supprime le IJSObjectReference pour le nettoyage de la mémoire dans IAsyncDisposable.DisposeAsync.

L’importation dynamique d’un module nécessite une requête réseau, de sorte qu’elle ne peut être obtenue de manière asynchrone qu’en appelant InvokeAsync.

IJSInProcessObjectReference représente une référence à un objet JS dont les fonctions peuvent être appelées de manière synchrone dans les composants côté client. Pour plus d’informations, consultez la section Interopérabilité JS synchrone dans les composants côté client.

Remarque

Quand le fichier JS externe est fourni par une bibliothèque de classes Razor, spécifiez le fichier JS du module à l’aide de son chemin de ressource web statique stable : ./_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)} :

• Le segment de chemin pour le répertoire actuel (./) est requis pour créer le chemin de ressource statique correct vers le fichier JS.
• L’espace réservé {PACKAGE ID} est l’ID de package de la bibliothèque. L’ID de package est défini par défaut sur le nom d’assembly du projet si <PackageId> n’est pas spécifié dans le fichier projet. Dans l’exemple suivant, le nom de l’assembly de la bibliothèque est ComponentLibrary, et le fichier projet de la bibliothèque ne spécifie pas <PackageId>.
• L’espace réservé {SCRIPT PATH AND FILE NAME (.js)} correspond au chemin et au nom de fichier sous wwwroot. Dans l’exemple suivant, le fichier JS externe (script.js) est placé dans le dossier wwwroot de la bibliothèque de classes.
• module est un élément IJSObjectReference nullable privé de la classe de composant (private IJSObjectReference? module;).

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

Pour plus d’informations, consultez Consommer des composants ASP.NET Core Razor à partir d’une bibliothèque de classes (RCL) Razor.

Dans la documentation Blazor, les exemples utilisent l’extension de fichier .js pour les fichiers de module, et non l’extension de fichier .mjs plus récente (RFC 9239). Notre documentation continue d’utiliser l’extension de fichier .js pour les mêmes raisons que la documentation de Mozilla Foundation continue d’utiliser l’extension de fichier .js. Pour plus d’informations, consultez Aparté : mjs ou .js (documentation MDN).

Capturer des références à des éléments

Certains scénarios d’interopérabilité JavaScript (JS) nécessitent des références à des éléments HTML. Par exemple, une bibliothèque d’interface utilisateur peut nécessiter une référence d’élément pour l’initialisation, ou vous devrez peut-être appeler des API de type commande sur un élément, comme click ou play.

Capturez des références à des éléments HTML dans un composant à l’aide de l’approche suivante :

• Ajoutez un attribut @ref à l’élément HTML.
• Définissez un champ de type ElementReference dont le nom correspond à la valeur de l’attribut @ref.

L’exemple suivant montre la capture d’une référence à l’élément username<input> :

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

@code {
    private ElementReference username;
}

Warning

Utilisez uniquement une référence d’élément pour muter le contenu d’un élément vide qui n’interagit pas avec Blazor. Ce scénario est utile lorsqu’une API tierce fournit du contenu à l’élément. Étant donné que Blazor n’interagit pas avec l’élément, il n’existe aucun risque de conflit entre la représentation de Blazor de l’élément et le modèle DOM.

Dans l’exemple suivant, il est dangereux de muter le contenu de la liste non triée (ul) à l’aide de MyList via l’interopérabilité JS, car Blazor interagit avec le DOM pour remplir les éléments de liste de cet élément (<li>) à partir de l’objet Todos :

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

L’utilisation de la référence d’élément MyList pour simplement lire le contenu DOM ou déclencher un événement est prise en charge.

Si l’interopérabilité JSmute le contenu de l’élément MyList et que Blazor tente d’appliquer des différences à l’élément, les différences ne correspondent pas au DOM. La modification du contenu de la liste via l’interopérabilité JS avec la référence d’élément MyListn’est pas prise en charge.

Pour plus d’informations, consultez Interopérabilité JavaScript et ASP.NET Core Blazor (interopérabilité JS).

Un ElementReference est transmis au code JS via l’interopérabilité JS. Le code JS reçoit une instance HTMLElement, qu’elle peut utiliser avec des API DOM normales. Par exemple, le code suivant définit une méthode d’extension .NET (TriggerClickEvent) qui permet d’envoyer un clic de souris à un élément.

La fonction JSclickElement crée un événement click sur l’élément HTML passé (element) :

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

Pour appeler une fonction JS qui ne retourne pas de valeur, utilisez JSRuntimeExtensions.InvokeVoidAsync. Le code suivant déclenche un événement click côté client en appelant la fonction JS précédente avec le ElementReference capturé :

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

Pour utiliser une méthode d’extension, créez une méthode d’extension statique qui reçoit l’instance IJSRuntime :

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

La méthode clickElement est appelée directement sur l’objet. L’exemple suivant suppose que la méthode TriggerClickEvent est disponible à partir de l’espace de noms 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);
    }
}

Important

La variable exampleButton est renseignée uniquement après le rendu du composant. Si un ElementReference non rempli est passé au code JS, le code JS reçoit une valeur de null. Pour manipuler les références d’élément une fois le rendu du composant terminé, utilisez les méthodes de cycle de vie de composant OnAfterRenderAsync ou OnAfterRender.

Lorsque vous utilisez des types génériques et retournez une valeur, utilisez ValueTask<TResult> :

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

L’espace réservé {JAVASCRIPT FUNCTION} est l’identificateur de fonction JS.

GenericMethod est appelé directement sur l’objet avec un type. L’exemple suivant suppose que le GenericMethod est disponible à partir de l’espace de noms 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);
    }
}

Référencer des éléments entre composants

Un ElementReference ne peut pas être passé entre composants pour les raisons suivantes :

• L’existence de l’instance n’est garantie qu’une fois que le composant a été rendu, c’est-à-dire pendant ou après l’exécution de la méthode OnAfterRender/OnAfterRenderAsync d’un composant.
• Un ElementReference est un struct, qui ne peut pas être passé en tant que paramètre de composant.

Pour qu’un composant parent rende une référence d’élément disponible pour d’autres composants, le composant parent peut :

• Autoriser les composants enfants à inscrire des rappels.
• Appeler les rappels inscrits pendant l’événement OnAfterRender avec la référence d’élément passée. Indirectement, cette approche permet aux composants enfants d’interagir avec la référence d’élément parent.

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

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

Remarque

Pour obtenir une aide générale sur l’emplacement deJS et nos recommandations pour les applications de production, consultez Emplacement de JavaScript dans les applications Blazor ASP.NET Core.

CallJs7.razor (composant parent) :

@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)
        {
            try
            {
                subscription.OnNext(title);
            }
            catch (Exception)
            {
                throw;
            }
        }
    }

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

Dans l’exemple précédent, l’espace de noms de l’application est BlazorSample. Si vous testez le code localement, mettez à jour l’espace de noms.

SurveyPrompt.razor (composant enfant) :

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

Dans l’exemple précédent, l’espace de noms de l’application est BlazorSample avec des composants partagés dans le dossier Shared. Si vous testez le code localement, mettez à jour l’espace de noms.

Renforcer les appels d’interopérabilité JavaScript

Cette section s’applique seulement aux composants de serveur interactif, mais les composants côté client peuvent également définir des délais d’expiration d’interopérabilité JS si les conditions le justifient.

Dans les applications côté serveur avec interactivité de serveur, l’interopérabilité JavaScript (JS) peut échouer en raison d’erreurs de mise en réseau, et doit être traitée comme non fiable. Par défaut, les applications Blazor utilisent un délai d’expiration d’une minute pour les appels d’interopérabilité JS. Si une application peut tolérer un délai d’expiration plus agressif, définissez le délai d’expiration à l’aide de l’une des approches suivantes.

Définissez un délai global dans le Program.cs avec CircuitOptions.JSInteropDefaultCallTimeout :

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

L’espace réservé {TIMEOUT} est un TimeSpan (par exemple, TimeSpan.FromSeconds(80)).

Définissez un délai d’expiration par appel dans le code du composant. Le délai d’expiration spécifié remplace le délai d’attente global défini par JSInteropDefaultCallTimeout :

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

Dans l'exemple précédent :

• L’espace réservé {TIMEOUT} est un TimeSpan (par exemple, TimeSpan.FromSeconds(80)).
• L’espace réservé {ID} est l’identificateur de la fonction à appeler. Par exemple, la valeur someScope.someFunction appelle la fonction window.someScope.someFunction.

Bien qu’une cause courante d’échecs d’interopérabilité JS soit des défaillances réseau avec des composants côté serveur, les délais d’expiration par appel peuvent être définis pour les appels d’interopérabilité JS pour les composants côté client. Bien qu’aucun circuit SignalR n’existe pour un composant côté client, les appels d’interopérabilité JS peuvent échouer pour d’autres raisons qui s’appliquent.

Pour plus d’informations sur l’épuisement des ressources, voir Threat mitigation guidance for ASP.NET CoreBlazor interactive server-side rendering.

Éviter les références d’objets circulaires

Les objets qui contiennent des références circulaires ne peuvent pas être sérialisés sur le client pour :

• Les appels de méthode .NET.
• Les appels de méthode JavaScript à partir de C# lorsque le type de retour a des références circulaires.

Bibliothèques JavaScript qui effectuent le rendu de l’interface utilisateur

Parfois, vous souhaiterez peut-être utiliser des bibliothèques JavaScript (JS) qui produisent des éléments d’interface utilisateur visibles dans le modèle DOM du navigateur. À première vue, cela peut sembler difficile, car le système de fonctions différentielles de Blazor s’appuie sur le contrôle sur l’arborescence des éléments DOM et rencontre des erreurs si un code externe mute l’arborescence DOM et invalide son mécanisme pour appliquer les différences. Il ne s’agit pas d’une limitation propre à Blazor. Le même problème se présente avec n’importe quel framework d’interface utilisateur basé sur l’analyse différentielle.

Heureusement, il est facile d’incorporer l’interface utilisateur générée en externe dans une interface utilisateur de composant Razor de manière fiable. La technique recommandée consiste à ce que le code du composant (fichier .razor) produise un élément vide. En ce qui concerne le système d’analyse des différences de Blazor, l’élément est toujours vide, de sorte que le convertisseur n’itère pas dans l’élément et laisse son contenu inchangé. Cela permet de remplir l’élément avec du contenu arbitraire géré en externe.

L’exemple suivant illustre le concept. Dans l’instruction if lorsque firstRender est true, interagissez avec unmanagedElement en dehors de Blazor à l’aide de l’interopérabilité JS. Par exemple, appelez une bibliothèque JS externe pour remplir l’élément. Blazor laisse le contenu de l’élément inchangé jusqu’à ce que ce composant soit supprimé. Lorsque le composant est supprimé, l’ensemble de la sous-arborescence DOM du composant est également supprimé.

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

Prenons l’exemple suivant qui affiche une carte interactive à l’aide des API Mapbox open source.

Le module JS suivant est placé dans l’application ou mis à disposition à partir d’une bibliothèque de classes Razor.

Remarque

Pour créer la carte Mapbox, obtenez un jeton d’accès à partir de Mapbox Sign in et fournissez-le là où {ACCESS TOKEN} apparaît le dans le code suivant.

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

Pour produire un style correct, ajoutez la balise de feuille de style suivante à la page HTML hôte.

Ajoutez l’élément <link> suivant au balisage d’élément <head> (emplacement de <head>contenu) :

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

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

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

L’exemple précédent génère une interface utilisateur de carte interactive. L’utilisateur :

• Possibilité de faire glisser pour faire défiler ou zoomer.
• Sélection avec des boutons pour accéder à des emplacements prédéfinis.

Dans l'exemple précédent :

• <div> avec @ref="mapElement" est laissé vide en ce qui concerne Blazor. Le script mapbox-gl.js peut remplir en toute sécurité l’élément et modifier son contenu. Utilisez cette technique avec n’importe quelle bibliothèque JS qui restitue l’interface utilisateur. Vous pouvez incorporer des composants à partir d’un framework SPA JS tiers à l’intérieur de composants Razor, tant qu’ils n’essaient pas d’atteindre et de modifier d’autres parties de la page. Il n’est pas sécurisé pour le code JS externe de modifier les éléments que Blazor ne considère pas comme vides.
• Lorsque vous utilisez cette approche, gardez à l’esprit les règles relatives à la façon dont Blazor conserve ou détruit les éléments DOM. Le composant gère en toute sécurité les événements de clic de bouton et met à jour l’instance de carte existante, car les éléments DOM sont conservés dans la mesure du possible par défaut. Si vous affichez une liste d’éléments de carte à partir d’une boucle @foreach, vous souhaitez utiliser @key pour garantir la conservation des instances de composant. Sinon, les modifications apportées aux données de liste peuvent entraîner la conservation de l’état des instances de composant précédentes de manière indésirable par les instances précédentes. Pour plus d’informations, découvrez comment utiliser l’attribut de directive @key pour préserver la relation entre les éléments, les composants et les objets de modèle.
• L’exemple encapsule la logique et les dépendances JS dans un module ES6 et charge le module dynamiquement à l’aide de l’identificateur import. Pour plus d’informations, consultez Isolation JavaScript dans les modules JavaScript.

Prise en charge des tableaux d’octets

Blazor prend en charge l’interopérabilité JavaScript (JS) des tableaux d’octets optimisés, qui évite l’encodage/décodage des tableaux d’octets en Base64. L’exemple suivant utilise l’interopérabilité JS pour passer un tableau d’octets à JavaScript.

Fournissez une fonction receiveByteArrayJS. La fonction est appelée avec InvokeVoidAsync et ne retourne pas de valeur :

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

Remarque

Pour obtenir une aide générale sur l’emplacement deJS et nos recommandations pour les applications de production, consultez Emplacement de JavaScript dans les applications Blazor 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);
    }
}

Diffuser en continu de .NET vers JavaScript

Blazor prend en charge la diffusion en continu de données directement de .NET vers JavaScript. Les flux sont créés à l’aide de DotNetStreamReference.

DotNetStreamReference représente un flux .NET et utilise les paramètres suivants :

• stream : le flux envoyé à JavaScript.
• leaveOpen : détermine si le flux est laissé ouvert après la transmission. Si aucune valeur n’est fournie, leaveOpen prend la valeur par défaut false.

En JavaScript, utilisez une mémoire tampon de tableau ou un flux lisible pour recevoir les données :

• Utilisation d’un ArrayBuffer :

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

• Utilisation d’un ReadableStream :

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

Dans le code C# :

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

Dans l'exemple précédent :

• L’espace réservé {STREAM} représente le Stream envoyé à JavaScript.
• JS est un instance IJSRuntime injectée.

Appeler des méthodes .NET à partir de fonctions JavaScript dans ASP.NET Core Blazor couvre l’opération inverse, la diffusion en continu de JavaScript vers .NET.

Téléchargements de fichiers ASP.NET Core Blazor explique comment télécharger un fichier dans Blazor.

Intercepter les exceptions JavaScript

Pour intercepter les exceptions JS, encapsulez l’interopérabilité JS dans un bloc try-catch et interceptez un JSException.

Dans l’exemple suivant, la fonction nonFunctionJS n’existe pas. Lorsque la fonction est introuvable, la JSException est interceptée par un Message, qui indique l’erreur suivante :

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

Abandonner une fonction JavaScript de longue durée

Utilisez JSAbortController avec CancellationTokenSource dans le composant pour abandonner une fonction JavaScript de longue durée à partir du code C#.

La classe JSHelpers suivante contient une fonction de longue durée simulée, longRunningFn, pour compter en continu jusqu’à ce que AbortController.signal indique l’appel à AbortController.abort. La fonction sleep sert à des fins de démonstration pour simuler l’exécution lente de la fonction longue, et ne serait pas présente dans le code de production. Lorsqu’un composant appelle stopFn, longRunningFn est signalé pour abandonner via la vérification conditionnelle de la boucle while sur 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>

Remarque

Pour obtenir une aide générale sur l’emplacement deJS et nos recommandations pour les applications de production, consultez Emplacement de JavaScript dans les applications Blazor ASP.NET Core.

Le composant suivant :

• Appelle la fonction JSlongRunningFn lorsque le bouton Start Task est sélectionné. Un CancellationTokenSource est utilisé pour gérer l’exécution de la fonction de longue durée. CancellationToken.Register définit un délégué d’appel d’interopérabilité JS pour exécuter la fonction JSstopFn lorsque le CancellationTokenSource.Token est annulé.
• Lorsque le bouton Cancel Task est sélectionné, le CancellationTokenSource.Token est annulé avec un appel à Cancel.
• Le CancellationTokenSource est supprimé dans la méthode 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 console d’outils de développement d’un navigateur indique l’exécution de la fonction JS de longue durée après la sélection du bouton Start Task, et lorsque la fonction est abandonnée une fois le bouton Cancel Task sélectionné :

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

JavaScript [JSImport]/[JSExport] interop

Cette section s’applique aux composants côté client.

En guise d’alternative à l’interaction avec JavaScript (JS) dans les composants côté client à l’aide du mécanisme d’interopérabilité JS de Blazor basé sur l’interface IJSRuntime, une API d’interopérabilité JS[JSImport]/[JSExport] est disponible pour les applications ciblant .NET 7 ou version ultérieure.

Pour plus d’informations, consultez interopérabilité JSImport/JSExport JavaScript avec Blazor ASP.NET Core.

Interopérabilité JavaScript démarshalée

Cette section s’applique aux composants côté client.

L’interopérabilité démarshalée à l’aide de l’interface IJSUnmarshalledRuntime est obsolète et doit être remplacée par l’interopérabilité [JSImport]/[JSExport] JavaScript.

Pour plus d’informations, consultez interopérabilité JSImport/JSExport JavaScript avec Blazor ASP.NET Core.

Suppression des références d’objets d’interopérabilité JavaScript

Les exemples des articles d’interopérabilité JavaScript (JS) illustrent des modèles de suppression d’objets classiques :

• Lorsque vous appelez JS à partir de .NET, comme décrit dans cet article, supprimez les IJSObjectReference/IJSInProcessObjectReference/JSObjectReference créés à partir de .NET ou de JS pour éviter la fuite de mémoire JS.

• Lors de l’appel de .NET à partir de JS, comme décrit dans Appeler des méthodes .NET à partir de fonctions JavaScript dans ASP.NET Core Blazor, supprimez un DotNetObjectReference créé à partir de .NET ou de JS pour éviter la fuite de mémoire .NET.

Les références d’objet d’interopérabilité JS sont implémentées en tant que carte avec pour clé un identificateur sur le côté de l’appel d’interopérabilité JS qui crée la référence. Lorsque l’élimination de l’objet est lancée du côté .NET ou JS, Blazor supprime l’entrée de la carte, et l’objet peut être récupéré en mémoire tant qu’aucune autre référence forte à l’objet n’est présente.

Au minimum, éliminez toujours les objets créés côté .NET pour éviter les fuites de mémoire managée .NET.

Tâches de nettoyage de modèle DOM lors de la suppression des composants

Pour plus d’informations, consultez Interopérabilité JavaScript et ASP.NET Core Blazor (interopérabilité JS).

Appels d’interopérabilité JavaScript sans circuit

Pour plus d’informations, consultez Interopérabilité JavaScript et ASP.NET Core Blazor (interopérabilité JS).

Ressources supplémentaires

• Appeler des méthodes .NET à partir de fonctions JavaScript dans ASP.NET Core Blazor
• Exemple InteropComponent.razor (branche dotnet/AspNetCore du dépôt GitHub main) : la branche main représente le développement actuel de l’unité de produit pour la prochaine version d’ASP.NET Core. Pour sélectionner la branche d’une autre version (par exemple, release/5.0), utilisez la liste déroulante Changer de branche ou d’étiquette pour sélectionner la branche.
• Blazor exemples de référentiel GitHub (dotnet/blazor-samples) (comment télécharger)
• Gérer les erreurs dans les applications ASP.NET Core Blazor (section interopérabilité JavaScript)
• Atténuation des menaces : fonctions JavaScript appelées à partir de .NET