Appeler un code WinRT côté natif à partir du code côté web

Votre code JavaScript côté web peut accéder aux méthodes et propriétés WinRT natives, à l’aide de l’outil wv2winrt (l’outil de projection WebView2 WinRT JS). L’outil wv2winrt génère les fichiers de code nécessaires pour votre code JavaScript et permet d’utiliser les méthodes et propriétés de toutes les API WinRT, notamment :

  • API WinRT de votre application hôte WebView2.
  • API Windows WinRT.
  • API WinRT tierces.

Pour plus d’informations sur la raison pour laquelle vous souhaitez que votre code JavaScript côté web accède aux méthodes et propriétés de votre application hôte WinRT, voir la présentation de Appeler le code côté natif à partir du code côté web.

Pourquoi WinRT et .NET utilisent des approches différentes

Cet article concerne les API WinRT WebView2, pas les API WebView2 .NET. Le code C# de cet article va générer, mais pas exécuter, pour les API WebView2 .NET. Appeler AddHostObjectToScript à l’aide du code C# de cet article pour les API .NET WebView2 produirait un message d’erreur.

L’outil wv2winrt (l’outil de projection WebView2 WinRT JS) est nécessaire lors de la projection d’objets WinRT, car WinRT ne prend pas en charge IDispatch ou tout autre mécanisme pour inspecter et interagir dynamiquement avec les objets WinRT, ce que les plates-formes Win32 et .NET de WebView2 prennent en charge. Pour l’utilisation .NET de AddHostObjectToScript, consultez Appeler du code côté natif à partir du code côté web à la place de cet article.

Différences de configuration pour WinUI 3 et WinUI 2

Si votre application WinRT WebView2 cible WinUI 3 (SDK Windows App) plutôt que WinUI 2 (UWP), voici une vue d’ensemble des étapes spécifiques à WinUI 3 qui sont fournies ci-dessous :

  • Dans une application non empaquetée, vous devez effectuer les étapes supplémentaires décrites dans l’article « Amélioration des applications de bureau non empaquetées à l’aide de composants Windows Runtime ».

  • Ajouter WinRTAdapter à CsWinRTIncludes.

  • Pour les applications WinUI 3 (SDK Windows App), le projet d’application principal comporte une référence à WinAppSDK qui inclut directement sa propre copie des fichiers du SDK WebView2. Vous ne pouvez donc pas inclure une référence au SDK WebView2 dans le projet d’application principal sans produire de messages d’erreur.

  • La version de l’adaptateur de projet n’a pas besoin de correspondre.

  • Après avoir installé les options « par défaut » pour Visual Studio 2022 Community edition, dans Visual Studio Installer, cliquez sur la carte .NET, puis à droite, cochez la case Modèles C# du SDK de Windows App.

  • Si le modèle de projet correct n’apparaît toujours pas : dans le programme d’installation de Visual Studio Installer, cliquez sur la carte UWP pour la sélectionner, cochez la case outils C++ v143 à droite, puis cliquez sur le bouton Modifier.

Stratégie et objectif final de cet exemple

Stratégie

Cet article vous guide à travers les étapes principales suivantes :

  1. Créez un projet WinRTAdapter pour l’outil wv2winrt (l’outil de projection WebView2 WinRT JS).

  2. Pour cet exemple, spécifiez les API côté hôte suivantes pour la projection :

  3. Exécutez l’outil wv2winrt pour générer du code source C++/WinRT pour les espaces de noms ou les classes sélectionnés.

  4. Appelez AddHostObjectToScript dans votre projet WinUI principal.

  5. Appelez les méthodes et les propriétés sur l’objet hôte à partir de votre code JavaScript côté web (ou de la console DevTools).

Objectif final

Tout d’abord, nous allons choisir quelques API WinRT que nous souhaitons appeler à partir de code JavaScript. Pour cet exemple, nous allons utiliser la classe WinRT Language , qui se trouve dans l’espace de noms, pour les Windows.Globalization applications UWP Windows. La classe Windows.Globalization.Language permet d’obtenir des informations linguistiques à partir du système d’exploitation natif du client.

Dans l’application hôte WebView2, le code JavaScript côté web peut alors accéder aux méthodes et propriétés de l’objet Language qui se trouve dans le code côté natif.

Accéder aux API projetées via la console DevTools

À la fin de cet exemple de procédure, vous allez utiliser la console de Microsoft Edge DevTools pour tester la lecture de la propriété de l’hôte displayName de la Language classe :

const Windows = chrome.webview.hostObjects.sync.Windows;
(new Windows.Globalization.Language("en-US")).displayName;

La console DevTools affichera English (États-Unis)alors , ou le nom d’affichage d’un autre langage, démontrant que vous avez appelé du code côté natif à partir du code JavaScript côté web :

Utiliser la console DevTools pour tester l’appel de code côté natif à partir de code côté web

Vous pouvez également accéder aux membres de l’espace de noms Windows.System.UserProfile .

Accéder aux API projetées via des fichiers de code source

De même, dans les fichiers de code source plutôt que dans la console DevTools, vous pouvez accéder à l’objet hôte projeté. Tout d’abord, vous exécutez le code d’installation pour le script :

// early in setup code:
const Windows = chrome.webview.hostObjects.sync.Windows;

Ensuite, dans le corps principal de votre code, vous ajoutez des appels aux objets projetés, comme suit :

(new Windows.Globalization.Language("en-US")).displayName;

Vous pouvez également accéder aux membres de l’espace de noms Windows.System.UserProfile .

Mettons-nous au travail.

Étape 1 : Créer ou obtenir un projet WebView2 de base

Installer Visual Studio

  • Si Visual Studio 2015 ou version ultérieure n’est pas déjà installé, dans une fenêtre ou un onglet séparé, consultez Installer Visual Studio dans Configurer votre environnement de développement pour WebView2. Suivez les étapes de cette section, puis revenez à cette page et continuez les étapes ci-dessous. Le présent article présente des captures d’écran de Visual Studio Community Edition 2022.

Installer un canal d’aperçu de Microsoft Edge

  • Si un canal d’aperçu de Microsoft Edge (Beta, Dev ou Canary) n’est pas déjà installé, dans une fenêtre ou un onglet séparé, consultez Installer un canal d’aperçu de Microsoft Edge dans Configurer votre environnement de développement pour WebView2. Suivez les étapes de cette section, puis revenez à cette page et continuez les étapes ci-dessous.

Créer ou ouvrir un projet WebView2 de base

  1. Effectuez l’une des approches suivantes pour obtenir un projet de démarrage de base qui contient quelques lignes de code WebView2 qui incorpore le contrôle WebView2 :

  2. Sur votre disque local, ouvrez le .sln fichier que vous avez obtenu ci-dessus, tel que la solution de dépôt d’exemples :

    • <your-repos-directory>/WebView2Samples-main/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln
    • <your-repos-directory>/WebView2Samples/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln

    L’exemple de solution s’ouvre dans Visual Studio :

    Ajout d’un nouveau projet pour l’outil wv2winrt

  3. Dans Visual Studio, sélectionnez Déboguer>Démarrer le débogage. Cette opération génère le projet, puis exécute la version de base du projet. L’application de référence s’ouvre, comme la fenêtre MyUWPGetStartApp :

    Fenêtre d’exemple WebView2 WinUI 2 UWP

    L’illustration est une application WinUI 2 (UWP) à laquelle un contrôle WebView a été ajouté, défini pour accéder initialement à Bing.com. Il s’agit de l’application qui résulte des étapes de mise en route avec WebView2 dans les applications WinUI 2 (UWP).

  4. Fermez la fenêtre de l’application.

Étape 2 : Ajouter un projet WinRTAdapter pour l’outil wv2winrt

Ensuite, créez un projet WinRTAdapter pour l’outil wv2winrt (l’outil de projection WebView2 WinRT JS). Ce projet construit une bibliothèque à partir du code généré par l’exécution de l’outil. Ce code généré permet d’exposer les API WinRT dans le contrôle WebView2.

Ajoutez un projet pour l’outil wv2winrt , comme suit :

  1. Dans Visual Studio, ouvrez votre projet WinUI, à partir de l’étape précédente.

  2. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur la solution (et non sur le projet), puis sélectionnez Ajouter>un projet. La boîte de dialogue Ajouter un nouveau projet s’ouvre.

  3. Dans la zone de texte Rechercher, entrez le composant Windows Runtime (C++/WinRT).

    Autre approche : Si vous n’ajoutez pas de projet à l’aide du modèle de projet pour le composant Windows Runtime (C++/WinRT) comme décrit dans les étapes numérotées ci-dessous, vous devez installer à la place la charge de travail de développement de la plateforme Windows universelle, en suivant les étapes décrites dans Applications > UWP : Introduction à C++/WinRT.

  4. Sélectionnez la carte du composant Windows Runtime (C++/WinRT), puis cliquez sur le bouton Suivant :

    Sélection de la carte Composant Windows Runtime (C++/WinRT) dans la boîte de dialogue « Ajouter un nouveau projet »

    Remarque : Assurez-vous que le modèle inclut « C++/WinRT » dans son nom. Si ce modèle n’est pas répertorié, installez la charge de travail de développement de la plateforme Windows universelle à partir du programme d’installation de Visual Studio Installer. Si vous utilisez Visual Studio 2019 et que vous ne trouvez toujours pas le modèle, installez les modèles C++/WinRT et le visualiseur pour l’extension VS2019 à partir de Visual Studio > Extensions > Manage Extensions.

    La fenêtre Configurer votre nouveau projet s’ouvre.

Configuration et création du projet

  1. Dans la zone de texte Nom du projet , nommez le projet, en particulier WinRTAdapter. Remarque : Pour le moment, vous devez utiliser ce nom de projet spécifique.

    Dans la fenêtre 'Configurer votre nouveau projet', nommez le projet 'WinRTAdapter'

    Le chemin d’accès dans la capture d’écran ci-dessus reflète l’approche de clonage du dépôt d’échantillons.

  2. Cliquez sur le bouton Créer.

    La boîte de dialogue Nouveau projet Windows s’ouvre :

    Boîte de dialogue « Nouveau projet Windows »

  3. Cliquez sur le bouton OK .

    Le projet WinRTAdapter est créé et ajouté dans l’Explorateur de solutions en regard du projet principal :

    Le projet WinRTAdapter nouvellement créé

  4. Sélectionnez Fichier>,Enregistrer tout (Ctrl+Maj+S).

L’outil wv2winrt (l’outil de projection WebView2 WinRT JS) fonctionnera dans ce projet WinRTAdapter . Dans une étape ci-dessous, vous allez générer du code pour les classes sélectionnées dans ce projet.

Étape 3 : Installer la bibliothèque d’implémentation Windows, pour le projet WinRTAdapter

Dans le projet WinRTAdapter, installez la bibliothèque d’implémentation Windows (WIL), comme suit :

  1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet WinRTAdapter, puis sélectionnez Gérer les packages NuGet. La fenêtre Gestionnaire de package NuGet s’ouvre dans Visual Studio.

  2. Dans la fenêtre Gestionnaire de package NuGet , cliquez sur l’onglet Parcourir .

  3. Dans la fenêtre Gestionnaire de package NuGet, dans la zone de recherche, entrez Bibliothèque d’implémentation Windows, puis sélectionnez la carte Bibliothèque d’implémentation Windows :

    Gestionnaire de package NuGet, sélection du package « Bibliothèque d’implémentation Windows »

  4. Cliquez sur le bouton Installer . La boîte de dialogue Aperçu des modifications s’ouvre :

    La boîte de dialogue Aperçu des modifications pour WIL pour le projet WinRTAdapter

  5. Cliquez sur le bouton OK .

  6. Sélectionnez Fichier>,Enregistrer tout (Ctrl+Maj+S).

WIL est maintenant installé pour le projet WinRTAdapter . Windows Implementation Library (WIL) est une bibliothèque C++ d’en-tête uniquement destinée à faciliter l’utilisation du codage COM pour Windows. Il fournit des interfaces C++ lisibles et de type sécurisé pour les modèles de codage COM Windows.

Étape 4 : Installer le Kit de développement logiciel (SDK) WebView2 de préversion pour le projet WinRTAdapter

Dans le projet WinRTAdapter, installez également une version préliminaire du SDK WebView2, comme suit :

  1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet WinRTAdapter, puis sélectionnez Gérer les packages NuGet. La fenêtre Gestionnaire de package NuGet s’ouvre.

  2. Dans la fenêtre Gestionnaire de package NuGet , cliquez sur l’onglet Parcourir .

  3. Cochez la case Inclure la version préliminaire .

  4. Dans la zone de recherche , entrez WebView2.

  5. Cliquez sur la carte Microsoft.Web.WebView2. Les informations détaillées s’affichent au milieu de la fenêtre.

  6. Dans la liste déroulante Version , sélectionnez une version préliminaire du SDK WebView2 ou assurez-vous que l’option Dernière version est sélectionnée. La version doit être 1.0.1243.0 ou supérieure. Notez le numéro de version que vous sélectionnez.

    Gestionnaire de package NuGet, sélection du package WebView2 SDK pour le projet WinRTAdapter

  7. Cliquez sur le bouton Installer . La boîte de dialogue Aperçu des modifications s’ouvre :

    La boîte de dialogue Aperçu des modifications pour ajouter le SDK WebView2 au projet WinRTAdapter

  8. Cliquez sur le bouton OK .

  9. Sélectionnez Fichier>,Enregistrer tout (Ctrl+Maj+S).

La version préliminaire du SDK WebView2 est désormais installée pour le projet WinRTAdapter .

Étape 5 : Installer le Kit de développement logiciel (SDK) WebView2 (WinUI 2 uniquement)

Dans le projet principal, tel que MyUWPGetStartApp, installez la même version préliminaire du SDK WebView2 que celle que vous avez installée pour le projet WinRTAdapter , comme suit :

  1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet principal, tel que MyUWPGetStartApp, puis sélectionnez Gérer les packages NuGet. La fenêtre Gestionnaire de package NuGet s’ouvre.

  2. Cochez la case Inclure la version préliminaire .

  3. Sélectionnez l’onglet Parcourir .

  4. Dans la zone de recherche , entrez WebView2.

  5. Cliquez sur la carte Microsoft.Web.WebView2. Des informations détaillées s’affichent au milieu de la fenêtre.

  6. Dans la liste déroulante Version , sélectionnez une version préliminaire du SDK WebView2 ou assurez-vous que l’option Dernière version est sélectionnée. Assurez-vous d’utiliser la même version que celle utilisée par le projet WinRTAdapter ; pour les applications WinRT WebView2 qui ciblent WinUI 2 (UWP), il doit s’agir de la même version que pour le projet WinRTAdapter . La version doit être 1.0.1243.0 ou supérieure.

  7. Cliquez sur le bouton Installer . La boîte de dialogue Aperçu des modifications s’ouvre pour ajouter WebView2 au projet principal.

  8. Cliquez sur le bouton OK .

    Visual Studio devrait ressembler à la section Étape ci-dessus, sauf que le Gestionnaire de package NuGet est maintenant ouvert pour le projet principal au lieu du projet WinRTAdapter .

  9. Sélectionnez Fichier>,Enregistrer tout (Ctrl+Maj+S).

Le SDK de préversion WebView2 est maintenant installé pour le projet principal.

Étape 6 : Générer le code source pour les API hôtes sélectionnées

Ensuite, configurez l’outil wv2winrt (l’outil WebView2 WinRT JS Projection), pour incorporer les classes WinRT que vous souhaitez utiliser. Cela génère des fichiers sources qui seront ensuite compilés. La génération de code pour ces API permet à votre code JavaScript côté web d’appeler ces API.

Dans les étapes ci-dessous, nous allons spécifier deux Windows espaces de noms et l’outil wv2winrt génère le code source uniquement pour les API sous ces espaces de noms :

Plus tard, lorsque l’exemple d’application sera en cours d’exécution, vous appellerez ces API à partir de la console DevTools, pour démontrer que ces API côté hôte spécifiées peuvent être appelées à partir du code côté web.

Spécifiez l’espace de noms et la classe comme suit :

  1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet WinRTAdapter, puis sélectionnez Propriétés. La boîte de dialogue Pages de propriétés WinRTAdapter s’ouvre.

  2. Sur la gauche, développez et sélectionnez Propriétés> communesWebView2.

  3. Définissez Use WebView2 WinRT APIs to No. Cela permet au SDK WebView2 de ne pas copier le composant WebView2 WinRT dans la sortie du projet. Ce projet WinRTAdapter n’appelle aucune API WinRT WebView2, il n’a donc pas besoin du composant WinRT.

  4. Définir l’outil wv2winrt sur Oui.

  5. Définissez Utiliser la casse JavaScript sur Oui.

  6. Dans la ligne Inclure les filtres , cliquez sur la colonne de droite, cliquez sur le menu déroulant de cette cellule, puis cliquez sur Modifier. La boîte de dialogue Inclure des filtres s’ouvre.

  7. Dans la zone de texte la plus haute, collez les chaînes suivantes sur des lignes distinctes, sans espace blanc de début ou de fin :

    Windows.System.UserProfile
    Windows.Globalization.Language
    

    Boîte de dialogue Inclure des filtres

    Vous devez spécifier le nom complet des espaces de noms ou des classes, comme illustré ci-dessus.

  8. Cliquez sur le bouton OK pour fermer la boîte de dialogue Inclure les filtres .

  9. Assurez-vous que la boîte de dialogue Pages de propriétés WinRTAdapter ressemble à ce qui suit, pour cette procédure pas à pas :

    La boîte de dialogue « Pages de propriétés WinRTAdapter », avec « Propriétés > communes WebView2 » développée

  10. Cliquez sur le bouton OK pour fermer la boîte de dialogue Pages de propriétés .

  11. Sélectionnez Fichier>,Enregistrer tout (Ctrl+Maj+S).

Ajout d’une référence pointant vers le projet d’adaptateur

Ensuite, ajoutez une référence dans le projet principal, pointant vers le projet d’adaptateur.

Dans le projet principal, tel que MyUWPGetStartApp, ajoutez une référence qui pointe vers le projet WinRTAdapter , comme suit :

  1. Dans l’Explorateur de solutions, développez le projet principal, par exemple MyUWPGetStartApp, cliquez avec le bouton droit sur Références, puis sélectionnez Ajouter une référence. La boîte de dialogue Gestionnaire de références s’ouvre.

  2. Dans l’arborescence de gauche, sélectionnez Projets. Cochez la case WinRTAdapter :

    La case à cocher WinRTAdapter dans la boîte de dialogue Gestionnaire de références pour le projet principal

  3. Cliquez sur le bouton OK pour fermer la boîte de dialogue Gestionnaire de références .

  4. Sélectionnez Fichier>,Enregistrer tout (Ctrl+Maj+S).

