Emplacement du code JavaScript dans les applications Blazor ASP.NET Core
Remarque
Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 8 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 8 de cet article.
Chargez du code JavaScript (JS) à l’aide de l’une des approches suivantes :
- 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
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 application web Blazor (.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 application web Blazor (.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)
{
await module.DisposeAsync();
}
}
}
{PATH}/JsCollocation2.razor.js:
export function showPrompt2(message) {
return prompt(message, 'Type your name here');
}
Pour les scripts ou modules fournis par une bibliothèque de classes (RCL) Razor, le chemin d’accès suivant est utilisé :
_content/{PACKAGE ID}/{PATH}/{COMPONENT}.{EXTENSION}.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,razoroucshtml.
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
JsCollocation3figure dans le dossierComponents/Pagesde 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>
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 souswwwroot.
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)} :
- 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. - L’espace réservé
{SCRIPT PATH AND FILE NAME (.js)}correspond au chemin et au nom de fichier souswwwroot.
<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
ComponentLibraryet aucun<PackageId>n’est spécifié dans le fichier projet de la bibliothèque. - Le fichier
scripts.jsse trouve dans le dossierwwwrootde 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é.
Pour plus d’informations, consultez Appeler des fonctions JavaScript à partir de méthodes .NET dans ASP.NET Core Blazor.
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.
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour