Blazor ASP.NET Core l’interopérabilité JavaScript (JSinteropérabilité)

Cet article explique les concepts généraux sur l’interaction avec JavaScript dans les Blazor applications.

Une Blazor application peut appeler des fonctions JavaScript (JS) à partir de méthodes .NET et de méthodes .NET à partir de JS fonctions. Ces scénarios sont appelés interopérabilité JavaScript (JS interopérabilité).

D’autres JS conseils d’interopérabilité sont fournis dans les articles suivants :

Interaction avec le modèle objet document (DOM)

Mutez uniquement le modèle objet document (DOM) avec JavaScript (JS) lorsque l’objet n’interagit pas avec Blazor. Blazor gère les représentations du DOM et interagit directement avec les objets DOM. Si un élément rendu par Blazor est modifié en externe à l’aide JS directement ou via JS Interop, le DOM peut ne plus correspondre Blazorà la représentation interne, ce qui peut entraîner un comportement non défini. Le comportement non défini peut simplement interférer avec la présentation d’éléments ou leurs fonctions, mais peut également introduire des risques de sécurité pour l’application ou le serveur.

Cette aide s’applique non seulement à votre propre JS code d’interopérabilité, mais également à toutes JS les bibliothèques que l’application utilise, y compris tout ce qui est fourni par une infrastructure tierce, telle que Bootstrap JS et jQuery.

Dans quelques exemples de documentation, JS l’interopérabilité est utilisée pour muter un élément purement à des fins de démonstration dans le cadre d’un exemple. Dans ces cas, un avertissement apparaît dans le texte.

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

Appels JavaScript asynchrones

JS Les appels d’interopérabilité sont asynchrones par défaut, que le code appelé soit synchrone ou asynchrone. Les appels sont asynchrones par défaut pour s’assurer que les composants sont compatibles entre les Blazor modèles Blazor Server d’hébergement et Blazor WebAssembly. Sur Blazor Server, les appels d’interopérabilité doivent être asynchrones, JS car ils sont envoyés via une connexion réseau. Pour les applications qui adoptent exclusivement le Blazor WebAssembly modèle d’hébergement, les appels d’interopérabilité synchrone JS sont pris en charge.

Pour plus d’informations, consultez les articles suivants :

Sérialisation d’objets

Blazor utilise System.Text.Json pour la sérialisation avec les exigences et les comportements par défaut suivants :

  • Les types doivent avoir un constructeur par défaut, get/set les accesseurs doivent être publics et les champs ne sont jamais sérialisés.
  • La sérialisation par défaut globale n’est pas personnalisable pour éviter de briser les bibliothèques de composants existantes, les répercussions sur les performances et la sécurité et les réductions de fiabilité.
  • La sérialisation des noms de membres .NET entraîne des noms de clés ON en minuscules JS.
  • JSON est désérialisé en tant qu’instances JsonElement C#, ce qui autorise la casse mixte. Le cast interne pour l’affectation aux propriétés du modèle C# fonctionne comme prévu malgré les différences de cas entre JSles noms de clés ON et les noms de propriétés C#.

JsonConverter L’API est disponible pour la sérialisation personnalisée. Les propriétés peuvent être annotées avec un [JsonConverter] attribut pour remplacer la sérialisation par défaut pour un type de données existant.

Pour plus d’informations, consultez les ressources suivantes dans la documentation .NET :

