Freigeben über

Aufrufen von systemeigenem WinRT-Code aus webseitigem Code

  • Artikel

Ihr webseitiger JavaScript-Code kann mit Hilfe des wv2winrt-Tools (WebView2 WinRT JS Projection Tool) auf native WinRT-Methoden und -Eigenschaften zugreifen. Das wv2winrt-Tool generiert die erforderlichen Codedateien für Ihren JavaScript-Code und ermöglicht die Verwendung von Methoden und Eigenschaften beliebiger WinRT-APIs, einschließlich:

  • WinRT-APIs Ihrer WebView2-Host-App.
  • Windows WinRT-APIs.
  • WinRT-APIs von Drittanbietern.

Weitere Informationen dazu, warum Ihr webseitiger JavaScript-Code auf die Methoden und Eigenschaften Ihrer WinRT-Host-App zugreifen soll, finden Sie in der Einführung von Aufrufen von nativem Code aus webseitigem Code.

Warum WinRT und .NET unterschiedliche Ansätze verwenden

Dieser Artikel gilt für WinRT WebView2-APIs, nicht für .NET WebView2-APIs. Der C#-Code in diesem Artikel wird für .NET WebView2-APIs erstellt, aber nicht ausgeführt. Das Aufrufen AddHostObjectToScript mit dem C#-Code dieses Artikels für .NET WebView2-APIs würde eine Fehlermeldung erzeugen.

Das wv2winrt-Tool (das WebView2 WinRT JS-Projektionstool) wird beim Projizieren von WinRT-Objekten benötigt, da WinRT keine anderen Mechanismen unterstützt IDispatch , um WinRT-Objekte dynamisch zu untersuchen und mit winRT-Objekten zu interagieren, die die Win32- und .NET-Plattformen von WebView2 unterstützen. Informationen zur Verwendung von .NET finden Sie unter Aufrufen von nativem Code aus webseitigem Code anstelle dieses Artikels.AddHostObjectToScript

Unterschiede beim Einrichten von WinUI 3 und WinUI 2

Wenn Ihre WinRT WebView2-App auf WinUI 3 (Windows App SDK) und nicht auf WinUI 2 (UWP) abzielt, finden Sie hier eine Übersicht über die WinUI 3-spezifischen Schritte, die weiter unten beschrieben werden:

  • In einer nicht gepackten App müssen Sie zusätzliche Schritte ausführen, die im Artikel "Verbessern von nicht gepackten Desktop-Apps mit Windows-Runtime-Komponenten" aufgeführt sind.

  • Fügen Sie zu hinzu WinRTAdapterCsWinRTIncludes.

  • Für WinUI 3-Apps (Windows App SDK) verfügt das Standard-App-Projekt über einen Verweis auf WinAppSDK, der direkt eine eigene Kopie der WebView2 SDK-Dateien enthält, sodass Sie keinen Verweis auf das WebView2 SDK in das Standard App-Projekt einschließen können, ohne Fehlermeldungen zu erzeugen.

  • Die Projektadapterversion muss nicht übereinstimmen.

  • Klicken Sie nach der Installation der Standardoptionen für Visual Studio 2022 Community Edition in Visual Studio-Installer auf die .NET-Karte, und aktivieren Sie dann auf der rechten Seite das Kontrollkästchen Windows App SDK C#-Vorlagen.

  • Wenn die richtige Projektvorlage immer noch nicht angezeigt wird: Klicken Sie im Visual Studio-Installer auf die UWP-Karte, um sie auszuwählen, aktivieren Sie das Kontrollkästchen v143 C++-Tools auf der rechten Seite, und klicken Sie dann auf die Schaltfläche Ändern.

Strategie und Endziel dieses Beispiels

Strategie

Dieser Artikel führt Sie durch die folgenden Standard Schritte:

  1. Erstellen Sie ein WinRTAdapter-Projekt für das wv2winrt-Tool (webView2 WinRT JS Projection Tool).

  2. Geben Sie für dieses Beispiel die folgenden hostseitigen APIs für die Projektion an:

  3. Führen Sie das wv2winrt-Tool aus, um C++/WinRT-Quellcode für die ausgewählten Namespaces oder Klassen zu generieren.

  4. Rufen Sie AddHostObjectToScript in Ihrem Standard WinUI-Projekt auf.

  5. Rufen Sie Methoden und Eigenschaften für das Hostobjekt aus Ihrem webseitigen JavaScript-Code (oder über die DevTools-Konsole) auf.

Endziel

Zunächst wählen wir einige WinRT-APIs aus, die wir aus JavaScript-Code aufrufen möchten. In diesem Beispiel verwenden wir die WinRT-Klasse Language , die Windows.Globalization sich im -Namespace befindet, für Windows-UWP-Anwendungen. Die Windows.Globalization.Language-Klasse ermöglicht das Abrufen von Sprachinformationen vom nativen Betriebssystem des Clients.

In der WebView2-Host-App kann der webseitige JavaScript-Code dann auf Methoden und Eigenschaften des Language Objekts zugreifen, das sich im nativen Code befindet.

Zugreifen auf projizierte APIs über die DevTools-Konsole

