Aufrufen von systemeigenem WinRT-Code aus webseitigem Code

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

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

Weitere Informationen dazu, warum Sie möchten, dass Ihr webseitiger JavaScript-Code auf die Methoden und Eigenschaften Ihrer WinRT-Host-App zugreift, finden Sie in der Einführung unter Aufrufen von systemeigenem 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. Ein Aufruf AddHostObjectToScript mit dem C#-Code dieses Artikels für .NET WebView2-APIs würde eine Fehlermeldung zurückgeben.

Das wv2winrt-Tool (das WebView2 WinRT JS-Projektionstool) wird beim Projizieren von WinRT-Objekten benötigt, da WinRT keinen anderen Mechanismus zur dynamischen Überprüfung von und Interaktion mit WinRT-Objekten unterstützt IDispatch , die von den Win32- und .NET-Plattformen von WebView2 unterstützt werden. Informationen zur Verwendung von .NET finden Sie unter Aufrufen von AddHostObjectToScriptsystemeigenem Code aus webseitigem Code anstelle dieses Artikels.

Setupunterschiede zwischen 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 bereitgestellt werden:

• In einer nicht verpackten App müssen Sie zusätzliche Schritte ausführen, die im Artikel "Verbessern nicht verpackter Desktop-Apps mithilfe von Windows-Runtime-Komponenten" beschrieben sind.

• Hinzufügen WinRTAdapter zu CsWinRTIncludes.

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

• Die Version des Projektadapters muss nicht übereinstimmen.

• Klicken Sie nach der Installation der "Standard"-Optionen 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

In diesem Artikel werden Sie durch die folgenden Hauptschritte geführt:

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

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

   • Windows.System.UserProfile Namespace
   • Windows.Globalization.Language Class

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

4. Rufen Sie AddHostObjectToScript in Ihrem WinUI-Hauptprojekt auf.

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

Endziel

Zuerst 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 für Windows UWP-Anwendungen befindet. Die Windows.Globalization.Language-Klasse ermöglicht das Abrufen von Sprachinformationen aus dem nativen Betriebssystem des Clients.

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

Zugriff auf projizierte APIs über die DevTools-Konsole

Am Ende dieser Beispielexemplarischen displayName Vorgehensweise verwenden Sie die Konsole von Microsoft Edge DevTools, um das Lesen der Hosteigenschaft 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 in einer anderen Sprache aus English (USA), um zu zeigen, dass Sie systemeigenen Code aus webseitigem JavaScript-Code aufgerufen haben:

Sie können auf ähnliche Weise auf Windows.System.UserProfile-Namespacemitglieder zugreifen.

Zugriff 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 den Setupcode für das Skript aus:

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

Fügen Sie dann im Hauptteil Ihres Codes Aufrufe an projizierte Objekte hinzu, wie die folgenden:

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

Sie können auf ähnliche Weise auf Windows.System.UserProfile-Namespacemitglieder zugreifen.

Los geht's!

Schritt 1: Erstellen oder Abrufen eines einfachen WebView2-Projekts

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

Erstellen Sie als Nächstes ein WinRTAdapter-Projekt für das Tool wv2winrt (das WebView2 WinRT JS-Projektionstool). Dieses Projekt erstellt eine Bibliothek aus Code, der durch Ausführen des Tools generiert wird. Dieser generierte Code ermöglicht es, WinRT-APIs im WebView2-Steuerelement verfügbar zu machen.

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 im Projektmappen-Explorer mit der rechten Maustaste auf die Projektmappe (nicht auf das Projekt), und wählen Siedann Neues Projekthinzufügen> aus. Das Dialogfeld Neues Projekt hinzufügen wird geöffnet.

3. Geben Sie im Textfeld Suchendie Zeichenfolge Windows-Runtime-Komponente (C++/WinRT) ein.

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

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

   

   Hinweis: Stellen Sie sicher, dass die Vorlage "C++/WinRT" im Namen enthält. Wenn diese Vorlage nicht aufgeführt ist, installieren Sie die Entwicklungsworkload "Universelle Windows-Plattform" 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 Erweiterung "Visualizer for VS2019 " von Visual Studio > Extensions > verwalten.

   Das Fenster Neues Projekt konfigurieren wird geöffnet.

Konfigurieren und Erstellen des Projekts

Das Tool wv2winrt (das WebView2 WinRT JS-Projektionstool) wird in diesem WinRTAdapter-Projekt ausgeführt. In einem nachfolgenden 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 (WIL) wie folgt:

WIL ist jetzt für das WinRTAdapter-Projekt installiert. Die Windows-Implementierungsbibliothek (Windows Implementation Library, WIL) ist eine C++-Bibliothek nur für Header, 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:

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

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

Schritt 6: Generieren des Quellcodes für ausgewählte Host-APIs

Konfigurieren Sie als Nächstes das Tool wv2winrt (das WebView2 WinRT JS-Projektionstool), um die WinRT-Klassen zu integrieren, die Sie verwenden möchten. Dadurch werden Quelldateien generiert, die dann kompiliert werden. Das Generieren von Code für diese APIs ermöglicht es Ihrem webseitigen JavaScript-Code, diese APIs aufzurufen.

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

