Blazor Interopérabilité JavaScript (interopérabilité JS )

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 (interopérabilité )JS.

Cet article de présentation traite des concepts généraux. JSD’autres conseils sur l’interopérabilité sont fournis dans les articles suivants :

Interaction avec le Document Object Model (DOM)

Muter uniquement le Document Object Model (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 de directement ou par le biais de JS l’interopérabilité, le DOM peut ne plus correspondre à la Blazor représentation interne de, ce qui peut entraîner un comportement indéfini. Un comportement indéfini peut simplement interférer avec la présentation d’éléments ou de fonctions, mais il 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 un Framework tiers, comme bootstrap JS et jQuery.

Dans quelques exemples de documentation, l' JS interopérabilité est utilisée pour muter un élément exclusivement à 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 Interop 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 d’hébergement Blazor Server et Blazor WebAssembly . Sur Blazor Server , JS les appels Interop doivent être asynchrones, car ils sont envoyés via une connexion réseau. Pour les applications qui adoptent en mode exclusif le Blazor WebAssembly modèle d’hébergement, les JS appels Interop synchrones sont pris en charge. Pour plus d’informations, consultez ASP.NET Core Blazor meilleures pratiques en matière de performances.

Initialiseurs JavaScript

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

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

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

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

Le module exporte l’une des fonctions conventionnelles suivantes, ou les deux :

  • beforeStart(options, extensions): Appelé avant le Blazor démarrage de. Par exemple, beforeStart 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 Blazor WebAssembly Options ( options dans l’exemple de cette section) et toutes les extensions ( extensions dans 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émarragepersonnalisé.
    • Dans Blazor Server , beforeStart reçoit les SignalR options de démarrage de circuit ( options dans l’exemple de cette section).
    • Dans BlazorWebViews , aucune option n’est passée.
  • afterStarted: Appelé après que Blazor est prêt à recevoir des appels de js. Par exemple, afterStarted est utilisé pour initialiser les bibliothèques en effectuant des appels d’interopérabilité js et en inscrivant des éléments personnalisés. L' Blazor instance est passée à afterStarted en tant qu’argument ( blazor dans l’exemple de cette section).

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

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

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

Notes

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

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

Notes

la Documentation liens vers la source de référence ASP.NET Core charge la branche du référentiel main , qui représente le développement actuel de l’unité du produit pour la prochaine version de ASP.NET Core. Pour sélectionner la branche pour une version différente, utilisez la liste déroulante permuter les branches ou les balises pour sélectionner la branche. par exemple, sélectionnez la release/5.0 branche du ASP.NET Core version 5,0.

Emplacement de Direct2d

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

Avertissement

Ne 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 généralement des scripts dans une <script> balise ou des scripts globaux de chargement à 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 quand cela est nécessaire. Pour plus d’informations, consultez la section isolation JavaScript dans les modules JavaScript .

Charger un script dans le <head> 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 de l’élément wwwroot/index.html () Blazor WebAssembly ou Pages/_Layout.cshtml ( Blazor Server ) :

<head>
    ...

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

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

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

Charger un script dans le <body> balisage

Placez les JS balises JavaScript () ( <script>...</script> ) dans la </body> balise de fermeture de l’élément 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' {webassembly|server} espace réservé dans le balisage précédent est webassembly pour une Blazor WebAssembly application ( blazor.webassembly.js ) ou server pour une Blazor Server application ( blazor.server.js ).

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

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

Fichiers colocaliser JS utilisant les conventions d’extension de nom de fichier suivantes :

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

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

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

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

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

    Dans l’exemple suivant d’une Razor application pages, le script est colocalisé dans le Pages dossier avec la Contact page ( Pages/Contact.cshtml ) :

    @section Scripts {
      <script src="~/Pages/Contact.cshtml.js"></script>
    }
    
  • Pour les scripts fournis par une Razor bibliothèque de classes (RCL) :

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

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

    Dans l' Blazor exemple d’application suivant :

    • L’identificateur de package de 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 RCLs, consultez utiliser Razor des composants de ASP.NET Core à partir de Razor bibliothèques de classes .

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

Placez les balises JavaScript () JS ( <script>...</script> ) avec un chemin d’accès à la source du script () à l' src intérieur de la </body> balise de fermeture après la Blazor Référence du 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' {webassembly|server} espace réservé dans le balisage précédent est webassembly pour une Blazor WebAssembly application ( blazor.webassembly.js ) ou server pour une Blazor Server application ( blazor.server.js ). L' {SCRIPT PATH AND FILE NAME (.js)} espace réservé est le chemin d’accès et le nom du fichier de script sous wwwroot .

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

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

Lorsque le JS fichier externe est fourni par une Razor bibliothèque de classes, spécifiez le JS fichier à l’aide de son chemin d’accès à une ressource Web statique stable : ./_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 d’élément statique correct au JS fichier.
  • L' {PACKAGE ID} espace réservé est l' ID de packagede la bibliothèque. L’ID de package est par défaut le nom de l’assembly du projet si <PackageId> n’est pas spécifié dans le fichier projet.
  • L' {SCRIPT PATH AND FILENAME (.js)} espace 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 <script> balise précédente :

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

Pour plus d’informations, consultez utiliser Razor des composants de ASP.NET Core à partir de Razor bibliothèques de classes.

Injecter un script après le Blazor démarrage

Charger 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.
  • Injecter un script dans le <head> balisage de l’élément qui référence un JS fichier personnalisé après avoir démarré Blazor en appelant Blazor.start().then(...) . Placez le script ( <script>...</script> ) à l’intérieur de la </body> balise de fermeture après le Blazor chargement du script.

L’exemple suivant injecte le wwwroot/scripts.js fichier après le Blazor 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' {webassembly|server} espace réservé dans le balisage précédent est webassembly pour une Blazor WebAssembly application ( blazor.webassembly.js ) ou server pour une Blazor Server application ( blazor.server.js ).

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

Isolation JavaScript dans les modules JavaScript

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

JS l’isolation offre les avantages suivants :

  • Importée JS ne pollue plus l’espace de noms global.
  • Les consommateurs d’une bibliothèque et de composants ne sont pas requis pour importer le associé 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

JSLes fichiers JavaScript () et autres ressources statiques ne sont généralement pas mis en cache sur les clients lors du développement dans l' Development environnement. Pendant le développement, les demandes d’actifs statiques incluent l' Cache-Control en-tête avec une valeur no-cache ou max-age avec une valeur de zéro ( 0 ).

Pendant la production dans l' Production environnement, les JS 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 outils de développement du navigateur est ouverte. Vous trouverez des conseils dans la documentation des outils de développement de chaque chargé de maintenance de navigateur :
  • Effectuez une actualisation manuelle du navigateur de n’importe quelle page Web de l' Blazor application pour recharger JS les fichiers à partir du serveur. l’intergiciel (middleware) de mise en cache HTTP de ASP.NET Core honore toujours un Cache-Control en-tête non-cache valide envoyé par un client.

Pour plus d’informations, consultez :

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 (interopérabilité )JS.

Cet article de présentation traite des concepts généraux. JSD’autres conseils sur l’interopérabilité sont fournis dans les articles suivants :

Interaction avec le Document Object Model (DOM)

Muter uniquement le Document Object Model (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 de directement ou par le biais de JS l’interopérabilité, le DOM peut ne plus correspondre à la Blazor représentation interne de, ce qui peut entraîner un comportement indéfini. Un comportement indéfini peut simplement interférer avec la présentation d’éléments ou de fonctions, mais il 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 un Framework tiers, comme bootstrap JS et jQuery.

Dans quelques exemples de documentation, l' JS interopérabilité est utilisée pour muter un élément exclusivement à 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 Interop 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 d’hébergement Blazor Server et Blazor WebAssembly . Sur Blazor Server , JS les appels Interop doivent être asynchrones, car ils sont envoyés via une connexion réseau. Pour les applications qui adoptent en mode exclusif le Blazor WebAssembly modèle d’hébergement, les JS appels Interop synchrones sont pris en charge. Pour plus d’informations, consultez ASP.NET Core Blazor meilleures pratiques en matière de performances.

Emplacement de Direct2d

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

Avertissement

Ne 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 généralement des scripts dans une <script> balise ou des scripts globaux de chargement à 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 quand cela est nécessaire. Pour plus d’informations, consultez la section isolation JavaScript dans les modules JavaScript .

Charger un script dans le <head> balisage

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

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

<head>
    ...

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

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

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

Charger un script dans le <body> balisage

Placez le script ( <script>...</script> ) à l’intérieur </body> de la balise de fermeture de l’élément 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' {webassembly|server} espace réservé dans le balisage précédent est webassembly pour une Blazor WebAssembly application ( blazor.webassembly.js ) ou server pour une Blazor Server application ( blazor.server.js ).

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

Placez le script ( <script>...</script> ) avec un src chemin d’accès de script à l’intérieur de la </body> balise de fermeture après la Blazor référence de 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' {webassembly|server} espace réservé dans le balisage précédent est webassembly pour une Blazor WebAssembly application ( blazor.webassembly.js ) ou server pour une Blazor Server application ( blazor.server.js ). L' {SCRIPT PATH AND FILE NAME (.js)} espace réservé est le chemin d’accès et le nom du fichier de script sous wwwroot .

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

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

Lorsque le JS fichier externe est fourni par une Razor bibliothèque de classes, spécifiez le JS fichier à l’aide de son chemin d’accès à une ressource Web statique stable : ./_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 d’élément statique correct au JS fichier.
  • L' {PACKAGE ID} espace réservé est l' ID de packagede la bibliothèque. L’ID de package est par défaut le nom de l’assembly du projet si <PackageId> n’est pas spécifié dans le fichier projet.
  • L' {SCRIPT PATH AND FILENAME (.js)} espace 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 <script> balise précédente :

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

Pour plus d’informations, consultez utiliser Razor des composants de ASP.NET Core à partir de Razor bibliothèques de classes.

Injecter un script après le Blazor démarrage

Charger 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.
  • Injecter un script dans le <head> balisage de l’élément qui référence un JS fichier personnalisé après avoir démarré Blazor en appelant Blazor.start().then(...) . Placez le script ( <script>...</script> ) à l’intérieur de la </body> balise de fermeture après le Blazor chargement du script.

L’exemple suivant injecte le wwwroot/scripts.js fichier après le Blazor 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' {webassembly|server} espace réservé dans le balisage précédent est webassembly pour une Blazor WebAssembly application ( blazor.webassembly.js ) ou server pour une Blazor Server application ( blazor.server.js ).

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

Isolation JavaScript dans les modules JavaScript

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

JS l’isolation offre les avantages suivants :

  • Importée JS ne pollue plus l’espace de noms global.
  • Les consommateurs d’une bibliothèque et de composants ne sont pas requis pour importer le associé 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

JSLes fichiers JavaScript () et autres ressources statiques ne sont généralement pas mis en cache sur les clients lors du développement dans l' Development environnement. Pendant le développement, les demandes d’actifs statiques incluent l' Cache-Control en-tête avec une valeur no-cache ou max-age avec une valeur de zéro ( 0 ).

Pendant la production dans l' Production environnement, les JS 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 outils de développement du navigateur est ouverte. Vous trouverez des conseils dans la documentation des outils de développement de chaque chargé de maintenance de navigateur :
  • Effectuez une actualisation manuelle du navigateur de n’importe quelle page Web de l' Blazor application pour recharger JS les fichiers à partir du serveur. l’intergiciel (middleware) de mise en cache HTTP de ASP.NET Core honore toujours un Cache-Control en-tête non-cache valide envoyé par un client.

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 (interopérabilité )JS.

Cet article de présentation traite des concepts généraux. JSD’autres conseils sur l’interopérabilité sont fournis dans les articles suivants :

Interaction avec le Document Object Model (DOM)

Muter uniquement le Document Object Model (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 de directement ou par le biais de JS l’interopérabilité, le DOM peut ne plus correspondre à la Blazor représentation interne de, ce qui peut entraîner un comportement indéfini. Un comportement indéfini peut simplement interférer avec la présentation d’éléments ou de fonctions, mais il 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 un Framework tiers, comme bootstrap JS et jQuery.

Dans quelques exemples de documentation, l' JS interopérabilité est utilisée pour muter un élément exclusivement à 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 Interop 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 d’hébergement Blazor Server et Blazor WebAssembly . Sur Blazor Server , JS les appels Interop doivent être asynchrones, car ils sont envoyés via une connexion réseau. Pour les applications qui adoptent en mode exclusif le Blazor WebAssembly modèle d’hébergement, les JS appels Interop synchrones sont pris en charge. Pour plus d’informations, consultez ASP.NET Core Blazor meilleures pratiques en matière de performances.

Emplacement de Direct2d

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

Avertissement

Ne 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 fait de placer javascript dans des modules javascript distincts qui peuvent être importés en cas de besoin n’est pas pris en charge dans les Blazor versions antérieures à ASP.NET Core 5,0. si l’application requiert l’utilisation de JS modules pour l' JS isolation, nous vous recommandons d’utiliser ASP.NET Core 5,0 ou une 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 consultez la section isolation JavaScript dans les modules JavaScript .

Charger un script dans le <head> balisage

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

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

<head>
    ...

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

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

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

Charger un script dans le <body> balisage

Placez le script ( <script>...</script> ) à l’intérieur </body> de la balise de fermeture de l’élément 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' {webassembly|server} espace réservé dans le balisage précédent est webassembly pour une Blazor WebAssembly application ( blazor.webassembly.js ) ou server pour une Blazor Server application ( blazor.server.js ).

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

Placez le script ( <script>...</script> ) avec un src chemin d’accès de script à l’intérieur de la </body> balise de fermeture après la Blazor référence de 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' {webassembly|server} espace réservé dans le balisage précédent est webassembly pour une Blazor WebAssembly application ( blazor.webassembly.js ) ou server pour une Blazor Server application ( blazor.server.js ). L' {SCRIPT PATH AND FILE NAME (.js)} espace réservé est le chemin d’accès et le nom du fichier de script sous wwwroot .

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

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

Lorsque le JS fichier externe est fourni par une Razor bibliothèque de classes, spécifiez le JS fichier à l’aide de son chemin d’accès à une ressource Web statique stable : ./_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 d’élément statique correct au JS fichier.
  • L' {PACKAGE ID} espace réservé est l' ID de packagede la bibliothèque. L’ID de package est par défaut le nom de l’assembly du projet si <PackageId> n’est pas spécifié dans le fichier projet.
  • L' {SCRIPT PATH AND FILENAME (.js)} espace 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 <script> balise précédente :

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

Pour plus d’informations, consultez utiliser Razor des composants de ASP.NET Core à partir de Razor bibliothèques de classes.

Injecter un script après le Blazor démarrage

Charger 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.
  • Injecter un script dans le <head> balisage de l’élément qui référence un JS fichier personnalisé après avoir démarré Blazor en appelant Blazor.start().then(...) . Placez le script ( <script>...</script> ) à l’intérieur de la </body> balise de fermeture après le Blazor chargement du script.

L’exemple suivant injecte le wwwroot/scripts.js fichier après le Blazor 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' {webassembly|server} espace réservé dans le balisage précédent est webassembly pour une Blazor WebAssembly application ( blazor.webassembly.js ) ou server pour une Blazor Server application ( blazor.server.js ).

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

Fichiers JavaScript mis en cache

JSLes fichiers JavaScript () et autres ressources statiques ne sont généralement pas mis en cache sur les clients lors du développement dans l' Development environnement. Pendant le développement, les demandes d’actifs statiques incluent l' Cache-Control en-tête avec une valeur no-cache ou max-age avec une valeur de zéro ( 0 ).

Pendant la production dans l' Production environnement, les JS 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 outils de développement du navigateur est ouverte. Vous trouverez des conseils dans la documentation des outils de développement de chaque chargé de maintenance de navigateur :
  • Effectuez une actualisation manuelle du navigateur de n’importe quelle page Web de l' Blazor application pour recharger JS les fichiers à partir du serveur. l’intergiciel (middleware) de mise en cache HTTP de ASP.NET Core honore toujours un Cache-Control en-tête non-cache valide envoyé par un client.

Pour plus d’informations, consultez :