Am Ende dieser exemplarischen Vorgehensweise verwenden Sie die Konsole von Microsoft Edge DevTools, um das Lesen der Hosteigenschaft displayName der Language -Klasse zu testen:

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

Die DevTools-Konsole gibt dann oder einen anderen Anzeigenamen der Sprache aus English (United States), um zu veranschaulichen, dass Sie nativen Code aus webseitigem JavaScript-Code aufgerufen haben:

Verwenden der DevTools-Konsole zum Testen des Aufrufens von nativem Code aus webseitigem Code

Auf ähnliche Weise können Sie auf Windows.System.UserProfile Namespace-Member zugreifen.

Zugreifen auf projizierte APIs über Quellcodedateien

Ebenso können Sie in Quellcodedateien und nicht in der DevTools-Konsole auf das projizierte Hostobjekt zugreifen. Führen Sie zunächst Setupcode für das Skript aus:

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

Anschließend fügen Sie im Standard Textkörper Ihres Codes Aufrufe zu projizierten Objekten hinzu, wie im Folgenden gezeigt:

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

Auf ähnliche Weise können Sie auf Windows.System.UserProfile Namespace-Member zugreifen.

Los geht's!

Schritt 1: Erstellen oder Abrufen eines einfachen WebView2-Projekts

Installieren von Visual Studio

  • Wenn Visual Studio 2015 oder höher noch nicht installiert ist, finden Sie in einem separaten Fenster oder einer separaten Registerkarte weitere Informationen unter Installieren von Visual Studio unter Einrichten Ihrer Entwicklungsumgebung für WebView2. Führen Sie die Schritte in diesem Abschnitt aus, kehren Sie dann zu dieser Seite zurück, und fahren Sie mit den folgenden Schritten fort. Der vorliegende Artikel enthält Screenshots für Visual Studio Community Edition 2022.

Installieren eines Vorschaukanals von Microsoft Edge

  • Wenn noch kein Vorschaukanal von Microsoft Edge (Beta, Dev oder Canary) in einem separaten Fenster oder einer separaten Registerkarte installiert ist, finden Sie weitere Informationen unter Installieren eines Vorschaukanals von Microsoft Edge unter Einrichten Ihrer Entwicklungsumgebung für WebView2. Führen Sie die Schritte in diesem Abschnitt aus, kehren Sie dann zu dieser Seite zurück, und fahren Sie mit den folgenden Schritten fort.

Erstellen oder Öffnen eines einfachen WebView2-Projekts

  1. Führen Sie einen der folgenden Ansätze aus, um ein Baselinestartprojekt zu erhalten, das ein paar Zeilen WebView2-Code enthält, der das WebView2-Steuerelement einbettet:

    • Verwenden Sie die bereitgestellte Basisbeispiellösung: Falls noch nicht geschehen, klonen Sie das Repository, oder laden Sie es WebView2Samples auf Ihr lokales Laufwerk herunter. In einem separaten Fenster oder einer separaten Registerkarte finden Sie weitere Informationen unter Herunterladen des WebView2Samples-Repositorys unter Einrichten Ihrer Entwicklungsumgebung für WebView2. Führen Sie die Schritte in diesem Abschnitt aus, kehren Sie dann zu dieser Seite zurück, und fahren Sie weiter unten fort. Bei diesem Ansatz wird Ihre lokale Kopie von https://github.com/MicrosoftEdge/WebView2Samples/tree/main/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.slnverwendet.

    • Verwenden Sie eine Projektvorlage in Visual Studio, um eine einfache UWP-App zu erstellen und ein WebView2-Steuerelement hinzuzufügen: Führen Sie die Schritte unter Erste Schritte mit WebView2 in WinUI 2-Apps (UWP) aus, um ein Baselinestartprojekt zu erstellen, das einige WebView2-Codezeilen enthält, die das WebView2-Steuerelement einbetten.

    • Verwenden Sie Ihre vorhandene Codebasis: Wenn Sie bereits über eine eigene App-Codebasis verfügen, können Sie dieses Projekt in Visual Studio öffnen.

  2. Öffnen Sie auf Ihrem lokalen Laufwerk die .sln Datei, die Sie oben abgerufen haben, z. B. die Beispielrepositorylösung:

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

    Die Beispielprojektmappe wird in Visual Studio geöffnet:

    Hinzufügen eines neuen Projekts für das wv2winrt-Tool

  3. Wählen Sie in Visual Studio Debuggen>Debuggen starten aus. Dadurch wird das Projekt erstellt und dann die Baselineversion des Projekts ausgeführt. Die Baseline-App wird geöffnet, z. B. das Fenster MyUWPGetStartApp :

    WebView2 WinUI 2 UWP-Beispielfenster

    Es wird eine WinUI 2-App (UWP) angezeigt, die ein WebView-Steuerelement hinzugefügt hat, das auf die anfängliche Navigation zu Bing.com festgelegt ist. Dies ist die App, die sich aus den Schritten unter Erste Schritte mit WebView2 in WinUI 2-Apps (UWP) ergibt.

  4. Schließen Sie das App-Fenster.

Schritt 2: Hinzufügen eines WinRTAdapter-Projekts für das wv2winrt-Tool

Erstellen Sie als Nächstes ein WinRTAdapter-Projekt für das wv2winrt-Tool (webView2 WinRT JS Projection Tool). Dieses Projekt erstellt eine Bibliothek aus Code, der durch Ausführen des Tools generiert wird. Mit diesem generierten Code können WinRT-APIs im WebView2-Steuerelement verfügbar gemacht werden.

Fügen Sie wie folgt ein Projekt für das wv2winrt-Tool hinzu:

  1. Öffnen Sie in Visual Studio Ihr WinUI-Projekt aus dem vorherigen Schritt.

  2. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf die Projektmappe (nicht auf das Projekt), und wählen Sie dannNeues Projekthinzufügen> aus. Das Dialogfeld Neues Projekt hinzufügen wird geöffnet.

  3. Geben Sie im Textfeld SuchenWindows-Runtime Component (C++/WinRT) ein.

    Alternativer Ansatz: Wenn Sie kein Projekt mithilfe der Projektvorlage für Windows-Runtime Component (C++/WinRT) hinzufügen, wie in den nummerierten Schritten unten beschrieben, müssen Sie stattdessen die Workload Universelle Windows-Plattform Entwicklung installieren, indem Sie die Schritte unter Einführung in C++/WinRT für UWP-Anwendungen >ausführen.

  4. Wählen Sie die Karte Windows-Runtime-Komponente (C++/WinRT) aus, und klicken Sie dann auf die Schaltfläche Weiter:

    Auswählen der Windows-Runtime-Komponente (C++/WinRT) Karte im Dialogfeld

    Hinweis: Stellen Sie sicher, dass die Vorlage "C++/WinRT" im Namen enthält. Wenn diese Vorlage nicht aufgeführt ist, installieren Sie die Workload Universelle Windows-Plattform Entwicklung aus dem Visual Studio-Installer. Wenn Sie Visual Studio 2019 verwenden und die Vorlage immer noch nicht finden können, installieren Sie die C++/WinRT-Vorlagen und die Schnellansicht für die VS2019-Erweiterung von Visual Studio-Erweiterungen >> verwalten.

    Das Fenster Neues Projekt konfigurieren wird geöffnet.

Konfigurieren und Erstellen des Projekts

  1. Geben Sie dem Projekt im Textfeld Projektname den Namen WinRTAdapter. Hinweis: Vorerst müssen Sie diesen spezifischen Projektnamen verwenden.

    Geben Sie dem Projekt im Fenster

    Der Pfad im obigen Screenshot spiegelt den Ansatz zum Klonen des Beispielrepositorys wider.

  2. Klicken Sie auf die Schaltfläche Erstellen.

    Das Dialogfeld Neues Windows-Projekt wird geöffnet:

    Dialogfeld

  3. Klicken Sie auf die Schaltfläche OK .

    Das WinRTAdapter-Projekt wird erstellt und in Projektmappen-Explorer neben dem Standard-Projekt hinzugefügt:

    Das neu erstellte WinRTAdapter-Projekt

  4. Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus.

Das wv2winrt-Tool (das WebView2 WinRT JS-Projektionstool) wird in diesem WinRTAdapter-Projekt ausgeführt. In einem folgenden Schritt generieren Sie Code für ausgewählte Klassen in diesem Projekt.

Schritt 3: Installieren der Windows-Implementierungsbibliothek für das WinRTAdapter-Projekt

Installieren Sie im WinRTAdapter-Projekt die Windows-Implementierungsbibliothek (Windows Implementation Library, WIL) wie folgt:

  1. Klicken Sie Projektmappen-Explorer mit der rechten Maustaste auf das Projekt WinRTAdapter, und wählen Sie dann NuGet-Pakete verwalten aus. Das Fenster NuGet-Paket-Manager wird in Visual Studio geöffnet.

  2. Klicken Sie im Fenster NuGet-Paket-Manager auf die Registerkarte Durchsuchen .

  3. Geben Sie im Fenster NuGet-Paket-Manager im Feld Suchen den Namen Windows-Implementierungsbibliothek ein, und wählen Sie dann die Windows-Implementierungsbibliothek Karte aus:

    NuGet-Paket-Manager, Auswählen des Pakets

  4. Klicken Sie auf die Schaltfläche Installieren . Das Dialogfeld Vorschau der Änderungen wird geöffnet:

    Dialogfeld

  5. Klicken Sie auf die Schaltfläche OK .

  6. Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus.

WIL ist jetzt für das WinRTAdapter-Projekt installiert. Die Windows-Implementierungsbibliothek (Windows Implementation Library, WIL) ist eine C++-Bibliothek, die nur für Header verwendet wird, um die Verwendung von COM-Codierung für Windows zu vereinfachen. Es bietet lesbare, typsichere C++-Schnittstellen für Windows COM-Codierungsmuster.

Schritt 4: Installieren des WebView2-Vorabversions-SDK für das WinRTAdapter-Projekt