Générer le code API

Ensuite, générez le code API :

  1. Cliquez avec le bouton droit sur le projet WinRTAdapter , puis sélectionnez Build.

    Le code source est généré pour les espaces de noms ou les classes que vous avez spécifiés dans la boîte de dialogue Inclure les filtres de l’outil wv2winrt (l’outil de projection WebView2 WinRT JS) :

    • Windows.System.UserProfile Espace de noms
    • Classe Windows.Globalization.Language
  2. Une fois la génération terminée, sélectionnez Fichier>Enregistrer tout (Ctrl+Maj+S).

Importante

Si vous avez installé une version finale du SDK WebView2 et que votre build échoue avec error MIDL2011: [msg]unresolved type declaration [context]: Microsoft.Web.WebView2.Core.ICoreWebView2DispatchAdapter [ RuntimeClass 'WinRTAdapter.DispatchAdapter' ], il s’agit d’un problème dans la version commerciale du SDK WebView2 et vous devrez changer Utiliser les API WebView2 WinRT en Oui dans les étapes ci-dessus.

Vous pouvez également ajouter ce qui suit après le dernier </ItemGroup> dans le fichier WinRTAdapter.vcxprojprojet :

<ItemGroup Condition="'$(WebView2UseDispatchAdapter)' == 'true'">
 <Reference Include="$(WebView2SDKPath)lib\Microsoft.Web.WebView2.Core.winmd">
   <!-- wv2winrt needs Dispatch Adapter metadata to generate code -->
 </Reference>
</ItemGroup>

Remplacez-le $(WebView2SDKPath) par le répertoire dans lequel le SDK WebView2 a été installé, avec un \ à la fin. Par exemple : ..\<sample-directory>\packages\Microsoft.Web.WebView2.1.0.1264.42\.

Étape 7 : Mettre à jour le framework cible (WinUI 3 uniquement)

Si votre application est destinée à WinUI 2 (UWP), ignorez cette étape.

Étape 8 : Ajouter l’objet hôte dans le projet principal