JSLa prise en charge System.DateOnly du sérialiseur ON est System.TimeOnly prévue pour ASP.NET Core 7.0, qui est prévue pour la mise en production à la fin de 2022. Pour plus d’informations, consultez Support DateOnly et TimeOnly in JsonSerializer (dotnet/runtime #53539).

Blazor prend en charge l’interopérabilité de tableau JS d’octets optimisée qui évite l’encodage/décodage des tableaux d’octets en Base64. L’application peut appliquer la sérialisation personnalisée et passer les octets résultants. Pour plus d’informations, consultez Appeler des fonctions JavaScript à partir de méthodes .NET dans ASP.NET Core Blazor.

Blazor prend en charge l’interopérabilité nonmarshallée JS lorsqu’un volume élevé d’objets .NET est rapidement sérialisé ou quand des objets .NET volumineux ou de nombreux objets .NET doivent être sérialisés. Pour plus d’informations, consultez Appeler des fonctions JavaScript à partir de méthodes .NET dans ASP.NET Core Blazor.

Initialiseurs JavaScript

Les initialiseurs JavaScript (JS) exécutent la logique avant et après le chargement d’une Blazor application. JS Les initialiseurs sont utiles dans les scénarios suivants :

  • Personnalisation du chargement d’une Blazor application.
  • Initialisation des bibliothèques avant Blazor le démarrage.
  • Configuration des Blazor paramètres.

JS Les initialiseurs sont détectés dans le cadre du processus de génération et importés automatiquement dans les Blazor applications. L’utilisation des initialiseurs supprime souvent la nécessité de déclencher manuellement des fonctions de script de l’application lors deJS l’utilisation Razor de bibliothèques de classes (RCLs).

Pour définir un JS initialiseur, ajoutez un JS module au projet nommé {NAME}.lib.module.js, où l’espace réservé est le nom de l’assembly, le {NAME} nom de la bibliothèque ou l’identificateur de package. Placez le fichier dans la racine web du projet, qui est généralement le wwwroot dossier.

Le module exporte l’une ou l’autre des fonctions conventionnelles suivantes :

  • beforeStart(options, extensions): appelé avant Blazor de commencer. Par exemple, beforeStart il est utilisé pour personnaliser le processus de chargement, le niveau de journalisation et d’autres options spécifiques au modèle d’hébergement.
    • Dans Blazor WebAssembly, beforeStart reçoit les options (optionsdans l’exemple de cette section) et toutes les Blazor WebAssembly extensions (extensionsdans l’exemple de cette section) ajoutées lors de la publication. Par exemple, les options peuvent spécifier l’utilisation d’un chargeur de ressources de démarrage personnalisé.
    • Dans Blazor Server, beforeStart reçoit les SignalR options de démarrage du circuit (options dans l’exemple de cette section).
    • Dans BlazorWebViews, aucune option n’est passée.
  • afterStarted: Appelé après Blazor est prêt à recevoir des appels à partir de JS. Par exemple, afterStarted permet d’initialiser des bibliothèques en effectuant JS des appels d’interopérabilité et en inscrivant des éléments personnalisés. L’instance Blazor est passée en afterStarted tant qu’argument (blazor dans l’exemple de cette section).

L’exemple suivant illustre JS les initialiseurs pour beforeStart et afterStarted. Pour le nom de fichier de l’exemple suivant :

  • Utilisez le nom d’assembly de l’application dans le nom de fichier si les JS initialiseurs sont consommés en tant que ressource statique dans le projet. Par exemple, nommez le fichier BlazorSample.lib.module.js d’un projet avec un nom d’assembly de BlazorSample. Placez le fichier dans le dossier de wwwroot l’application.
  • Utilisez le nom ou l’identificateur de package de la bibliothèque du projet si les JS initialiseurs sont consommés à partir d’une bibliothèque RCL. Par exemple, nommez le fichier RazorClassLibrary1.lib.module.js d’un RCL avec un identificateur de package de RazorClassLibrary1. Placez le fichier dans le dossier de wwwroot la bibliothèque.
export function beforeStart(options, extensions) {
    console.log("beforeStart");
}

export function afterStarted(blazor) {
    console.log("afterStarted");
}

Notes

Les applications MVC et Razor Pages ne chargent JS pas automatiquement les initialiseurs. Toutefois, le code du développeur peut inclure un script pour extraire le manifeste de l’application et déclencher la charge des JS initialiseurs.

Pour obtenir des exemples d’initialiseurs JS , consultez les ressources suivantes :

Notes

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Basculer des branches ou des balises . Pour plus d’informations, consultez Comment sélectionner une balise de version de ASP.NET Core code source (dotnet/AspNetCore.Docs #26205).

Emplacement de JavaScript

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

Avertissement

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

Notes

Les exemples de documentation placent généralement des scripts dans une <script> balise 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 JavaScript dans des modules JavaScript distincts qui peuvent être importés si nécessaire. Pour plus d’informations, consultez la section Isolation JavaScript dans les modules JavaScript .

Charger un script dans <head> le balisage

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

Placez les balises JavaScript () (JS<script>...</script>) dans le <head> balisage d’élément de wwwroot/index.html (Blazor WebAssembly) ou Pages/_Layout.cshtml (Blazor Server) :

<head>
    ...

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

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

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

Charger un script dans <body> le balisage

Placez les balises JavaScript () (JS<script>...</script>) à l’intérieur du balisage d’élément fermant </body> de wwwroot/index.html (Blazor WebAssembly) ou Pages/_Layout.cshtml (Blazor Server) :

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js"></script>
    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</body>

L’espace {webassembly|server} réservé dans le balisage précédent est webassembly soit pour une Blazor WebAssembly application () soit server pour une Blazor Server application (blazor.webassembly.jsblazor.server.js).

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

La colocation des fichiers JavaScript (JS) pour les pages, les vues et Razor les composants est un moyen pratique d’organiser des scripts dans une application.

Colocaliser JS des fichiers à l’aide des conventions d’extension de nom de fichier suivantes :

  • Pages d’applications pages et affichages d’applications Razor MVC : .cshtml.js. Exemples :
    • Pages/Index.cshtml.js pour la Index page d’une Razor application Pages à l’adresse Pages/Index.cshtml.
    • Views/Home/Index.cshtml.js pour l’affichage Index d’une application MVC à l’adresse Views/Home/Index.cshtml.
  • Razor composants d’applications Blazor : .razor.js. Exemple : Pages/Index.razor.js pour le Index composant à Pages/Index.razor.

Les fichiers colocalisés sont accessibles JS publiquement à l’aide du chemin d’accès au fichier dans le projet :

  • Pages, vues et composants à partir d’un fichier de scripts colocalisé dans l’application :

    {PATH}/{PAGE, VIEW, OR COMPONENT}.{EXTENSION}.js

    • L’espace {PATH} réservé est le chemin d’accès à la page, à l’affichage ou au composant.
    • L’espace {PAGE, VIEW, OR COMPONENT} réservé est la page, l’affichage ou le composant.
    • L’espace {EXTENSION} réservé correspond à l’extension de la page, de l’affichage ou du composant, razor soit cshtml.

    Razor Exemple de pages :

    Un JS fichier pour la Index page est placé dans le Pages dossier (Pages/Index.cshtml.js) en regard de la Index page (Pages/Index.cshtml). Dans la Index page, le script est référencé au chemin d’accès dans le Pages dossier :

    @section Scripts {
      <script src="~/Pages/Index.cshtml.js"></script>
    }
    

    Lorsque l’application est publiée, l’infrastructure déplace automatiquement le script vers la racine web. Dans l’exemple précédent, le script est déplacé vers bin\Release\{TARGET FRAMEWORK MONIKER}\publish\wwwroot\Pages\Index.cshtml.js, où l’espace {TARGET FRAMEWORK MONIKER} réservé est le Moniker (TFM) du Framework cible. Aucune modification n’est nécessaire à l’URL relative du script dans la Index page.

    Blazor Exemple:

    Un JS fichier pour le Index composant est placé dans le Pages dossier (Pages/Index.razor.js) en regard du Index composant (Pages/Index.razor). Dans le Index composant, le script est référencé au chemin d’accès du Pages dossier. L’exemple suivant est basé sur un exemple illustré dans les fonctions JavaScript d’appel à partir de méthodes .NET dans ASP.NET Core Blazor article.

    Pages/Index.razor.js:

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

    Dans la OnAfterRenderAsync méthode du Index composant (Pages/Index.razor) :

    module = await JS.InvokeAsync<IJSObjectReference>(
        "import", "./Pages/Index.razor.js");
    

    Lorsque l’application est publiée, l’infrastructure déplace automatiquement le script vers la racine web. Dans l’exemple précédent, le script est déplacé vers bin\Release\{TARGET FRAMEWORK MONIKER}\publish\wwwroot\Pages\Index.razor.js, où l’espace {TARGET FRAMEWORK MONIKER} réservé est le Moniker (TFM) du Framework cible. Aucune modification n’est requise pour l’URL relative du script dans le Index composant.

  • Pour les scripts fournis par une Razor bibliothèque de classes (RCL) :

    _content/{PACKAGE ID}/{PATH}/{PAGE, VIEW, OR COMPONENT}.{EXTENSION}.js

    • L’espace {PACKAGE ID} réservé est l’identificateur de package rcL (ou le nom de la bibliothèque d’une bibliothèque de classes référencée par l’application).
    • L’espace {PATH} réservé est le chemin d’accès à la page, à l’affichage ou au composant. Si un Razor composant se trouve à la racine du RCL, le segment de chemin n’est pas inclus.
    • L’espace {PAGE, VIEW, OR COMPONENT} réservé est la page, l’affichage ou le composant.
    • L’espace {EXTENSION} réservé correspond à l’extension de page, d’affichage ou de composant, razor soit cshtml.

    Dans l’exemple d’application suivant Blazor :

    • L’identificateur de package rcL est AppJS.
    • Les scripts d’un module sont chargés pour le Index composant (Index.razor).
    • Le Index composant se trouve dans le Pages dossier du RCL.
    var module = await JS.InvokeAsync<IJSObjectReference>("import", 
        "./_content/AppJS/Pages/Index.razor.js");
    

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

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

Placez les balises JavaScript (JS<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 Blazor script.

In wwwroot/index.html (Blazor WebAssembly) ou Pages/_Layout.cshtml (Blazor Server) :

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js"></script>
    <script src="{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

L’espace {webassembly|server} réservé dans le balisage précédent est webassembly soit pour une Blazor WebAssembly application () soit server pour une Blazor Server application (blazor.webassembly.jsblazor.server.js). L’espace {SCRIPT PATH AND FILE NAME (.js)} réservé est le chemin d’accès et le nom du fichier de script sous wwwroot.

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

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

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

  • Le segment de chemin du répertoire actuel (./) est requis pour créer le chemin d’accès de ressource statique correct au JS fichier.
  • L’espace {PACKAGE ID} réservé est l’ID de package de la bibliothèque. L’ID de package est défini par défaut sur le nom de l’assembly du projet s’il <PackageId> n’est pas spécifié dans le fichier projet.
  • L’espace {SCRIPT PATH AND FILENAME (.js)} réservé est le chemin d’accès et le nom de fichier sous wwwroot.
<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js"></script>
    <script src="./_content/{PACKAGE ID}/{SCRIPT PATH AND FILENAME (.js)}"></script>
</body>

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

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

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

Injecter un script après Blazor le démarrage

Chargez JS à partir d’un script injecté dans wwwroot/index.html (Blazor WebAssembly) ou Pages/_Layout.cshtml (Blazor Server) lorsque l’application est initialisée :

  • Ajoutez autostart="false" à la <script> balise qui charge le Blazor script.
  • Injectez un script dans le balisage d’élément <head> qui référence un fichier personnalisé JS après avoir commencé Blazor en appelant Blazor.start().then(...). Placez le script (<script>...</script>) à l’intérieur de la balise de fermeture </body> une fois le Blazor script chargé.

L’exemple suivant injecte le wwwroot/scripts.js fichier après Blazor le démarrage :

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" 
        autostart="false"></script>
    <script>
      Blazor.start().then(function () {
        var customScript = document.createElement('script');
        customScript.setAttribute('src', 'scripts.js');
        document.head.appendChild(customScript);
      });
    </script>
</body>

L’espace {webassembly|server} réservé dans le balisage précédent est webassembly soit pour une Blazor WebAssembly application () soit server pour une Blazor Server application (blazor.webassembly.jsblazor.server.js).

Pour plus d’informations sur le Blazor démarrage, consultez ASP.NET Core Blazor démarrage.

Isolation JavaScript dans les modules JavaScript

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

JS l’isolation offre les avantages suivants :

  • Importé JS ne pollue plus l’espace de noms global.
  • Les consommateurs d’une bibliothèque et de composants ne sont pas tenus d’importer les composants associés JS.

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

Fichiers JavaScript mis en cache

Les fichiers JavaScript (JS) et d’autres ressources statiques ne sont généralement pas mis en cache sur les clients pendant le développement dans l’environnementDevelopment. Au cours du développement, les demandes de ressources statiques incluent l’en-têteCache-Control avec une valeur de no-cache zéro ou max-age une valeur nulle (0).

Pendant la production dans l’environnementProduction, JS les fichiers sont généralement mis en cache par les clients.

Pour désactiver la mise en cache côté client dans les navigateurs, les développeurs adoptent généralement l’une des approches suivantes :

Pour plus d'informations, consultez les pages suivantes :

Une Blazor application peut appeler des fonctions JavaScript (JS) à partir de méthodes .NET et de méthodes .NET à partir de JS fonctions. Ces scénarios sont appelés interopérabilité JavaScript (JS interopérabilité).

Cet article de vue d’ensemble couvre les concepts généraux. D’autres JS conseils d’interopérabilité sont fournis dans les articles suivants :

Interaction avec le modèle objet document (DOM)

Mutez uniquement le modèle objet document (DOM) avec JavaScript (JS) lorsque l’objet n’interagit pas avec Blazor. Blazor gère les représentations du DOM et interagit directement avec les objets DOM. Si un élément rendu par Blazor est modifié en externe à l’aide JS directement ou via JS Interop, le DOM peut ne plus correspondre Blazorà la représentation interne, ce qui peut entraîner un comportement non défini. Le comportement non défini peut simplement interférer avec la présentation d’éléments ou leurs fonctions, mais peut également introduire des risques de sécurité pour l’application ou le serveur.

Cette aide s’applique non seulement à votre propre JS code d’interopérabilité, mais également à toutes JS les bibliothèques que l’application utilise, y compris tout ce qui est fourni par une infrastructure tierce, telle que Bootstrap JS et jQuery.

Dans quelques exemples de documentation, JS l’interopérabilité est utilisée pour muter un élément purement à des fins de démonstration dans le cadre d’un exemple. Dans ces cas, un avertissement apparaît dans le texte.

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

Appels JavaScript asynchrones

JS Les appels d’interopérabilité sont asynchrones par défaut, que le code appelé soit synchrone ou asynchrone. Les appels sont asynchrones par défaut pour s’assurer que les composants sont compatibles entre les Blazor modèles Blazor Server d’hébergement et Blazor WebAssembly. Sur Blazor Server, les appels d’interopérabilité doivent être asynchrones, JS car ils sont envoyés via une connexion réseau. Pour les applications qui adoptent exclusivement le Blazor WebAssembly modèle d’hébergement, les appels d’interopérabilité synchrone JS sont pris en charge.

Pour plus d’informations, consultez les articles suivants :

Sérialisation d’objets

Blazor utilise System.Text.Json pour la sérialisation avec les exigences et les comportements par défaut suivants :

  • Les types doivent avoir un constructeur par défaut, get/set les accesseurs doivent être publics et les champs ne sont jamais sérialisés.
  • La sérialisation par défaut globale n’est pas personnalisable pour éviter de briser les bibliothèques de composants existantes, les répercussions sur les performances et la sécurité et les réductions de fiabilité.
  • La sérialisation des noms de membres .NET entraîne des noms de clés ON en minuscules JS.
  • JSON est désérialisé en tant qu’instances JsonElement C#, ce qui autorise la casse mixte. Le cast interne pour l’affectation aux propriétés du modèle C# fonctionne comme prévu malgré les différences de cas entre JSles noms de clés ON et les noms de propriétés C#.

JsonConverter L’API est disponible pour la sérialisation personnalisée. Les propriétés peuvent être annotées avec un [JsonConverter] attribut pour remplacer la sérialisation par défaut pour un type de données existant.

Pour plus d’informations, consultez les ressources suivantes dans la documentation .NET :

JSLa prise en charge System.DateOnly du sérialiseur ON est System.TimeOnly prévue pour ASP.NET Core 7.0, qui est prévue pour la mise en production à la fin de 2022. Pour plus d’informations, consultez Support DateOnly et TimeOnly in JsonSerializer (dotnet/runtime #53539).

Blazor prend en charge l’interopérabilité nonmarshallée JS lorsqu’un volume élevé d’objets .NET est rapidement sérialisé ou quand des objets .NET volumineux ou de nombreux objets .NET doivent être sérialisés. Pour plus d’informations, consultez Appeler des fonctions JavaScript à partir de méthodes .NET dans ASP.NET Core Blazor.

Emplacement de JavaScript

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

Avertissement

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

Notes

Les exemples de documentation placent généralement des scripts dans une <script> balise 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 JavaScript dans des modules JavaScript distincts qui peuvent être importés si nécessaire. Pour plus d’informations, consultez la section Isolation JavaScript dans les modules JavaScript .

Charger un script dans <head> le balisage

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

Placez le script (<script>...</script>) dans le balisage d’élément <head> de wwwroot/index.html (Blazor WebAssembly) ou Pages/_Host.cshtml (Blazor Server) :

<head>
    ...

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

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

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

Charger un script dans <body> le balisage

Placez le script (<script>...</script>) à l’intérieur du balisage d’élément fermant </body> de wwwroot/index.html (Blazor WebAssembly) ou Pages/_Host.cshtml (Blazor Server) :

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js"></script>
    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</body>

L’espace {webassembly|server} réservé dans le balisage précédent est webassembly soit pour une Blazor WebAssembly application () soit server pour une Blazor Server application (blazor.webassembly.jsblazor.server.js).

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

Placez le script (<script>...</script>) avec un chemin de src script à l’intérieur de la balise de fermeture </body> après la référence de Blazor script.

In wwwroot/index.html (Blazor WebAssembly) ou Pages/_Host.cshtml (Blazor Server) :

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js"></script>
    <script src="{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

L’espace {webassembly|server} réservé dans le balisage précédent est webassembly soit pour une Blazor WebAssembly application () soit server pour une Blazor Server application (blazor.webassembly.jsblazor.server.js). L’espace {SCRIPT PATH AND FILE NAME (.js)} réservé est le chemin d’accès et le nom du fichier de script sous wwwroot.

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

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

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

  • Le segment de chemin du répertoire actuel (./) est requis pour créer le chemin d’accès de ressource statique correct au JS fichier.
  • L’espace {PACKAGE ID} réservé est l’ID de package de la bibliothèque. L’ID de package est défini par défaut sur le nom de l’assembly du projet s’il <PackageId> n’est pas spécifié dans le fichier projet.
  • L’espace {SCRIPT PATH AND FILENAME (.js)} réservé est le chemin d’accès et le nom de fichier sous wwwroot.
<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js"></script>
    <script src="./_content/{PACKAGE ID}/{SCRIPT PATH AND FILENAME (.js)}"></script>
</body>

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

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

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

Injecter un script après Blazor le démarrage

Chargez JS à partir d’un script injecté dans wwwroot/index.html (Blazor WebAssembly) ou Pages/_Host.cshtml (Blazor Server) lorsque l’application est initialisée :

  • Ajoutez autostart="false" à la <script> balise qui charge le Blazor script.
  • Injectez un script dans le balisage d’élément <head> qui référence un fichier personnalisé JS après avoir commencé Blazor en appelant Blazor.start().then(...). Placez le script (<script>...</script>) à l’intérieur de la balise de fermeture </body> une fois le Blazor script chargé.

L’exemple suivant injecte le wwwroot/scripts.js fichier après Blazor le démarrage :

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" 
        autostart="false"></script>
    <script>
      Blazor.start().then(function () {
        var customScript = document.createElement('script');
        customScript.setAttribute('src', 'scripts.js');
        document.head.appendChild(customScript);
      });
    </script>
</body>

L’espace {webassembly|server} réservé dans le balisage précédent est webassembly soit pour une Blazor WebAssembly application () soit server pour une Blazor Server application (blazor.webassembly.jsblazor.server.js).

Pour plus d’informations sur le Blazor démarrage, consultez ASP.NET Core Blazor démarrage.

Isolation JavaScript dans les modules JavaScript

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

JS l’isolation offre les avantages suivants :

  • Importé JS ne pollue plus l’espace de noms global.
  • Les consommateurs d’une bibliothèque et de composants ne sont pas tenus d’importer les composants associés JS.

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

Fichiers JavaScript mis en cache

Les fichiers JavaScript (JS) et d’autres ressources statiques ne sont généralement pas mis en cache sur les clients pendant le développement dans l’environnementDevelopment. Au cours du développement, les demandes de ressources statiques incluent l’en-têteCache-Control avec une valeur de no-cache zéro ou max-age une valeur nulle (0).

Pendant la production dans l’environnementProduction, JS les fichiers sont généralement mis en cache par les clients.

Pour désactiver la mise en cache côté client dans les navigateurs, les développeurs adoptent généralement l’une des approches suivantes :

Pour plus d'informations, consultez les pages suivantes :

Une Blazor application peut appeler des fonctions JavaScript (JS) à partir de méthodes .NET et de méthodes .NET à partir de JS fonctions. Ces scénarios sont appelés interopérabilité JavaScript (JS interopérabilité).

Cet article de vue d’ensemble couvre les concepts généraux. D’autres JS conseils d’interopérabilité sont fournis dans les articles suivants :

Interaction avec le modèle DOM (Document Object Model)

Mutez uniquement le modèle DOM (Document Object Model) avec JavaScript (JS) lorsque l’objet n’interagit pas avec Blazor. Blazor gère les représentations du DOM et interagit directement avec les objets DOM. Si un élément rendu par Blazor est modifié en externe à l’aide JS directement ou via JS Interop, le DOM peut ne plus correspondre Blazorà la représentation interne, ce qui peut entraîner un comportement non défini. Le comportement non défini peut simplement interférer avec la présentation d’éléments ou de leurs fonctions, mais peut également introduire des risques de sécurité pour l’application ou le serveur.

Ce guide s’applique non seulement à votre propre JS code d’interopérabilité, mais également à toutes les JS bibliothèques que l’application utilise, y compris tout ce qui est fourni par une infrastructure tierce, comme Bootstrap JS et jQuery.

Dans quelques exemples de documentation, JS l’interopérabilité est utilisée pour muter un élément purement à des fins de démonstration dans le cadre d’un exemple. Dans ce cas, un avertissement s’affiche dans le texte.

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

Appels JavaScript asynchrones

JS Les appels d’interopérabilité sont asynchrones par défaut, que le code appelé soit synchrone ou asynchrone. Les appels sont asynchrones par défaut pour s’assurer que les composants sont compatibles entre les Blazor deux modèles d’hébergement et Blazor ServerBlazor WebAssembly. Sur Blazor Server, JS les appels d’interopérabilité doivent être asynchrones, car ils sont envoyés via une connexion réseau. Pour les applications qui adoptent exclusivement le Blazor WebAssembly modèle d’hébergement, les appels d’interopérabilité synchrone JS sont pris en charge.

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

Sérialisation d’objets

Blazor utilise System.Text.Json pour la sérialisation avec les exigences et les comportements par défaut suivants :

  • Les types doivent avoir un constructeur par défaut, get/set les accesseurs doivent être publics et les champs ne sont jamais sérialisés.
  • La sérialisation par défaut globale n’est pas personnalisable pour éviter d’interrompre les bibliothèques de composants existantes, les impacts sur les performances et la sécurité et les réductions de fiabilité.
  • La sérialisation des noms de membres .NET entraîne des noms de clés ON minuscules JS.
  • JSON est désérialisé en tant qu’instances JsonElement C#, ce qui autorise la casse mixte. Le cast interne pour l’affectation aux propriétés du modèle C# fonctionne comme prévu malgré les différences de cas entre JSles noms de clés ON et les noms de propriétés C#.

JsonConverter L’API est disponible pour la sérialisation personnalisée. Les propriétés peuvent être annotées avec un [JsonConverter] attribut pour remplacer la sérialisation par défaut pour un type de données existant.

Pour plus d’informations, consultez les ressources suivantes dans la documentation .NET :

JSLa prise en charge du sérialiseur ON est System.DateOnlySystem.TimeOnly prévue pour ASP.NET Core 7.0, qui est prévue pour la publication d’ici la fin de 2022. Pour plus d’informations, consultez Support DateOnly et TimeOnly in JsonSerializer (dotnet/runtime #53539).

Emplacement de JavaScript

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

Avertissement

N’placez pas de <script> balise dans un Razor fichier de composant (.razor) car la <script> balise ne peut pas être mise à jour dynamiquement par Blazor.

Notes

Les exemples de documentation placent des scripts dans une <script> balise ou chargent des scripts globaux à partir de fichiers externes. Ces approches polluent le client avec des fonctions globales. Le placement de JavaScript dans des modules JavaScript distincts qui peuvent être importés si nécessaire n’est pas pris en charge dans Blazor les versions antérieures à ASP.NET Core 5.0. Si l’application nécessite l’utilisation de JS modules pour JS l’isolation, 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 l’isolation JavaScript dans la section modules JavaScript .

Charger un script dans <head> le balisage

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

Placez le script (<script>...</script>) dans le <head> balisage d’élément de wwwroot/index.html (Blazor WebAssembly) ou Pages/_Host.cshtml (Blazor Server) :

<head>
    ...

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

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

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

Charger un script dans <body> le balisage

Placez le script (<script>...</script>) à l’intérieur du balisage d’élément fermant </body> de wwwroot/index.html (Blazor WebAssembly) ou Pages/_Host.cshtml ()Blazor Server :

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js"></script>
    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</body>

L’espace {webassembly|server} réservé dans le balisage précédent est soit webassembly pour une Blazor WebAssembly application (blazor.webassembly.js) soit server pour une Blazor Server application (blazor.server.js).

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

Placez le script (<script>...</script>) avec un chemin de script src à l’intérieur de la balise de fermeture </body> après la référence de Blazor script.

In wwwroot/index.html (Blazor WebAssembly) ou Pages/_Host.cshtml (Blazor Server) :

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js"></script>
    <script src="{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

L’espace {webassembly|server} réservé dans le balisage précédent est soit webassembly pour une Blazor WebAssembly application (blazor.webassembly.js) soit server pour une Blazor Server application (blazor.server.js). L’espace {SCRIPT PATH AND FILE NAME (.js)} réservé est le chemin d’accès et le nom du fichier de script sous wwwroot.

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

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

Lorsque le fichier externe JS est fourni par une Razor bibliothèque de classes, spécifiez le fichier à l’aide JS de son chemin stable de ressources web statiques : ./_content/{PACKAGE ID}/{SCRIPT PATH AND FILENAME (.js)}

  • Le segment de chemin d’accès du répertoire actif (./) est requis pour créer le chemin d’accès de ressource statique approprié au JS fichier.
  • L’espace {PACKAGE ID} réservé est l’ID de package de la bibliothèque. L’ID de package est défini par défaut sur le nom de l’assembly du projet s’il <PackageId> n’est pas spécifié dans le fichier projet.
  • L’espace {SCRIPT PATH AND FILENAME (.js)} réservé est le chemin d’accès et le nom de fichier sous wwwroot.
<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js"></script>
    <script src="./_content/{PACKAGE ID}/{SCRIPT PATH AND FILENAME (.js)}"></script>
</body>

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

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

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

Injecter un script après Blazor le démarrage

Chargez JS à partir d’un script injecté dans wwwroot/index.html (Blazor WebAssembly) ou Pages/_Host.cshtml (Blazor Server) lorsque l’application est initialisée :

  • Ajoutez autostart="false" à la <script> balise qui charge le Blazor script.
  • Injectez un script dans le <head> balisage d’élément qui fait référence à un fichier personnalisé JS après avoir commencé Blazor par appeler Blazor.start().then(...). Placez le script (<script>...</script>) à l’intérieur de la balise de fermeture </body> une fois le Blazor script chargé.

L’exemple suivant injecte le wwwroot/scripts.js fichier après Blazor le démarrage :

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" 
        autostart="false"></script>
    <script>
      Blazor.start().then(function () {
        var customScript = document.createElement('script');
        customScript.setAttribute('src', 'scripts.js');
        document.head.appendChild(customScript);
      });
    </script>
</body>

L’espace {webassembly|server} réservé dans le balisage précédent est soit webassembly pour une Blazor WebAssembly application (blazor.webassembly.js) soit server pour une Blazor Server application (blazor.server.js).

Pour plus d’informations sur le Blazor démarrage, consultez ASP.NET Core Blazor démarrage.

Fichiers JavaScript mis en cache

Les fichiers JavaScript (JS) et d’autres ressources statiques ne sont généralement pas mis en cache sur les clients pendant le développement dans l’environnementDevelopment. Pendant le développement, les demandes de ressources statiques incluent l’en-têteCache-Control avec une valeur égale no-cache ou max-age égale à zéro (0).

Pendant la production dans l’environnementProduction, JS les fichiers sont généralement mis en cache par les clients.

Pour désactiver la mise en cache côté client dans les navigateurs, les développeurs adoptent généralement l’une des approches suivantes :

  • Désactivez la mise en cache lorsque la console des outils de développement du navigateur est ouverte. Vous trouverez des conseils dans la documentation des outils de développement de chaque mainteneur de navigateur :
  • Effectuez une actualisation manuelle du navigateur de n’importe quelle page web de l’application Blazor pour recharger JS les fichiers à partir du serveur. ASP.NET Core’intergiciel de mise en cache HTTP respecte toujours un en-tête de cache non valide Cache-Control envoyé par un client.

Pour plus d'informations, consultez les pages suivantes :