Installieren Sie im WinRTAdapter-Projekt auch eine Vorabversion des WebView2 SDK wie folgt:

  1. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf das Projekt WinRTAdapter, und wählen Sie dann NuGet-Pakete verwalten aus. Das Fenster NuGet-Paket-Manager wird geöffnet.

  2. Klicken Sie im Fenster NuGet-Paket-Manager auf die Registerkarte Durchsuchen .

  3. Aktivieren Sie das Kontrollkästchen Vorabversion einschließen .

  4. Geben Sie webView2 in das Suchfeld ein.

  5. Klicken Sie auf die Karte Microsoft.Web.WebView2. Ausführliche Informationen werden im mittleren Bereich des Fensters angezeigt.

  6. Wählen Sie in der Dropdownliste Version eine Vorabversion des WebView2 SDK aus, oder stellen Sie sicher, dass Neueste Vorabversion ausgewählt ist. Die Version muss 1.0.1243.0 oder höher sein. Notieren Sie sich, welche Versionsnummer Sie auswählen.

    NuGet-Paket-Manager, Auswählen des WebView2 SDK-Pakets für das WinRTAdapter-Projekt

  7. Klicken Sie auf die Schaltfläche Installieren . Das Dialogfeld Vorschau der Änderungen wird geöffnet:

    Dialogfeld

  8. Klicken Sie auf die Schaltfläche OK .

  9. Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus.

Das WebView2-Vorabversions-SDK ist jetzt für das WinRTAdapter-Projekt installiert.

Schritt 5: Installieren des WebView2-Vorabversions-SDK (nur WinUI 2)

Installieren Sie im Standard Projekt, z. B. MyUWPGetStartApp, die gleiche Vorabversion des WebView2 SDK wie für das WinRTAdapter-Projekt wie folgt:

  1. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf das Standard Projekt, z. B. MyUWPGetStartApp, und wählen Sie dann NuGet-Pakete verwalten aus. Das Fenster NuGet-Paket-Manager wird geöffnet.

  2. Aktivieren Sie das Kontrollkästchen Vorabversion einschließen .

  3. Wählen Sie die Registerkarte Durchsuchen aus.

  4. Geben Sie webView2 in das Suchfeld ein.

  5. Klicken Sie auf die Karte Microsoft.Web.WebView2. Ausführliche Informationen werden im mittleren Bereich des Fensters angezeigt.

  6. Wählen Sie in der Dropdownliste Version eine Vorabversion des WebView2 SDK aus, oder stellen Sie sicher, dass Neueste Vorabversion ausgewählt ist. Stellen Sie sicher, dass Sie dieselbe Version wie das WinRTAdapter-Projekt verwenden. Für WinRT WebView2-Apps, die auf WinUI 2 (UWP) ausgerichtet sind, muss dies die gleiche Version wie für das WinRTAdapter-Projekt sein. Die Version muss 1.0.1243.0 oder höher sein.

  7. Klicken Sie auf die Schaltfläche Installieren . Das Dialogfeld Vorschau der Änderungen wird geöffnet, um WebView2 zum Standard-Projekt hinzuzufügen.

  8. Klicken Sie auf die Schaltfläche OK .

    Visual Studio sollte dem obigen Schrittabschnitt ähneln, mit dem Unterschied, dass jetzt der NuGet-Paket-Manager für das Standard-Projekt anstelle des WinRTAdapter-Projekts geöffnet ist.

  9. Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus.

Das WebView2-Vorabversions-SDK ist jetzt für das Standard-Projekt installiert.

Schritt 6: Generieren von Quellcode für ausgewählte Host-APIs

Konfigurieren Sie als Nächstes das wv2winrt-Tool (webView2 WinRT JS Projection Tool), um die WinRT-Klassen zu integrieren, die Sie verwenden möchten. Dadurch werden Quelldateien generiert, die dann kompiliert werden. Durch das Generieren von Code für diese APIs kann Ihr webseitiger JavaScript-Code diese APIs aufrufen.

In den folgenden Beispielschritten geben wir zwei Windows Namespaces an, und das wv2winrt-Tool generiert Quellcode nur für APIs unter diesen Namespaces:

Später, wenn die Beispiel-App ausgeführt wird, rufen Sie diese APIs über die DevTools-Konsole auf, um zu zeigen, dass diese angegebenen hostseitigen APIs aus webseitigem Code aufgerufen werden können.

Geben Sie den Namespace und die Klasse wie folgt an:

  1. Klicken Sie Projektmappen-Explorer mit der rechten Maustaste auf das Projekt WinRTAdapter, und wählen Sie dann Eigenschaften aus. Das Dialogfeld WinRTAdapter-Eigenschaftenseiten wird geöffnet.

  2. Erweitern Sie links, und wählen Sie Allgemeine Eigenschaften>WebView2 aus.

  3. Legen Sie WebView2 WinRT-APIs verwenden auf Nein fest. Dies bedeutet, dass das WebView2 SDK die WebView2 WinRT-Komponente nicht in die Ausgabe des Projekts kopiert. Dieses WinRTAdapter-Projekt ruft keine WebView2-WinRT-APIs auf, sodass die WinRT-Komponente nicht benötigt wird.

  4. Legen Sie Use the wv2winrt tool (wv2winrt-Tool verwenden) auf Ja fest.

  5. Legen Sie Use JavaScript case (JavaScript-Groß-/Kleinschreibung verwenden ) auf Ja fest.

  6. Klicken Sie in der Zeile Filter einschließen auf die Spalte auf der rechten Seite, klicken Sie in dieser Zelle auf das Dropdownmenü, und klicken Sie dann auf Bearbeiten. Das Dialogfeld Filter einschließen wird geöffnet.

  7. Fügen Sie im obersten Textfeld die folgenden Zeichenfolgen in separaten Zeilen ohne voranschreibende oder nachfolgende Leerzeichen ein:

    Windows.System.UserProfile
