Partager via

Emplacement du code JavaScript dans les applications Blazor ASP.NET Core

  • Article

Remarque

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 9 de cet article.

Avertissement

Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la stratégie de support .NET et .NET Core. Pour la version actuelle, consultez la version .NET 9 de cet article.

Important

Ces informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.

Pour la version actuelle, consultez la version .NET 9 de cet article.

Chargez du code JavaScript (JS) à l’aide de l’une des approches suivantes :

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.

Avertissement

Ne placez pas une balise <script> dans un fichier de composant (.razor) car la balise <script> ne peut pas être mise à jour dynamiquement.

Remarque

Les exemples de documentation placent généralement des scripts dans une balise <script> ou chargent des scripts globaux à partir de fichiers externes. Ces approches polluent le client avec des fonctions globales. Pour les applications de production, nous vous recommandons de placer JS dans des modules JS qui peuvent être importés si nécessaire. Pour plus d’informations, consultez la section Isolation JavaScript dans les modules JavaScript.

Remarque

Les exemples de documentation placent des scripts dans une balise <script> ou chargent des scripts globaux à partir de fichiers externes. Ces approches polluent le client avec des fonctions globales. Le placement de JS dans des modules JS distincts pouvant être importés si nécessaire n’est pas pris en charge dans les versions de Blazor antérieure à ASP.NET Core 5.0. Si l’application nécessite l’utilisation de modules JS pour l’isolation JS, nous vous recommandons d’utiliser ASP.NET Core 5.0 ou version ultérieure pour générer l’application. Pour plus d’informations, utilisez la liste déroulante Version pour sélectionner une version 5.0 ou ultérieure de cet article et voir la section Isolation JavaScript dans les modules JavaScript.

Charger un script dans le balisage <head>

L’approche dans cette section n’est généralement pas recommandée.

Placez les (JS) balises JavaScript (<script>...</script>) dans le <head>balisage de l’élément :

<head>
    ...

    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</head>

Le chargement de JS à partir de <head> n’est pas la meilleure approche pour les raisons suivantes :

  • L’interopérabilité JS peut échouer si le script dépend de Blazor. Nous vous recommandons de charger des scripts par une autre approche, et non via le balisage <head>.
  • La page peut devenir plus lentement interactive en raison du temps nécessaire à l’analyse JS du script.

Charger un script dans le balisage <body>

Placez les balises JavaScript (<script>...</script>) dans l’élément </body> de fermeture après la référence au script Blazor :

<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</body>

Dans l’exemple précédent, l’espace réservé {BLAZOR SCRIPT} est le chemin d’accès de script Blazor et le nom de fichier. Pour connaître l’emplacement du script, consultez ASP.NET Core Blazor structure du projet.

Charger un script à partir d’un fichier JavaScript externe (.js) colocalisé avec un composant

La colocation de fichiers JavaScript (JS) pour les composants Razor constitue un moyen pratique pour organiser des scripts dans une application.

Les composants Razor pour les applications Blazor colocalisent des fichiers JS en utilisant l’extension .razor.js et sont adressables publiquement en tirant parti du chemin d’accès au fichier dans le projet :

{PATH}/{COMPONENT}.razor.js

  • L’espace réservé {PATH} constitue le chemin d’accès au composant.
  • L’espace réservé {COMPONENT} constitue le composant.

Quand l’application est publiée, l’infrastructure déplace automatiquement le script vers la racine web. Les scripts sont déplacés vers bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.js où les espaces réservés sont :

  • {TARGET FRAMEWORK MONIKER} constitue le moniker de framework cible (TFM).
  • {PATH} constitue le chemin d’accès au composant.
  • {COMPONENT} constitue le nom de composant.

Aucune modification n’est requise pour l’URL relative du script, car Blazor se charge de placer le fichier JS dans des ressources statiques publiées à votre place.

Cette section et les exemples suivants sont principalement axés sur l’explication de la colocation de fichiers JS. Le premier exemple illustre un fichier colocalisé JS avec une fonction ordinaire JS. Le deuxième exemple illustre l’utilisation d’un module pour charger une fonction, ce qui correspond à l’approche recommandée pour la plupart des applications de production. L’appel JS à partir de .NET est entièrement couvert dans les fonctions JavaScript d’appel à partir de méthodes .NET dans ASP.NET CoreBlazor, où il existe d’autres explications de l’API BlazorJS avec des exemples supplémentaires. L’élimination des composants, qui est présente dans le deuxième exemple, est abordée dans Cycle de vie des composants Razor ASP.NET Core .

