Interopérabilité de JavaScript avec Blazor
- 5 minutes
Blazor utilise des composants C# au lieu de JavaScript pour créer des pages web ou des sections HTML avec du contenu dynamique. Vous pouvez cependant utiliser l’interopérabilité JavaScript - Blazor (interopérabilité JS) pour appeler des bibliothèques JavaScript dans des applications Blazor et pour appeler des fonctions JavaScript depuis du code C# .NET.
Dans cette unité, vous découvrez comment appeler JavaScript depuis du code C# dans une page Blazor et comment appeler des méthodes C# depuis des fonctions JavaScript. Dans l’unité suivante, vous utilisez un composant d’alerte d’une bibliothèque JavaScript pour mettre à jour votre site web de livraison de pizzas Blazor.
Utiliser l’interopérabilité JavaScript - Blazor
Un composant Blazor classique utilise une disposition et une logique d’interface utilisateur pour rendre le HTML à l’exécution. Vous utilisez du code C# pour gérer des événements et d’autres aspects dynamiques d’une page qui interagissent avec l’utilisateur et avec des services externes. Dans de nombreux cas, vous n’avez pas besoin d’utiliser du code JavaScript. À la place, vous pouvez utiliser Blazor avec des bibliothèques .NET, qui fournissent de nombreuses fonctionnalités équivalentes.
Vous devez cependant parfois utiliser une bibliothèque JavaScript existante. Par exemple, certaines bibliothèques JavaScript open source effectuent le rendu des composants et gèrent des éléments d’interface utilisateur de manière spécialisée. Vous pouvez aussi disposer d’un code JavaScript testé et éprouvé, que vous voulez réutiliser au lieu de le convertir en C#.
Vous pouvez intégrer des bibliothèques JavaScript dans vos applications en utilisant l’interopérabilité JavaScript - Blazor, ou interopérabilité JS. Vous utilisez l’interopérabilité JS pour appeler des fonctions JavaScript depuis des méthodes .NET et pour appeler des méthodes .NET depuis des fonctions JavaScript. L’interopérabilité JS gère le marshaling des données et des références d’objet entre Blazor et JavaScript pour faciliter la transition entre les deux.
Chargement de code JavaScript dans une application Blazor
Vous ajoutez JavaScript à une application Blazor de la même façon que vous l’ajoutez à une application web HTML standard, en utilisant l’élément HTML <script>. Vous ajoutez la balise <script> après la balise <script src="_framework/blazor.*.js"></script> existante dans le fichier Pages/_Host.cshtml ou le fichier wwwroot/index.html, selon votre modèle d’hébergement Blazor. Pour plus d’informations, consultez Modèles d’hébergement Blazor ASP.NET Core.
Il est préférable de ne pas placer de scripts dans l’élément <head> de la page. Blazor contrôle seulement le contenu de l’élément <body> d’une page HTML : l’interopérabilité JS pourrait donc échouer si les scripts dépendent de Blazor. En outre, la page peut s’afficher plus lentement en raison du temps nécessaire à l’analyse du code JavaScript.
La balise <script> fonctionne comme dans une application web HTML. Vous pouvez écrire du code directement dans le corps de la balise, ou bien faire référence à un fichier JavaScript existant. Pour plus d’informations, consultez Interopérabilité JavaScript Blazor ASP.NET Core (interopérabilité JS) : emplacement de JavaScript.
Important
Placez les fichiers JavaScript dans le dossier wwwroot de votre projet Blazor.
Une autre option consiste à injecter dynamiquement l’élément <script> qui fait référence à un fichier JavaScript sur la page Pages/_Host.cshtml. Cette approche est utile si vous devez charger des scripts différents en fonction de conditions qui ne peuvent être déterminées qu’à l’exécution. Cette approche peut aussi accélérer le chargement initial de l’application si vous déclenchez la logique avec un événement qui se produit après le rendu d’une page. Pour plus d’informations, consultez Démarrage de Blazor ASP.NET Core.
Appel de JavaScript à partir de code .NET
Vous utilisez IJSRuntime pour appeler une fonction JavaScript à partir du code .NET. Pour rendre le runtime d’interopérabilité JS disponible, injectez une instance de l’abstraction IJSRuntime dans une page Blazor, après la directive @page située près du début du fichier.
L’interface IJSRuntime expose les méthodes InvokeAsync et InvokeVoidAsync pour appeler du code JavaScript. Utilisez InvokeAsync<TValue> pour appeler une fonction JavaScript qui retourne une valeur. Sinon, appelez InvokeVoidAsync. Comme les noms le suggèrent, les deux méthodes sont asynchrones : vous utilisez donc l’opérateur C# await pour capturer les résultats.
Le paramètre de la méthode InvokeAsync ou InvokeVoidAsync est le nom de la fonction JavaScript à appeler, suivi des arguments requis par la fonction. La fonction JavaScript doit faire partie de l’étendue de window ou d’une sous-étendue de window. Les arguments doivent être sérialisables au format JSON.
Notes
L’interopérabilité JS est disponible seulement quand l’application Blazor Server a établi une connexion SignalR avec le navigateur. Il n’est pas possible d’effectuer des appels d’interopérabilité tant que le rendu n’est pas terminé. Pour déterminer si le rendu est terminé, utilisez l’événement OnAfterRender ou OnAfterRenderAsync dans votre code Blazor.
Utiliser un objet ElementReference pour mettre à jour le modèle DOM
Blazor gère une représentation du modèle DOM (Document Object Model) sous la forme d’une arborescence de rendu virtuel. Lorsque la structure de la page change, Blazor génère une nouvelle arborescence de rendu qui contient les différences. Une fois les modifications terminées, Blazor itère dans les différences pour mettre à jour l’affichage par le navigateur de l’interface utilisateur et la version du navigateur du modèle DOM que JavaScript utilise.
De nombreuses bibliothèques JavaScript de tiers sont disponibles pour rendre des éléments sur une page, et ces bibliothèques peuvent mettre à jour le modèle DOM. Si votre code JavaScript modifie des éléments du modèle DOM, la copie Blazor du modèle DOM peut ne plus correspondre à l’état actuel. Cette situation peut provoquer un comportement inattendu et possiblement introduire des risques de sécurité. Il est important de ne pas apporter de modifications susceptibles d’endommager la vue Blazor du modèle DOM.
La façon la plus simple de gérer cette situation est de créer un élément d’espace réservé dans le composant Blazor, habituellement un élément <div @ref="placeHolder"></div> vide. Le code Blazor interprète ce code comme un espace vide, et l’arborescence de rendu Blazor n’essaie pas d’effectuer le suivi de son contenu. Vous pouvez librement ajouter des éléments de code JavaScript à ce <div>, et Blazor n’essaie pas de le modifier.
Le code de l’application Blazor définit un champ de type ElementReference pour contenir la référence à l’élément <div>. L’attribut @ref sur l’élément <div> définir la valeur du champ. L’objet ElementReference passe ensuite à une fonction JavaScript, qui peut utiliser la référence pour ajouter du contenu à l’élément <div>.
Appel de code .NET à partir de JavaScript
Le code JavaScript peut exécuter une méthode .NET définie par votre code Blazor en utilisant la classe utilitaire DotNet, qui fait partie de la bibliothèque d’interopérabilité JS. La classe DotNet expose les fonctions d’assistance invokeMethod et invokeMethodAsync. Utilisez invokeMethod pour exécuter une méthode et attendre le résultat, et invokeMethodAsync pour appeler la méthode de façon asynchrone. La méthode invokeMethodAsync retourne un élément JavaScript Promise.
Conseil
Pour conserver la réactivité de vos applications, définissez la méthode .NET comme async et appelez-la avec invokeMethodAsync depuis JavaScript.
Vous devez baliser la méthode .NET appelée avec le JSInvokableAttribute. La méthode doit être public, et tous les paramètres doivent être sérialisables au format JSON. En outre, pour une méthode asynchrone, le type de retour doit être void, Task ou un objet Task<T> générique, où T est un type sérialisable au format JSON.
Pour appeler une méthode static, vous fournissez le nom de l’assembly .NET contenant la classe, un identificateur pour la méthode, et les paramètres que la méthode accepte comme arguments des fonctions invokeMethod et invokeMethodAsync. Par défaut, l’identificateur de la méthode correspond à son nom, mais vous pouvez spécifier une autre valeur en utilisant l’attribut JSInvokable.
Appel d’une méthode d’instance .NET à partir de JavaScript
Pour exécuter une méthode d’instance, JavaScript a besoin d’une référence d’objet qui pointe vers l’instance. L’interopérabilité JS fournit le type DotNetObjectReference générique, que vous pouvez utiliser pour créer une référence d’objet dans le code .NET. Votre code doit rendre cette référence d’objet disponible pour JavaScript.
Le code JavaScript peut ensuite appeler invokeMethodAsync avec le nom de la méthode .NET et les paramètres requis par celle-ci. Pour éviter les fuites de mémoire, le code .NET doit supprimer la référence d’objet quand elle n’est plus nécessaire.