Windows.Globalization.Language

    Dialogfeld

    Sie müssen den vollständigen Namen der Namespaces oder Klassen angeben, wie oben gezeigt.

  8. Klicken Sie auf die Schaltfläche OK , um das Dialogfeld Filter einschließen zu schließen.

  9. Stellen Sie für diese exemplarische Vorgehensweise sicher, dass das Dialogfeld WinRTAdapter-Eigenschaftenseiten wie folgt aussieht:

    Dialogfeld

  10. Klicken Sie auf die Schaltfläche OK , um das Dialogfeld Eigenschaftenseiten zu schließen.

  11. Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus.

Hinzufügen eines Verweises, der auf das Adapterprojekt verweist

Fügen Sie als Nächstes im Standard-Projekt einen Verweis hinzu, der auf das Adapterprojekt verweist.

Fügen Sie im Standard Projekt, z. B. MyUWPGetStartApp, wie folgt einen Verweis hinzu, der auf das WinRTAdapter-Projekt verweist:

  1. Erweitern Sie in Projektmappen-Explorer das Standard Projekt, z. B. MyUWPGetStartApp, klicken Sie mit der rechten Maustaste auf Verweise, und wählen Sie dann Verweis hinzufügen aus. Das Dialogfeld Verweis-Manager wird geöffnet.

  2. Wählen Sie in der Struktur auf der linken Seite Projekte aus. Aktivieren Sie das Kontrollkästchen WinRTAdapter :

    Das Kontrollkästchen WinRTAdapter im Dialogfeld

  3. Klicken Sie auf die Schaltfläche OK , um das Dialogfeld Verweis-Manager zu schließen.

  4. Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus.

Generieren des API-Codes

Generieren Sie als Nächstes den API-Code:

  1. Klicken Sie mit der rechten Maustaste auf das Projekt WinRTAdapter , und wählen Sie dann Erstellen aus.

    Quellcode wird für Namespaces oder Klassen generiert, die Sie im Dialogfeld Filter einschließen des wv2winrt-Tools (webView2 WinRT JS Projection Tool) angegeben haben:

    • Windows.System.UserProfile Namespace
    • Windows.Globalization.Language-Klasse

  2. Wählen Sie nach Abschluss der Erstellung Datei>Alle speichern (STRG+UMSCHALT+S) aus.

Wichtig

Wenn Sie eine Releaseversion des WebView2 SDK installiert haben und Ihr Build mit error MIDL2011: [msg]unresolved type declaration [context]: Microsoft.Web.WebView2.Core.ICoreWebView2DispatchAdapter [ RuntimeClass 'WinRTAdapter.DispatchAdapter' ]fehlschlägt, ist dies ein Problem in der Releaseversion des WebView2 SDK, und Sie müssen Use WebView2 WinRT APIs in den obigen Schritten in Yes ändern.

Fügen Sie alternativ nach dem letzten </ItemGroup> in der Projektdatei WinRTAdapter.vcxprojFolgendes hinzu:

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

Ersetzen Sie durch $(WebView2SDKPath) das Verzeichnis, in dem das WebView2 SDK installiert wurde, durch ein \ am Ende. Beispiel: ..\<sample-directory>\packages\Microsoft.Web.WebView2.1.0.1264.42\.

Schritt 7: Aktualisieren des Zielframeworks (nur WinUI 3)

Wenn Ihre App für WinUI 2 (UWP) vorgesehen ist, überspringen Sie diesen Schritt.

Schritt 8: Hinzufügen des Hostobjekts zum Standard-Projekt