Le composant JsCollocation1 suivant charge un script via un composant HeadContent et appelle une fonction JS avec IJSRuntime.InvokeAsync. L’espace réservé {PATH} constitue le chemin d’accès au composant.

Important

Si vous utilisez le code suivant pour une démonstration dans une application de test, remplacez l’espace réservé {PATH} par le chemin d’accès du composant (exemple : Components/Pages dans .NET 8 ou ultérieur ou Pages dans .NET 7 ou antérieur). Dans une Blazor Web App (.NET 8 ou version ultérieure), le composant nécessite un mode de rendu interactif appliqué globalement à l’application ou à la définition du composant.

Ajoutez le script suivant après le script Blazor (emplacement du script de démarrage Blazor) :

<script src="{PATH}/JsCollocation1.razor.js"></script>

Composant JsCollocation1 ({PATH}/JsCollocation1.razor) :

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

<PageTitle>JS Collocation 1</PageTitle>

<h1>JS Collocation Example 1</h1>

<button @onclick="ShowPrompt">Call showPrompt1</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

@code {
    private string? result;

    public async void ShowPrompt()
    {
        result = await JS.InvokeAsync<string>(
            "showPrompt1", "What's your name?");
        StateHasChanged();
    }
}

Le fichier colocalisé JS est placé en regard du fichier de composant JsCollocation1 avec le nom de fichier JsCollocation1.razor.js. Dans le composant JsCollocation1, le script est référencé au niveau du chemin du dossier colocalisé. Dans l’exemple suivant, la fonction showPrompt1 accepte le nom de l’utilisateur à partir d’un Window prompt() et le retourne au composant JsCollocation1 pour l’affichage.

{PATH}/JsCollocation1.razor.js:

function showPrompt1(message) {
  return prompt(message, 'Type your name here');
}

L’approche précédente n’est pas recommandée pour une utilisation générale dans des applications de production, car elle pollue le client avec des fonctions globales. Une meilleure approche pour les applications de production consiste à utiliser des modules JS. Ces mêmes principes généraux s’appliquent au chargement d’un module JS à partir d’un fichier JS colocalisé, tel qu’illustré dans l’exemple suivant.

La méthode OnAfterRenderAsync du composant JsCollocation2 suivant charge un module JS dans module qui est un IJSObjectReference de la classe de composant. module est utilisé pour appeler la fonction showPrompt2. L’espace réservé {PATH} constitue le chemin d’accès au composant.

Important

Si vous utilisez le code suivant pour une démonstration dans une application de test, remplacez l’espace réservé {PATH} par le chemin d’accès du composant. Dans une Blazor Web App (.NET 8 ou version ultérieure), le composant nécessite un mode de rendu interactif appliqué globalement à l’application ou à la définition du composant.

Composant JsCollocation2 ({PATH}/JsCollocation2.razor) :

@page "/js-collocation-2"
@implements IAsyncDisposable
@inject IJSRuntime JS

<PageTitle>JS Collocation 2</PageTitle>

<h1>JS Collocation Example 2</h1>

<button @onclick="ShowPrompt">Call showPrompt2</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

@code {
    private IJSObjectReference? module;
    private string? result;

    protected async override Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            /*
                Change the {PATH} placeholder in the next line to the path of
                the collocated JS file in the app. Examples:

                ./Components/Pages/JsCollocation2.razor.js (.NET 8 or later)
                ./Pages/JsCollocation2.razor.js (.NET 7 or earlier)
            */
            module = await JS.InvokeAsync<IJSObjectReference>("import",
                "./{PATH}/JsCollocation2.razor.js");
        }
    }

    public async void ShowPrompt()
    {
        if (module is not null)
        {
            result = await module.InvokeAsync<string>(
                "showPrompt2", "What's your name?");
            StateHasChanged();
        }
    }

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

Dans l’exemple précédent, JSDisconnectedException est piégé lors de l’élimination du module au cas où Blazorle circuit est SignalR perdu. Si le code précédent est utilisé dans une Blazor WebAssembly application, il n’existe aucune SignalR connexion à perdre. Vous pouvez donc supprimer lecatch try-bloc et laisser la ligne qui supprime le module ().await module.DisposeAsync(); Pour plus d’informations, consultez Interopérabilité JavaScript et ASP.NET Core Blazor (interopérabilité JS).

{PATH}/JsCollocation2.razor.js:

export function showPrompt2(message) {
  return prompt(message, 'Type your name here');
}