Ensuite, transmettez l’objet WinRT du côté natif de l’application hôte vers le côté web de l’application hôte. Pour ce faire, ajoutez une InitializeWebView2Async méthode qui appelle AddHostObjectToScript, comme suit :

  1. Dans Explorateur de solutions, développez le projet principal, par exemple MyUWPGetStartApp, développez MainPage.xaml, puis sélectionnez MainPage.xaml.cs.

  2. Sous le MainPage constructeur, ajoutez la méthode suivante InitializeWebView2Async :

    private async void InitializeWebView2Async()
    {
       await WebView2.EnsureCoreWebView2Async();
       var dispatchAdapter = new WinRTAdapter.DispatchAdapter();
       WebView2.CoreWebView2.AddHostObjectToScript("Windows", dispatchAdapter.WrapNamedObject("Windows", dispatchAdapter));
    }
    

    Cette méthode appelle AddHostObjectToScript.

    Dans la ligne AddHostObjectToScript("Windows", ..., Windows se trouve l’espace de noms de niveau supérieur. Si vous avez d’autres espaces de noms de niveau supérieur, vous pouvez ajouter des appels supplémentaires à , comme dans AddHostObjectToScriptl’exemple suivant :

    WebView2.CoreWebView2.AddHostObjectToScript("RuntimeComponent1", dispatchAdapter.WrapNamedObject("RuntimeComponent1", dispatchAdapter));
    

    L’appel WrapNamedObject crée un objet wrapper pour l’espace de RuntimeComponent1 noms. L’appel AddHostObjectToScript ajoute cet objet encapsulé au script en utilisant le nom RuntimeComponent1.

    Pour des instructions complètes sur l’utilisation des composants WinRT personnalisés, consultez Composants WinRT personnalisés (tiers), ci-dessous.

  3. Dans le MainPage constructeur, ci-dessous this.InitializeComponent();, ajoutez le code suivant :

    InitializeWebView2Async();
    
  4. Cliquez avec le bouton droit sur le projet principal, tel que MyUWPGetStartApp, puis sélectionnez Définir comme projet de démarrage. Gras indique un projet de démarrage.

  5. Sélectionnez Fichier>,Enregistrer tout (Ctrl+Maj+S).

  6. Appuyez sur F5 pour exécuter l’exemple d’application. L’application WinUI 2 (UWP) compatible WebView2 s’ouvre :

    Application WebView2 WinUI 2 UWP

Le code côté web de l’application hôte (et la console DevTools) peut désormais appeler des méthodes et des propriétés des espaces de noms ou des classes spécifiés de l’objet hôte.

Étape 9 : Appeler des méthodes et des propriétés sur l’objet hôte à partir d’un code JavaScript côté web

Accéder aux API projetées via la console DevTools

Ensuite, utilisez la console DevTools pour démontrer que le code côté web peut appeler les API côté hôte spécifiées dans l’outil wv2winrt (l’outil de projection WebView2 WinRT JS) :

  1. Si l’application n’est pas en cours d’exécution, dans Visual Studio, appuyez sur F5 pour exécuter l’exemple d’application.

  2. Cliquez dans la partie principale de la fenêtre de l’exemple d’application WebView2 pour lui donner le focus, puis appuyez sur Ctrl+Maj+I pour ouvrir Microsoft Edge DevTools. Ou cliquez avec le bouton droit sur la page, puis sélectionnez Inspecter.

    La fenêtre Microsoft Edge DevTools s’ouvre.

  3. Si la fenêtre DevTools de Microsoft Edge n’est pas affichée, appuyez sur Alt+Tab pour l’afficher.

  4. Dans la fenêtre DevTools , sélectionnez l’onglet Console .

  5. Cliquez sur le bouton Effacer la console (icône Effacer la console) ou cliquez avec le bouton droit dans la console , puis sélectionnez Effacer la console. Des messages peuvent apparaître régulièrement dans la console.

  6. Dans la console DevTools, collez le code de classe Windows.Globalization.Language suivant, puis appuyez sur Entrée :

    const Windows = chrome.webview.hostObjects.sync.Windows;
    (new Windows.Globalization.Language("en-US")).displayName;
    

    La console génère une chaîne de nom de langage, telle que English (États-Unis), démontrant que le code côté hôte (côté natif) de votre application peut être appelé à partir du code JavaScript côté web :

    Utilisation de la console DevTools pour tester l’appel de code côté natif à partir de code côté web

  7. Essayez d’omettre les parenthèses. Dans la console DevTools, entrez l’instruction suivante :

    new Windows.Globalization.Language("en-US").displayName;
    

    La console génère une chaîne de nom de langue, telle que English (États-Unis).

    Vous pouvez également accéder aux membres de l’espace de noms Windows.System.UserProfile .

  8. Fermez la fenêtre DevTools.

  9. Fermez l’application.

Félicitations ! Vous avez terminé l’exemple de démonstration de l’appel de code WinRT à partir de code JavaScript.

Accéder aux API projetées via des fichiers de code source

Ci-dessus, nous avons utilisé la console DevTools pour exécuter des instructions JavaScript qui accèdent à l’objet hôte projeté. De même, vous pouvez accéder à l’objet hôte projeté à partir de fichiers de code source. Pour ce faire, vous exécutez d’abord le code d’installation pour le script :

// early in setup code:
const Windows = chrome.webview.hostObjects.sync.Windows;

Ensuite, dans le corps principal de votre code, vous ajoutez des appels aux objets projetés, comme suit :

(new Windows.Globalization.Language("en-US")).displayName;

Vous pouvez également accéder aux Windows.System.UserProfile membres de l’API.

C’est la fin des étapes du didacticiel. Les sections suivantes sont des informations générales sur les applications WebView2 WinRT.

Composants WinRT personnalisés (tiers)

L’outil wv2winrt (l’outil de projection WebView2 WinRT JS) prend en charge les composants WinRT tiers personnalisés, en plus des API WinRT du système d’exploitation internes.

Composants WinRT tiers avec l’outil wv2winrt

Pour utiliser des composants WinRT personnalisés (tiers) avec l’outil wv2winrt , en plus des étapes ci-dessus, procédez également comme suit :

  1. Ajoutez un troisième projet (autre que votre application principale et votre projet WinRTAdapter) à votre solution Visual Studio qui implémente votre classe WinRT.

  2. Avoir le projet WinRTAdapter 'Ajouter une référence' à votre nouveau troisième projet contenant votre classe WinRT.

  3. Mettez à jour le filtre Inclure du projet WinRTAdapter dans les propriétés pour inclure également votre nouvelle classe.

  4. Ajoutez une ligne supplémentaire à InitializeWebView2Async pour ajouter l’espace de noms de votre classe WinRT :

    WebView2.CoreWebView2.AddHostObjectToScript("MyCustomNamespace", dispatchAdapter.WrapNamedObject("MyCustomNamespace", dispatchAdapter));

  5. Pour faciliter les appels de méthode à partir du web, ajoutez éventuellement votre proxy de synchronisation d’espace de noms en tant qu’objet global dans le script. Par exemple :

    window.MyCustomNamespace = chrome.webview.hostObjects.sync.MyCustomNamespace;

Pour obtenir un exemple, consultez l’exemple WebView2 suivant :

Méthodes WinRT asynchrones

En suivant les étapes du guide ci-dessus, vous devriez être en mesure d’utiliser des proxys synchrones. Pour les appels de méthode asynchrone, vous devez utiliser chrome.webview.hostObjects.options.forceAsyncMethodMatches.

La forceAsyncMethodMatches propriété est un tableau d’expressions régulières, où si une expression régulière correspond à un nom de méthode sur un proxy de synchronisation, la méthode sera exécutée de manière asynchrone à la place. La définition de cette valeur [/Async$/] correspondra à toute méthode se terminant par le suffixe Async. Ensuite, les appels de méthode correspondante fonctionnent comme une méthode sur un proxy asynchrone et retournent une promesse que vous pouvez attendre.

Exemple :

const Windows = chrome.webview.hostObjects.sync.Windows;
chrome.webview.hostObjects.options.forceAsyncMethodMatches = [/Async$/];

let result = await Windows.System.Launcher.launchUriAsync(new Windows.Foundation.Uri('https://contoso.com/'));

Pour plus d’informations, consultez la ligne dans la forceAsyncMethodMatchesméthode CoreWebView2.AddHostObjectToScript.

Abonnement aux événements WinRT

Les événements WinRT sont également exposés via les proxys de script. Vous pouvez ajouter et supprimer des gestionnaires d’événements d’instance WinRT et d’événements WinRT statiques à l’aide des addEventListener(string eventName, function handler) méthodes etremoveEventListener(string eventName, function handler).

Ces méthodes fonctionnent de la même manière que les méthodes DOM portant le même nom. Appelez addEventListener avec un nom de chaîne de l’événement WinRT que vous souhaitez abonner en tant que premier paramètre et un rappel de fonction à appeler chaque fois que l’événement est déclenché. L’appel removeEventListener avec les mêmes paramètres entraîne la désinscription de cet événement. Par exemple :

const Windows = chrome.webview.hostObjects.sync.Windows;
const coreApplication = Windows.ApplicationModel.Core.CoreApplication;
const coreApplicationView = coreApplication.getCurrentView();
const titleBar = coreApplicationView.titleBar;
titleBar.addEventListener('IsVisibleChanged', () => {
    console.log('titlebar visibility changed to: ' + titleBar.isVisible);
});

Pour un événement WinRT qui fournit des arguments d’événement, ceux-ci sont fournis en tant que premier paramètre de la fonction de gestionnaire d’événements. Par exemple, l’événement a IMapChangedEventArgs<string, object> l’objet Windows.Foundation.Collections.PropertySet.MapChanged événement arg et cet objet est fourni en tant que paramètre du rappel.

const Windows = chrome.webview.hostObjects.sync.Windows;
const propertySet = new Windows.Foundation.Collections.PropertySet();
propertySet.addEventListener('MapChanged', eventArgs => {
    const key = eventArgs.key;
    const collectionChange = eventArgs.collectionChange;
    // ...
});

L’objet event args aura en outre les propriétés suivantes :

Nom de la propriété Description
target L’objet qui a déclenché l’événement
type La chaîne de nom de l’événement
detail Tableau de tous les paramètres fournis au délégué WinRT

Faire en sorte que les proxys JavaScript AddHostObjectToScript agissent davantage comme les autres API JavaScript

AddHostObjectToScript utilise par défaut des proxys asynchrones et détaillés, mais vous pouvez faire en sorte que les proxys JavaScript agissent davantage comme d’autres AddHostObjectToScript API JavaScript. Pour en savoir plus sur AddHostObjectToScript son comportement par défaut, voir AddHostObjectToScript. En outre, si vous migrez une application hôte à partir d’une projection JavaScript WinRT dans des applications UWP JavaScript ou à partir de la vue web basée sur EdgeHTML, vous pouvez utiliser l’approche suivante, pour mieux correspondre à ce comportement précédent.

Pour que les AddHostObjectToScript proxys JavaScript agissent davantage comme les autres API JavaScript, définissez les propriétés suivantes :

  • chrome.webview.hostObjects.option.defaultSyncProxy - Les proxys peuvent être asynchrones ou synchrones. Normalement, nous savons, lors de l’appel d’une méthode sur un proxy synchrone, que le résultat doit également être un proxy synchrone. Mais dans certains cas, nous perdons ce contexte, par exemple lorsque nous fournissons une référence à une fonction au code natif, puis que le code natif appelle plus tard cette fonction. Dans ce cas, le proxy sera asynchrone, sauf si cette propriété est définie.

  • chrome.webview.hostObjects.options.forceAsyncMethodMatches - Il s’agit d’un tableau d’expressions régulières. Si vous appelez une méthode sur un proxy synchrone, l’appel de méthode sera en fait effectué de manière asynchrone si le nom de la méthode correspond à une chaîne ou à une expression régulière qui se trouve dans ce tableau. Définir cette valeur sur [/Async$/] fera de toute méthode qui se termine par Async un appel de méthode asynchrone. Si une méthode asynchrone ne correspond pas ici et n’est pas forcée d’être asynchrone, la méthode est appelée de manière synchrone, ce qui bloque l’exécution du code JavaScript appelant, puis renvoie la résolution de la promesse, au lieu de renvoyer une promesse.

  • chrome.webview.hostObjects.options.ignoreMemberNotFoundError - Si vous essayez d’obtenir la valeur d’une propriété d’un proxy, et que la propriété n’existe pas sur la classe native correspondante, vous obtiendrez une exception - à moins que vous ne définissiez cette propriété à true, auquel cas le comportement correspondra au comportement de projection Chakra WinRT (et au comportement général de JavaScript) et renverra undefined sans erreur.

La projection Chakra WinRT place les espaces de noms WinRT directement sur l’objet racine. En revanche :

  • AddHostObjectToScript Place les proxys racines asynchrones sur chrome.webview.hostObjects.
  • AddHostObjectToScript Place les proxys racine de synchronisation sur chrome.webview.hostObjects.sync.

Pour accéder aux proxys racine où le code de projection WinRT Chakra s’attendrait, vous pouvez affecter les emplacements de l’espace de noms WinRT du proxy racine à l’objet racine. Par exemple :

window.Windows = chrome.webview.hostObjects.sync.Windows;

Pour vous assurer que le JavaScript qui configure tout cela est exécuté avant toute autre chose, vous pouvez soit ajouter l’instruction ci-dessus à votre JavaScript, soit demander à WebView2 d’injecter l’instruction ci-dessus pour vous avant d’exécuter tout autre script, en utilisant la CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync méthode.

L’exemple suivant illustre les techniques décrites ci-dessus :

webview.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync(
            "(() => {" +
                    "if (chrome && chrome.webview) {" +
                        "console.log('Setting up WinRT projection options');" +
                        "chrome.webview.hostObjects.options.defaultSyncProxy = true;" +
                        "chrome.webview.hostObjects.options.forceAsyncMethodMatches = [/Async$/,/AsyncWithSpeller$/];" +
                        "chrome.webview.hostObjects.options.ignoreMemberNotFoundError = true;"  +
                        "window.Windows = chrome.webview.hostObjects.sync.Windows;" +
                    "}" +
                "})();");

Obtenir des informations sur les propriétés WebView2

Les informations sur les propriétés WebView2 sont disponibles à deux endroits :

  • Pages de propriétés du projet WinRTAdapter.
  • wv2winrt.exe Aide en ligne de commande. Il s’agit de l’outil wv2winrt (outil de projection WebView2 WinRT JS).

Pages de propriétés du projet WinRTAdapter

Dans les pages de propriétés du projet WinRTAdapter, pour obtenir de l’aide sur une propriété, cliquez sur une ligne de propriété. L’aide est affichée en bas de la boîte de dialogue :

Propriétés répertoriées dans les pages de propriétés WinRTAdapter

Aide en ligne de commande pour les propriétés wv2winrt.exe

L’aide wv2winrt.exe en ligne de commande donne des informations sur les paramètres de l’outil wv2winrt (l’outil de projection WebView2 WinRT JS). Par exemple :

Paramètre Description
verbose Répertoriez du contenu à standardiser, y compris les fichiers qui ont été créés et des informations sur les règles d’inclusion et d’exclusion.
include La liste ci-dessus exclut les espaces de noms et les classes d’exécution par défaut, à l’exception de ceux répertoriés. Les déclarations include peuvent être soit des espaces de noms qui incluent tout ce qui se trouve dans cet espace de noms, soit des noms de classe d’exécution pour inclure uniquement cette classe d’exécution.
use-javascript-case Modifie le code généré pour produire des noms de méthodes, des noms de propriétés, etc., qui utilisent le même style de casse que la projection Chakra JavaScript WinRT. La valeur par défaut consiste à produire des noms qui correspondent au winrt.
output-path Définit le chemin d’accès dans lequel les fichiers générés seront enregistrés.
output-namespace Définit l’espace de noms à utiliser pour la classe WinRT générée.
winmd-paths Une liste délimitée par des espaces de tous les fichiers winmd qui doivent être examinés pour la génération de code.

Voir aussi

Didacticiel et exemple :

Informations de référence sur l’API :

Article équivalent .NET :