Übergeben Sie als Nächstes das WinRT-Objekt von der nativen Seite der Host-App an die Webseite der Host-App. Fügen Sie hierzu wie folgt eine InitializeWebView2Async Methode hinzu, die aufruft AddHostObjectToScript:

  1. Erweitern Sie in Projektmappen-Explorer das Standard-Projekt, z. B. MyUWPGetStartApp, erweitern Sie MainPage.xaml, und wählen Sie dann MainPage.xaml.cs aus.

  2. Fügen Sie unterhalb des MainPage Konstruktors die folgende InitializeWebView2Async Methode hinzu:

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

    Diese Methode ruft auf AddHostObjectToScript.

    In der Zeile AddHostObjectToScript("Windows", ...Windows ist der Namespace der obersten Ebene. Wenn Sie über andere Namespaces der obersten Ebene verfügen, können Sie zusätzliche Aufrufe für AddHostObjectToScripthinzufügen, wie im folgenden Beispiel:

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

    Der WrapNamedObject Aufruf erstellt ein Wrapperobjekt für den RuntimeComponent1 Namespace. Der AddHostObjectToScript Aufruf fügt das umschlossene Objekt dem Skript mit dem Namen RuntimeComponent1hinzu.

    Eine vollständige Anleitung zur Verwendung benutzerdefinierter WinRT-Komponenten finden Sie weiter unten unter Benutzerdefinierte WinRT-Komponenten von Drittanbietern.

  3. Fügen Sie im MainPage Konstruktor unten this.InitializeComponent();den folgenden Code hinzu:

    InitializeWebView2Async();

  4. Klicken Sie mit der rechten Maustaste auf das Standard Projekt, z. B. MyUWPGetStartApp, und wählen Sie dann Als Startprojekt festlegen aus. Fett zeigt das Startprojekt an.

  5. Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus.

  6. Drücken Sie F5 , um die Beispiel-App auszuführen. Die WebView2-fähige WinUI 2-App (UWP) wird geöffnet:

    Die WebView2 WinUI 2-UWP-App

Der webseitige Code der Host-App (und die DevTools-Konsole) kann jetzt Methoden und Eigenschaften der angegebenen Namespaces oder Klassen des Hostobjekts aufrufen.

Schritt 9: Aufrufen von Methoden und Eigenschaften für das Hostobjekt aus webseitigem JavaScript

Zugreifen auf projizierte APIs über die DevTools-Konsole

Verwenden Sie als Nächstes die DevTools-Konsole, um zu veranschaulichen, dass webseitiger Code die hostseitigen APIs aufrufen kann, die im wv2winrt-Tool (webView2 WinRT JS Projection Tool) angegeben wurden:

  1. Wenn die App nicht ausgeführt wird, drücken Sie in Visual Studio F5 , um die Beispiel-App auszuführen.

  2. Klicken Sie auf den Standard Teil des WebView2-Beispiel-App-Fensters, um den Fokus zu geben, und drücken Sie dann STRG+UMSCHALT+I, um Microsoft Edge DevTools zu öffnen. Oder klicken Sie mit der rechten Maustaste auf die Seite, und wählen Sie dann Untersuchen aus.

    Das Fenster Microsoft Edge DevTools wird geöffnet.

  3. Wenn das Microsoft Edge DevTools-Fenster nicht angezeigt wird, drücken Sie ALT+TAB , um es anzuzeigen.

  4. Wählen Sie im Fenster DevTools die Registerkarte Konsole aus.

  5. Klicken Sie auf die Schaltfläche Konsole löschen (Konsolensymbol löschen), oder klicken Sie mit der rechten Maustaste auf die Konsole , und wählen Sie dann Konsole löschen aus. Nachrichten werden in regelmäßigen Abständen in der Konsole angezeigt.

  6. Fügen Sie in der DevTools-Konsole den folgenden Windows.Globalization.Language-Klassencode ein, und drücken Sie dann die EINGABETASTE:

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

    Die Konsole gibt eine Sprachnamenzeichenfolge aus, z English (United States). B. , die zeigt, dass der hostseitige (systemeigene) Code Ihrer App aus webseitigem JavaScript-Code aufgerufen werden kann:

    Verwenden der DevTools-Konsole zum Testen des Aufrufens von nativem Code aus webseitigem Code

  7. Versuchen Sie, die Klammern wegzulassen. Geben Sie in der DevTools-Konsole die folgende Anweisung ein:

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

    Die Konsole gibt eine Sprachnamenzeichenfolge aus, z English (United States). B. .

    Auf ähnliche Weise können Sie auf Windows.System.UserProfile Namespace-Member zugreifen.

  8. Schließen Sie das Fenster DevTools.

  9. Schließen Sie die App.

Herzlichen Glückwunsch! Sie haben die Beispieldemonstration zum Aufrufen von WinRT-Code aus JavaScript-Code abgeschlossen.

Zugreifen auf projizierte APIs über Quellcodedateien

Oben haben wir die DevTools-Konsole verwendet, um JavaScript-Anweisungen auszuführen, die auf das projizierte Hostobjekt zugreifen. Ebenso können Sie aus Quellcodedateien auf das projizierte Hostobjekt zugreifen. Führen Sie dazu zunächst Setupcode für das Skript aus:

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

Anschließend fügen Sie im Standard Textkörper Ihres Codes Aufrufe zu projizierten Objekten hinzu, wie im Folgenden gezeigt:

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

Auf ähnliche Weise können Sie auf API-Member zugreifen Windows.System.UserProfile .

Dies ist das Ende der Tutorialschritte. Die folgenden Abschnitte enthalten allgemeine Informationen zu WebView2 WinRT-Apps.

Benutzerdefinierte WinRT-Komponenten (Drittanbieter)

Das wv2winrt-Tool (das WebView2 WinRT JS-Projektionstool) unterstützt benutzerdefinierte WinRT-Komponenten von Drittanbietern, zusätzlich zu Den WinRT-APIs des Erstanbieterbetriebssystems.

WinRT-Komponenten von Drittanbietern mit wv2winrt-Tool

Um benutzerdefinierte WinRT-Komponenten (Drittanbieter) mit dem wv2winrt-Tool zu verwenden, führen Sie zusätzlich zu den oben genannten Schritten auch die folgenden Schritte aus:

  1. Fügen Sie ihrer Visual Studio-Projektmappe, die Ihre WinRT-Klasse implementiert, ein drittes Projekt (außer Ihrem Standard-App- und WinRTAdapter-Projekt) hinzu.

  2. Lassen Sie das WinRTAdapter-Projekt "Verweis hinzufügen" auf Ihr neues drittes Projekt, das Ihre WinRT-Klasse enthält, verwenden.

  3. Aktualisieren Sie den Include-Filter des WinRTAdapter-Projekts in den Eigenschaften, um auch Ihre neue Klasse einzuschließen.

  4. Fügen Sie eine zusätzliche Zeile zu hinzu, um InitializeWebView2Async den Namespace Ihrer winrt-Klasse hinzuzufügen:

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

  5. Für einfache Methodenaufrufe aus dem Web fügen Sie optional Ihren Namespacesynchronisierungsproxy als globales Objekt im Skript hinzu. Beispiel:

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

Ein Beispiel hierfür finden Sie im folgenden WebView2-Beispiel:

Asynchrone WinRT-Methoden

Wenn Sie die Schritte in der obigen Anleitung befolgen, sollten Sie synchrone Proxys verwenden können. Für asynchrone Methodenaufrufe müssen Sie verwenden chrome.webview.hostObjects.options.forceAsyncMethodMatches.

Die forceAsyncMethodMatches -Eigenschaft ist ein Array von regulären Ausdrücken. Wenn ein regex mit einem Methodennamen in einem Synchronisierungsproxy übereinstimmt, wird die Methode stattdessen asynchron ausgeführt. Wenn Sie diese Einstellung auf [/Async$/] festlegen, entspricht sie einer beliebigen Methode, die mit dem Suffix Asyncendet. Dann funktionieren übereinstimmende Methodenaufrufe wie eine Methode für einen asynchronen Proxy und geben eine Zusage zurück, die Sie erwarten können.

Beispiel:

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/'));

Weitere Informationen finden Sie in der Zeile in CoreWebView2.AddHostObjectToScript-MethodeforceAsyncMethodMatches.

Abonnieren von WinRT-Ereignissen

WinRT-Ereignisse werden auch über die Skriptproxys verfügbar gemacht. Sie können Ereignishandler von instance WinRT-Ereignissen und statischen WinRT-Ereignissen mithilfe der addEventListener(string eventName, function handler) Methoden und hinzufügen und removeEventListener(string eventName, function handler) entfernen.

Diese Methoden funktionieren ähnlich wie die DOM-Methoden mit demselben Namen. Rufen Sie addEventListener mit einem Zeichenfolgennamen des WinRT-Ereignisses auf, das Sie als ersten Parameter abonnieren möchten, und einem Funktionsrückruf, der aufgerufen wird, wenn das Ereignis ausgelöst wird. Das Aufrufen removeEventListener mit denselben Parametern gekündigt das Ereignis. Beispiel:

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);
});