L’utilisation de scripts et de modules pour le JS colocalisé dans une bibliothèque de classes Razor (RCL) n’est prise en charge que pour le mécanisme d’interop JS de Blazor basé sur l’interface IJSRuntime. Si vous implémentez l’interopéabilité JavaScript [JSImport]/[JSExport], consultez Interopérabilité JSImport/JSExport JavaScript avec ASP.NET Core Blazor.

Pour les scripts ou modules fournis par une bibliothèque de classes Razor (RCL) qui utilise l’interop JS basée sur IJSRuntime, le chemin d’accès suivant est utilisé :

./_content/{PACKAGE ID}/{PATH}/{COMPONENT}.{EXTENSION}.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’identificateur de package de la bibliothèque RCL (ou le nom de la bibliothèque pour une bibliothèque de classes référencée par l’application).
  • L’espace réservé {PATH} constitue le chemin d’accès au composant. Si un composant Razor se trouve à la racine de la bibliothèque RCL, le segment de chemin n’est pas inclus.
  • L’espace réservé {COMPONENT} constitue le nom de composant.
  • L’espace réservé {EXTENSION} correspond à l’extension du composant, razor ou cshtml.

Dans l’exemple d’application Blazor suivant :

  • L’identificateur de package de la bibliothèque RCL est AppJS.
  • Les scripts d’un module sont chargés pour le composant JsCollocation3 (JsCollocation3.razor).
  • Le composant JsCollocation3 figure dans le dossier Components/Pages de la bibliothèque RCL.
module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./_content/AppJS/Components/Pages/JsCollocation3.razor.js");

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

Charger un script à partir d’un fichier JavaScript externe (.js)

Placez les (JS) balises JavaScript (<script>...</script>) avec un chemin source de script (src) à l’intérieur de la balise de fermeture</body> après la référence du scriptBlazor :

<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script src="{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

Pour les espace réservés dans l’exemple précédent :

  • L’espace réservé {BLAZOR SCRIPT} correspond au chemin d’accès au script et au nom de fichier Blazor. Pour connaître l’emplacement du script, consultez ASP.NET Core Blazor structure du projet.
  • L’espace réservé {SCRIPT PATH AND FILE NAME (.js)} correspond au chemin et au nom de fichier de script sous wwwroot.

Dans l’exemple suivant de la balise <script> précédente, le fichier scripts.js figure dans le dossier wwwroot/js de l’application :

<script src="js/scripts.js"></script>

Vous pouvez également traiter des scripts directement à partir du dossier wwwroot si vous préférez ne pas conserver tous vos scripts dans un dossier distinct sous wwwroot :

<script src="scripts.js"></script>

Quand le fichier JS externe est fourni par une bibliothèque de classes Razor, spécifiez le fichier JS à l’aide de son chemin de ressource web statique stable : _content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.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.
  • L’espace réservé {SCRIPT PATH AND FILE NAME (.js)} correspond au chemin et au nom de fichier sous wwwroot.
<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script src="_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

Dans l’exemple suivant de la balise <script> précédente :

  • La bibliothèque de classes Razor a le nom d’assembly ComponentLibrary et aucun <PackageId> n’est spécifié dans le fichier projet de la bibliothèque.
  • Le fichier scripts.js se trouve dans le dossier wwwroot de la bibliothèque de classes.
<script src="_content/ComponentLibrary/scripts.js"></script>

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

Injecter un script avant ou après le démarrage de Blazor

Pour garantir le chargement des scripts avant ou après le démarrage de Blazor, utilisez un initialiseur JavaScript. Pour plus d’informations et d’exemples, consultez ASP.NET Core Blazor startup.

Injecter un script après que Blazor démarre

Pour injecter un script après le démarrage de Blazor, chaînez le Promise qui résulte d’un démarrage manuel de Blazor. Pour plus d’informations et un exemple, consultez ASP.NET Core Blazor startup.

Isolation JavaScript dans les modules JavaScript

Blazor active l’isolation JavaScript (JS) dans les modules JS standard (spécification ECMAScript).

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

Dans les scénarios côté serveur, interceptez JSDisconnectedException toujours en cas de perte de BlazorSignalR circuits empêche un JS appel d’interopérabilité de supprimer un module, ce qui entraîne une exception non gérée. Blazor WebAssembly les applications n’utilisent pas de SignalR connexion pendant JS l’interopérabilité. Il n’est donc pas nécessaire de les intercepter JSDisconnectedException dans les Blazor WebAssembly applications pour la suppression des modules.

Pour plus d’informations, consultez les ressources suivantes :