• Windows.System.UserProfile Namespace
• Windows.Globalization.Language Class

Später, wenn die Beispiel-App ausgeführt wird, rufen Sie diese APIs über die DevTools-Konsole auf, um zu veranschaulichen, 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 im Projektmappen-Explorer mit der rechten Maustaste auf das WinRTAdapter-Projekt, und wählen Sie Eigenschaften aus. Das Dialogfeld WinRTAdapter-Eigenschaftenseiten wird geöffnet.

2. Erweitern Sie auf der linken Seite Allgemeine Eigenschaften>WebView2, und wählen Sie sie aus.

3. Legen Sie "WebView2 WinRT-APIs verwenden " auf "Nein" fest. Dadurch kopiert das WebView2-SDK die WebView2-WinRT-Komponente nicht in die Projektausgabe. Dieses WinRTAdapter-Projekt ruft keine WebView2-WinRT-APIs auf und benötigt daher die WinRT-Komponente nicht.

4. Legen Sie Verwenden des Tools wv2winrt auf Ja fest.

5. Legen Sie "JavaScript-Groß-/Kleinschreibung verwenden " auf Ja fest.

6. Klicken Sie in der Zeile "Filter einschließen " auf die Spalte rechts, klicken Sie auf das Dropdown-Menü in dieser Zelle, 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 führende oder nachgestellte Leerzeichen ein:

   Windows.System.UserProfile
   Windows.Globalization.Language
   

   

   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 sicher, dass das Dialogfeld "WinRTAdapter-Eigenschaftenseiten " für diese exemplarische Vorgehensweise wie folgt aussieht:

   

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

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

Hinzufügen eines Verweises, der auf das Adapterprojekt verweist

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

API-Code generieren

Generieren Sie als Nächstes den API-Code:

1. Klicken Sie mit der rechten Maustaste auf das WinRTAdapter-Projekt , 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 (dem WebView2 WinRT JS-Projektionstool) angegeben haben:

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

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

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

Schritt 7: Aktualisieren des Zielframeworks (nur WinUI 3)

Schritt 8: Hinzufügen des Hostobjekts zum Hauptprojekt

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

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 über webseitiges JavaScript

Zugriff auf projizierte APIs über die DevTools-Konsole

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

• Windows.System.UserProfile Namespace
• Windows.Globalization.Language Class

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

2. Klicken Sie in den Hauptteil des WebView2-Beispiel-App-Fensters, um den Fokus zu setzen, und drücken Sie dann STRG+UMSCHALT+I , um die Microsoft Edge-Entwicklungstools zu öffnen. Oder klicken Sie mit der rechten Maustaste auf die Seite, und wählen Sie dann "Überprüfen" 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 DevTools-Fenster die Registerkarte Konsole aus.

5. Klicken Sie auf die Schaltfläche Konsole löschen (") oder klicken Sie mit der rechten Maustaste in die Konsole , und wählen Sie dann Konsole löschen aus. In der Konsole werden möglicherweise regelmäßig Nachrichten 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. B English (USA). , die zeigt, dass der hostseitige (systemeigene) Code Ihrer App aus webseitigem JavaScript-Code aufgerufen werden kann:

   

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. B English (USA).

   Sie können auf ähnliche Weise auf Windows.System.UserProfile-Namespacemitglieder zugreifen.

8. Schließen Sie das DevTools-Fenster.

9. Schließen Sie die App.

Zugriff 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 heraus auf das projizierte Hostobjekt zugreifen. Führen Sie dazu zunächst den Setupcode für das Skript aus:

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

Fügen Sie dann im Hauptteil Ihres Codes Aufrufe an projizierte Objekte hinzu, wie die folgenden:

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

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

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

Benutzerdefinierte (Fremdanbieter-) WinRT-Komponenten

Das Tool wv2winrt (das WebView2 WinRT JS-Projektionstool) unterstützt benutzerdefinierte WinRT-Komponenten von Drittanbietern zusätzlich zu den WinRT-APIs für das Betriebssystem von Erstanbietern.

Um benutzerdefinierte WinRT-Komponenten (von Drittanbietern) 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 ein drittes Projekt (außer der Haupt-App und dem WinRTAdapter-Projekt) hinzu, das Ihre WinRT-Klasse implementiert.

2. Lassen Sie das WinRTAdapter-Projekt Ihrem neuen dritten Projekt "Verweis hinzufügen", das Ihre WinRT-Klasse enthält.

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 hinzu, um InitializeWebView2Async den Namespace Ihrer WinRT-Klasse hinzuzufügen:

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

5. Fügen Sie für einen einfachen Methodenaufruf aus dem Web optional Ihren Namespacesynchronisierungsproxy als globales Objekt im Skript hinzu. Zum Beispiel:

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

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

• uwp-wv2winrt-custom-csharp-winrt : Ein Beispiel, als Verzweigung.

Asynchrone WinRT-Methoden

Wenn Sie die Schritte in der obigen Anleitung befolgen, sollten Sie in der Lage sein, synchrone Proxys zu verwenden. Für Aufrufe mit asynchroner Methode müssen chrome.webview.hostObjects.options.forceAsyncMethodMatchesSie verwenden.

Die forceAsyncMethodMatches Eigenschaft ist ein Array von regulären Ausdrücken. Wenn ein regulärer Ausdruck mit einem Methodennamen auf einem Synchronisierungsproxy übereinstimmt, wird die Methode stattdessen asynchron ausgeführt. Wenn Sie dies auf festlegen, [/Async$/] wird es mit jeder Methode übereinstimmen, die mit dem Suffix Asyncendet. Dann funktionieren übereinstimmende Methodenaufrufe genau wie eine Methode auf einem 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 der forceAsyncMethodMatchesCoreWebView2.AddHostObjectToScript-Methode.

Abonnieren von WinRT-Ereignissen

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

Diese Methoden funktionieren ähnlich wie die gleichnamigen DOM-Methoden. Rufen Sie als ersten Parameter einen Zeichenfolgennamen addEventListener für das WinRT-Ereignis auf, das Sie abonnieren möchten, und einen Funktionsrückruf, der immer aufgerufen wird, wenn das Ereignis ausgelöst wird. Beim Aufruf removeEventListener mit denselben Parametern wird dieses Ereignis abgemeldet. Zum 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);
});

Bei einem WinRT-Ereignis, das Ereignisargumente bereitstellt, werden diese als erster Parameter für die Ereignishandlerfunktion bereitgestellt. Beispielsweise verfügt das Windows.Foundation.Collections.PropertySet.MapChanged Ereignis über IMapChangedEventArgs<string, object> ein 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:

Verhalten von AddHostObjectToScript-JavaScript-Proxys verhalten sich eher wie andere JavaScript-APIs

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

Damit sich die AddHostObjectToScript JavaScript-Proxys mehr wie andere JavaScript-APIs verhalten, legen Sie die folgenden Eigenschaften fest:

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

• chrome.webview.hostObjects.options.forceAsyncMethodMatches - Dies ist ein Array regulärer Ausdrücke. Wenn Sie eine Methode auf einem 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 einem asynchronen Methodenaufruf endet, zu einem asynchronen Methodenaufruf gemacht. Wenn eine asynchrone Methode hier nicht übereinstimmt und nicht erzwungen wird, asynchron zu sein, wird die Methode synchron aufgerufen, wodurch die Ausführung des aufrufenden JavaScript-Codes blockiert wird 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 entspricht das Verhalten dem Chakra WinRT-Projektionsverhalten (und dem allgemeinen JavaScript-Verhalten) und wird ohne Fehler zurückgegeben 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, die der Chakra-WinRT-Projektionscode erwarten würde, können Sie dem Stammobjekt die WinRT-Namespacespeicherorte des Stammproxys zuweisen. Zum Beispiel:

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

Um sicherzustellen, dass das JavaScript, das all dies einrichtet, vor allem anderen ausgeführt wird, können Sie entweder die obige Anweisung zu Ihrem JavaScript hinzufügen, oder Sie können WebView2 anweisen, die obige Anweisung für Sie einzuschleusen, 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;" +
                    "}" +
                "})();");

webView->CoreWebView2->AddScriptToExecuteOnDocumentCreatedAsync(
            LR"(
                (() => {
                    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;
                    }
                })();
            )"));

Informationen zu WebView2-Eigenschaften

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

• Die Eigenschaftenseiten des WinRTAdapter-Projekts.
• wv2winrt.exe Hilfe zur Befehlszeile. Dies ist das Tool wv2winrt (das WebView2 WinRT JS-Projektionstool).

Eigenschaftenseiten des WinRTAdapter-Projekts

Klicken Sie auf den Eigenschaftenseiten des WinRTAdapter-Projekts auf eine Eigenschaftenzeile, um Hilfe zu einer Eigenschaft zu erhalten. Unten im Dialogfeld wird Hilfe angezeigt:

Befehlszeilenhilfe für wv2winrt.exe Eigenschaften

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

Siehe auch

Tutorial und Beispiel:

• Erste Schritte mit WinUI 2 (UWP)-Apps – Lernprogramm: Schritte zum Erstellen einer App mit WebView2 mithilfe einer Projektvorlage.
• WinUI 2 (UWP)-Beispiel-App – Beispiel: Schritte zum Herunterladen, Erstellen, Ausführen und Aktualisieren des Beispiels.

API-Referenz:

• WinRT: CoreWebView2.AddHostObjectToScript-Methode
• Win32: ICoreWebView2::AddHostObjectToScript-Methode
• .NET: CoreWebView2.AddHostObjectToScript-Methode

Äquivalenter .NET-Artikel:

• Aufrufen von systemeigenem Code aus webseitigem Code – behandelt Win32/C++ sowie einige Aspekte von .NET/C# innerhalb von Frames.