Für ein WinRT-Ereignis, das Ereignisargumente bereitstellt, werden diese als erster Parameter für die Ereignishandlerfunktion bereitgestellt. Beispielsweise verfügt das Ereignis über IMapChangedEventArgs<string, object> ein Windows.Foundation.Collections.PropertySet.MapChanged Ereignis-ARG-Objekt, und dieses Objekt wird als Parameter für den Rückruf bereitgestellt.

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;
    // ...
});

Das Ereignis-Args-Objekt verfügt zusätzlich über die folgenden Eigenschaften:

Eigenschaftenname Beschreibung
target Das Objekt, das das Ereignis ausgelöst hat
type Der Zeichenfolgenname des Ereignisses
detail Ein Array aller Parameter, die für den WinRT-Delegaten bereitgestellt werden

Festlegen, dass AddHostObjectToScript-JavaScript-Proxys mehr wie andere JavaScript-APIs wirken

AddHostObjectToScript standardmäßig asynchrone und ausführliche Proxys verwenden, aber Sie können festlegen, dass die AddHostObjectToScript JavaScript-Proxys wie andere JavaScript-APIs agieren. Weitere Informationen zu AddHostObjectToScript und dem Standardverhalten finden Sie unter AddHostObjectToScript. Wenn Sie eine Host-App von der JavaScript-WinRT-Projektion in JavaScript-UWP-Apps oder aus der EdgeHTML-basierten WebView migrieren, sollten Sie den folgenden Ansatz verwenden, um dem vorherigen Verhalten besser gerecht zu werden.

Legen Sie die folgenden Eigenschaften fest, damit die AddHostObjectToScript JavaScript-Proxys mehr wie andere JavaScript-APIs agieren:

  • chrome.webview.hostObjects.option.defaultSyncProxy - Proxys können entweder asynchron oder synchron sein. Normalerweise wissen wir beim Aufrufen einer Methode für einen synchronen Proxy, dass das Ergebnis auch ein synchroner Proxy sein sollte. In einigen Fällen geht dieser Kontext jedoch verloren, z. B. wenn ein Verweis auf eine Funktion auf nativen Code bereitgestellt wird, und dann später nativer Code, der diese Funktion aufruft. In diesen Fällen ist der Proxy asynchron, es sei denn, diese Eigenschaft ist festgelegt.

  • chrome.webview.hostObjects.options.forceAsyncMethodMatches – Dies ist ein Array von regulären Ausdrücken. Wenn Sie eine Methode für einen synchronen Proxy aufrufen, wird der Methodenaufruf tatsächlich asynchron ausgeführt, wenn der Methodenname mit einer Zeichenfolge oder einem regulären Ausdruck in diesem Array übereinstimmt. Wenn Sie diesen Wert auf [/Async$/] festlegen, wird jede Methode, die mit Async endet, zu einem asynchronen Methodenaufruf. Wenn eine asynchrone Methode hier nicht übereinstimmt und nicht gezwungen wird, asynchron zu sein, wird die Methode synchron aufgerufen, wodurch die Ausführung des aufrufenden JavaScript blockiert und dann die Auflösung der Zusage zurückgegeben wird, anstatt eine Zusage zurückzugeben.

  • chrome.webview.hostObjects.options.ignoreMemberNotFoundError - Wenn Sie versuchen, den Wert einer Eigenschaft eines Proxys abzurufen, und die Eigenschaft in der entsprechenden nativen Klasse nicht vorhanden ist, erhalten Sie eine Ausnahme . Es sei denn, Sie legen diese Eigenschaft auf truefest. In diesem Fall stimmt das Verhalten mit dem Chakra WinRT-Projektionsverhalten (und dem allgemeinen JavaScript-Verhalten) überein und gibt ohne Fehler zurück undefined .

Die Chakra WinRT-Projektion platziert die WinRT-Namespaces direkt auf dem Stammobjekt. Im Gegensatz dazu:

  • AddHostObjectToScript platziert asynchrone Stammproxys auf chrome.webview.hostObjects.
  • AddHostObjectToScript platziert Synchronisierungsstammproxys auf chrome.webview.hostObjects.sync.

Um auf Stammproxys zuzugreifen, wo Chakra WinRT-Projektionscode erwarten würde, können Sie dem Stammobjekt die WinRT-Namespacespeicherorte des Stammproxys zuweisen. Beispiel:

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

Um sicherzustellen, dass das JavaScript, das all dies festlegt, vor allem ausgeführt wird, können Sie entweder die obige Anweisung zu Ihrem JavaScript hinzufügen oder WebView2 anweisen, die obige Anweisung für Sie einzufügen, bevor Sie ein anderes Skript ausführen, indem Sie die CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync -Methode verwenden.

Im folgenden Beispiel werden die oben genannten Techniken veranschaulicht:

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;" +
                    "}" +
                "})();");

Abrufen von Informationen zu WebView2-Eigenschaften

Informationen zu WebView2-Eigenschaften sind an zwei Stellen verfügbar:

  • Eigenschaftenseiten des WinRTAdapter-Projekts.
  • wv2winrt.exe Befehlszeilenhilfe. Dies ist das wv2winrt-Tool (webView2 WinRT JS Projection Tool).

Eigenschaftenseiten des WinRTAdapter-Projekts

Klicken Sie in den Eigenschaftenseiten des WinRTAdapter-Projekts auf eine Eigenschaftenzeile, um Hilfe zu einer Eigenschaft zu benötigen. Die Hilfe wird am unteren Rand des Dialogfelds angezeigt:

Eigenschaften, die auf den WinRTAdapter-Eigenschaftenseiten aufgeführt sind

Befehlszeilenhilfe für wv2winrt.exe Eigenschaften

Die Befehlszeilenhilfe für wv2winrt.exe enthält Informationen zu den Parametern des wv2winrt-Tools (webView2 WinRT JS Projection Tool). Beispiel:

Parameter Beschreibung
verbose Listen Sie einige Inhalte auf, die standardmäßig festgelegt werden sollen, einschließlich der erstellten Dateien und Informationen zu den Ein- und Ausschlussregeln.
include Die Liste wie oben schließt Standardmäßig Namespaces und Laufzeitklassen mit Ausnahme der aufgeführten aus. Die include-Deklarationen können entweder Namespaces sein, die alles in diesem Namespace enthalten, oder Laufzeitklassennamen, die nur diese Runtimeklasse enthalten.
use-javascript-case Ändert den generierten Code, um Methodennamen, Eigenschaftsnamen usw. zu erzeugen, die den gleichen Groß-/Kleinschreibungsstil wie die Chakra JavaScript WinRT-Projektion verwenden. Standardmäßig werden Namen generiert, die dem Winrt entsprechen.
output-path Legt den Pfad fest, in den generierte Dateien geschrieben werden.
output-namespace Legt den Namespace fest, der für die generierte WinRT-Klasse verwendet werden soll.
winmd-paths Eine durch Leerzeichen getrennte Liste aller winmd-Dateien, die für die Codegenerierung untersucht werden sollen.

Siehe auch

Tutorial und Beispiel:

API-Referenz:

.NET-gleichwertiger Artikel: