Win32-Beispiel-App

Die WebView2APISample-App veranschaulicht die Verwendung des WebView2-Steuerelements und der WebView2-APIs zum Hinzufügen von Features zu einer Win32 C++-App. Dies ist das Standard Win32-Beispiel und enthält Testwebseiten für die neuesten Features und APIs sowie Hunderte von Menüelementen zum Testen verschiedener APIs.

• Beispielname: WebView2APISample
• Repositoryverzeichnis: WebView2APISample
• Lösungsdatei: WebView2Samples.sln (befindet sich im übergeordneten Verzeichnis, \SampleApps\)
• Projektname in Projektmappen-Explorer: WebView2APISample

WebView2APISample bettet ein WebView2-Steuerelement in eine native Win32-Anwendung ein.

In diesem Beispiel werden C++ und HTML/CSS/JavaScript in der WebView2-Umgebung verwendet.

WebView2APISample zeigt eine Auswahl von WebView2-Ereignishandlern und API-Methoden, die es einer nativen Win32-Anwendung ermöglichen, direkt mit einem WebView2-Steuerelement zu interagieren und umgekehrt.

Dieses Beispiel und seine Lösungsdatei sind eindeutig: Sie enthält eine Kopie anderer Beispiele in Projektmappen-Explorer.

WebView2APISample ist eine Hybridanwendung, die mit dem Microsoft Edge WebView2-Steuerelement erstellt wurde. Das heißt, diese App kombiniert eine native Seite und eine Browser-Web-App-Seite. Weitere Informationen finden Sie unter Hybrid-App-Ansatz in Einführung in Microsoft Edge WebView2.

Das ausgeführte WebView2APISample-App-Fenster zeigt die WebView2 SDK-Version sowie die WebView2-Runtimeversion und den Pfad an. Es gibt viele nützliche Menüs und Menüelemente zum Testen und Veranschaulichen der WebView2-APIs.

Abfolge der Artikel

Verwenden Sie zum Erlernen von WebView2 diese vorgeschlagene Abfolge von Artikeln und Beispielprojekten:

1. Rufen Sie dieses WebView2APISample zum Erstellen und Ausführen mithilfe des vorliegenden Artikels ab, auch wenn Ihre eigene App für eine andere Plattform vorgesehen ist.

2. Wenn Sie am meisten an einer anderen Plattform als Win32 interessiert sind, verwenden Sie den Artikel Beispiel für Ihre Plattform. Siehe Beispiel-Apps.

3. Verwenden Sie den Artikel Erste Schritte für die Plattform, an der Sie interessiert sind. Siehe Erste Schritte Tutorials.

Schritt 1: Installieren von Visual Studio 2022

1. Drücken Sie die Windows-Taste , geben Sie Visual Studio 2022 ein, und klicken Sie dann auf Öffnen.

   Das Dialogfeld Zuletzt geöffnet in Visual Studio wird geöffnet.

   Microsoft Visual Studio Code wird für dieses Beispiel nicht unterstützt.

2. Wenn Visual Studio 2022 nicht installiert ist, wechseln Sie zu Visual Studio 2022 , und verwenden Sie dann die Kombinationsschaltfläche Visual Studio herunterladen .

Fahren Sie mit dem nächsten Schritt unten fort, Schritt 2: Klonen des WebView2Samples-Repositorys.

Ältere Versionen von Visual Studio

Visual Studio 2019 und 2017 werden ebenfalls unterstützt.

Visual Studio 2019

Dieses Beispiel wurde mit Visual Studio 2019 als Visual Studio 2019-Projekt erstellt. Um das Projekt dieses Beispiels unverändert zu öffnen, können Sie Visual Studio 2019 verwenden.

Visual Studio 2017

Wenn Sie dieses Beispiel mit Visual Studio 2017 öffnen möchten:

1. Öffnen Sie die Projektmappe in Visual Studio 2017.

2. Ändern Sie das Plattformtoolset des Projekts unter Projekteigenschaften > Konfigurationseigenschaften > Allgemeines > Plattformtoolset.

3. Möglicherweise müssen Sie auch ein aktuelles Windows SDK auf Ihrem Computer installieren.

Schritt 2: Klonen des WebView2Samples-Repositorys

1. Drücken Sie Windows+E.

   Ein Explorer Fenster wird geöffnet.

2. Navigieren Sie zu dem Ort, an dem Sie das WebView2Samples-Repository geklont haben, oder planen Sie, das Repository zu klonen.

   Beispielpfad:

   C:\Users\localAccount\GitHub\WebView2Samples

3. Falls noch nicht geschehen, klonen Sie das WebView2Samples Repository auf Ihr lokales Laufwerk. In einem separaten Fenster oder einer separaten Registerkarte finden Sie weitere Informationen unter Klonen 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.

4. Wenn noch nicht geöffnet, öffnen Sie eine Git Bash-Eingabeaufforderung: Drücken Sie die Windows-Taste , und geben Sie dann git bash ein.

   Pullcommits

5. Wechseln Sie zum geklonten Repositoryverzeichnis:

   cd C:/Users/localAccount/GitHub/WebView2Samples`
   

   Ersetzen Sie den Pfad, in dem Sie das WebView2Samples-Repository geklont haben.

6. Rufen Sie die neuesten Commits in Ihre lokale Kopie des Repositorys ab:

   git pull
   

   Erstellen eines Arbeitsbranchs

7. Erstellen Sie einen Arbeitsbranch, und wechseln Sie zu diesem Branch:

   git checkout -b test
   

   Ertrag: Switched to branch 'test'

Sie können jetzt den Code in Ihrem Arbeitsbranch ändern, ohne den Code im Branch "Standard" des Repositorys zu ändern. Später möchten Sie möglicherweise wieder zum Branch "Standard" wechseln, z. B. um neue Commits zu pullen, oder einen anderen Branch basierend auf dem Branch "Standard" erstellen.

Schritt 3: Öffnen der Projektmappe in Visual Studio

Beim Öffnen und Erstellen des Beispiels wird das Beispiel geändert. Die bewährte Methode besteht darin, das Ändern des Codes im Branch "Standard" zu vermeiden, indem Sie einen Arbeitsbranch erstellen und zu diesem wechseln. Dies können Sie in Visual Studio ausführen.

1. Drücken Sie die Windows-Taste , geben Sie Visual Studio 2022 ein, und klicken Sie dann auf Öffnen.

   Das Dialogfeld Zuletzt geöffnet in Visual Studio wird geöffnet:

   

2. Klicken Sie unten rechts auf Continue without code (Ohne Code fortfahren).

3. Wählen Sie in Visual Studio 2022 Datei>Projekt/Projektmappeöffnen> aus.

   Das Dialogfeld Projekt/Projektmappe öffnen wird geöffnet.

4. Navigieren Sie zu der WebView2Samples\SampleApps\WebView2Samples.sln Datei, und klicken Sie dann auf die Schaltfläche Öffnen .

   Beispielpfad:

   C:\Users\localAccount\GitHub\WebView2Samples\SampleApps\WebView2Samples.sln
   

   Im Gegensatz zu einigen anderen Beispielen gibt es keine dedizierte .sln Datei im Beispielrepositoryverzeichnis, die die Infodatei dieses Beispiels enthält. Stattdessen befindet sich die .sln Datei für dieses Beispiel (einschließlich anderer Beispielprojekte) im übergeordneten Verzeichnis.

   Das Dialogfeld Projekt und Projektmappenänderungen überprüfen wird möglicherweise geöffnet:

   

5. Klicken Sie auf die Schaltfläche OK .

   Die Projektmappe wird in Visual Studio geöffnet:

   

Schritt 4: Aktualisieren des Toolsets

Weiter oben: Das Dialogfeld Projektmappenaktionen überprüfen: Projekte neu festlegen wird möglicherweise geöffnet:

Dieser Screenshot zeigt:

• Windows SDK Version:10.0 (neueste installierte Version)
• Plattformtoolset:Upgrade auf v143

Diese Optionen sind für diese Projekte aufgeführt:

• WebView2APISample.vcxproj : das vorliegende Standard Beispiel.

• WebView2APISampleWinComp.vcxproj – ein anderes Beispiel.

• Wenn dieses Dialogfeld geöffnet wird, klicken Sie auf die Schaltfläche OK .

  Im Bereich Ausgabe in Visual Studio werden Ergebnisse angezeigt, z. B.:

  Upgrading project 'WebView2APISample'...
  Configuration 'Debug|ARM64': changing Platform Toolset to 'v143' (was 'v142').
  Configuration 'Debug|Win32': changing Platform Toolset to 'v143' (was 'v142').
  Configuration 'Debug|x64': changing Platform Toolset to 'v143' (was 'v142').
  Configuration 'Release|Win32': changing Platform Toolset to 'v143' (was 'v142').
  Configuration 'Release|ARM64': changing Platform Toolset to 'v143' (was 'v142').
  Configuration 'Release|x64': changing Platform Toolset to 'v143' (was 'v142').
  Upgrading project 'WebView2SampleWinComp'...
  Configuration 'Debug|Win32': changing Platform Toolset to 'v143' (was 'v142').
  Configuration 'Debug|x64': changing Platform Toolset to 'v143' (was 'v142').
  Configuration 'Release|Win32': changing Platform Toolset to 'v143' (was 'v142').
  Configuration 'Release|x64': changing Platform Toolset to 'v143' (was 'v142').
  Retargeting End: 2 completed, 0 failed, 0 skipped
  

  Im Browser wird eine Seite Migrationsbericht geöffnet, z. B.: file:///C:/Users/localAccount/GitHub/WebView2Samples/SampleApps/UpgradeLog.htm

Schritt 5: Aktualisieren von .NET

Weiter oben: In Visual Studio wird in Projektmappen-Explorer oben rechts möglicherweise die Meldung angezeigt: Dieses Projekt zielt auf eine Version von .NET ab, die nicht installiert ist.

1. Wenn Diese Meldung angezeigt wird, klicken Sie neben der Nachricht auf den Link Installieren .

   Das Dialogfeld Visual Studio-Installer wird geöffnet:

   

2. Klicken Sie auf die Schaltfläche Installieren .

   Das Dialogfeld Benutzerkontensteuerung wird geöffnet.

3. Klicken Sie auf die Schaltfläche Ja .

   Das Dialogfeld Visual Studio-Installer zeigt den Fortschritt beim Herunterladen und Installieren an, und zeigt dann Die Installation wurde abgeschlossen an.

4. Klicken Sie auf die Schaltfläche Schließen .

   Das Dialogfeld Visual Studio-Installer wird geschlossen.

   Projektmappen-Explorer wird ohne die Meldung "Nicht installiert" angezeigt.

Schritt 6: Installieren der C++-Workload für Visual Studio

Weiter oben: Wenn Sie aufgefordert werden, Workloads zu installieren, wenn Sie versuchen, das Projekt zu erstellen:

1. Wählen Sie in Visual Studio Tools>und Features abrufen aus.

   Das Dialogfeld Visual Studio-Installer wird geöffnet, und dann wird das Dialogfeld Ändern geöffnet.

2. Wählen Sie auf der Registerkarte Workloads die Karte Desktopentwicklung mit C++ aus, sodass ein Häkchen darauf angezeigt wird.

3. Erweitern Sie unter Installationsdetails auf der rechten Seite Desktopentwicklung mit C++.

4. Klicken Sie auf die Schaltfläche Aktualisieren oder Installieren .

   Das Installationsprogramm wird geschlossen.

Siehe auch:

• Schritt 4: Installieren Sie Workloads, wenn Sie unter Erste Schritte mit WebView2 in Win32-Apps dazu aufgefordert werden.
• Installieren Sie Visual Studio-Workloads unter Einrichten Ihrer Entwicklungsumgebung für WebView2.

Sie müssen WiX nicht installieren, um den Vorgang fortzusetzen. für ein anderes Projekt in dieser Projektmappendatei. Die Installation von WiX wird in WiX Burn Bundle behandelt, um die WebView2-Runtime bereitzustellen.

Schritt 7: Erstellen und Ausführen mit einem älteren SDK

Legen Sie oben in Visual Studio das Buildziel wie folgt fest:

1. Wählen Sie in der Dropdownliste Lösungskonfigurationendie Option Debuggen aus.

2. Wählen Sie in der Dropdownliste Lösungsplattformendie Option x64 aus.

3. Klicken Sie Projektmappen-Explorer mit der rechten Maustaste auf das Projekt WebView2APISample, und wählen Sie dann Erstellen aus.

   

   Dadurch wird die Projektdatei SampleApps/WebView2APISample/WebView2APISample.vcxprojerstellt.

4. Wählen Sie Debuggen>Debuggen starten (F5) aus.

   Das App-Fenster WebView2APISample wird geöffnet:

   

5. Schließen Sie das Beispiel-App-Fenster.

Schritt 8: Aktualisieren der Vorabversion des WebView2 SDK

In der Repositoryversion dieses Beispiels ist eine Vorabversion des WebView2 SDK installiert. Im Folgenden aktualisieren Sie das WebView2 SDK auf die neueste Vorabversion (es sei denn, das neueste Vorabversions-SDK ist bereits installiert). Ein Vorabversions-SDK unterstützt die neuesten experimentellen APIs und die neuesten "Stable in Prerelease"-APIs.

1. Überprüfen Sie die Versionsnummer des Vorabversions-SDK, das sich in der Kopie des Repositorys der WebView2APISample-App auf GitHub befindet: siehe packages.config.

   Zum Beispiel:

   <package id="Microsoft.Web.WebView2" version="1.0.2950-prerelease" targetFramework="native" />
   <package id="Microsoft.Windows.ImplementationLibrary" version="1.0.220201.1" targetFramework="native" />
   

2. Überprüfen Sie die neueste Versionsnummer der Vorabversion unter Versionshinweise für das WebView2 SDK.

3. Klicken Sie in Visual Studio in Projektmappen-Explorer mit der rechten Maustaste auf das Projekt WebView2APISample (nicht auf den Darüber stehenden Projektmappenknoten), und wählen Sie dann NuGet-Pakete verwalten aus.

   Der Bereich NuGet-Paket-Manager wird in Visual Studio geöffnet.

4. Klicken Sie im NuGet-Paket-Manager auf die Registerkarte Installiert :

   

5. Aktivieren Sie rechts neben dem Textfeld Suchen das Kontrollkästchen Vorabversion einschließen .

6. Wählen Sie auf der linken Seite Microsoft.Web.WebView2 aus.

7. Wählen Sie auf der rechten Seite in der Dropdownliste Version die neueste Vorabversion aus.

8. Klicken Sie rechts neben der Dropdownliste Version auf die Schaltfläche Aktualisieren .

   Das Dialogfeld Vorschau der Änderungen wird geöffnet:

   

9. Klicken Sie auf die Schaltfläche Übernehmen .

10. Wiederholen Sie die oben genannten Schritte, um die Microsoft.Windows.Implementation.Library zu aktualisieren, aber Sie können das neueste Release anstelle der neuesten Vorabversion auswählen.

    Die neueste Vorabversion des WebView2 SDK ist jetzt für dieses Projekt installiert.

Siehe auch:

• Phasen des Hinzufügens von APIs in Den Anmerkungen zu dieser Version für das WebView2 SDK.

Schritt 9: Erstellen und Ausführen mit dem aktualisierten SDK

Wenn Sie die Vorabversion des WebView2 SDK aktualisiert haben, erstellen Sie das Beispiel, und führen Sie es erneut aus:

1. Klicken Sie Projektmappen-Explorer mit der rechten Maustaste auf das Projekt WebView2APISample, und wählen Sie dann Erstellen aus.

2. Wählen Sie Debuggen>Debuggen starten (F5) aus.

   Das App-Fenster WebView2APISample wird geöffnet:

   

3. Schließen Sie das Beispiel-App-Fenster.

Sie haben die Win32-Beispiel-App abgerufen, aktualisiert, erstellt und ausgeführt.

Schritt 10: Untersuchen der Stichprobe

In den folgenden Abschnitten wird die Funktionsweise des Beispiels beschrieben.

Anzeigen der Projektdateien

Bei diesen Schritten wird davon ausgegangen, dass Sie die Win32-Beispiel-App gemäß den oben genannten Schritten abgerufen, aktualisiert, erstellt und ausgeführt haben.

Das WebView2APISample-Beispiel und -Projekt ist das Standard Win32-Beispiel.

1. Öffnen Sie WebView2Samples.sln in Visual Studio.

   Beispielpfad:

   C:\Users\localAccount\GitHub\WebView2Samples\SampleApps\WebView2Samples.sln
   

   Diese Lösungsdatei enthält das Standard-Beispiel (WebView2APISample) und weitere Beispiele:

   

2. Erweitern Sie Projektmappen-Explorer das Projekt WebView2APISample:

   

Hybrid-App-Architektur

Die WebView2APISample-App ist ein Beispiel für eine Hybridanwendung mit einem nativen Win32-Teil und einem WebView-Teil:

• Der Win32-Teil kann direkt auf native Windows-APIs zugreifen. Der oberste Teil der WebView2APISample-App ist eine Win32-Komponente, die in C++ geschrieben wurde. Dieser Teil der Anwendung akzeptiert Benutzeroberflächeneingaben vom Benutzer und verwendet sie, um die WebView zu steuern.

• WebView ist ein Container für Standardwebtechnologien (HTML, CSS und JavaScript). Der Standard Teil der WebView2APISample-App ist eine WebView, die mithilfe von Standardwebtechnologien (HTML/CSS/JavaScript) umfunktioniert werden kann. Die WebView kann zu Websites oder lokalen Inhalten navigiert werden.

Dieser Hybridansatz ermöglicht es Ihnen, mithilfe von Webtechnologien schneller zu erstellen und zu durchlaufen, während Sie gleichzeitig native Funktionen nutzen können. Die WebView2APISample-App zeigt, wie die Win32-Komponente und die WebView-Komponente miteinander interagieren können.

Diese Beispiel-App verfügt über mehr als 100 Menüelemente, die viele WebView2-APIs im Win32/C++-Framework veranschaulichen. Die folgenden Abschnitte konzentrieren sich auf die Grundlagen der Hybrid-App-Implementierung.

Projektdateien

In diesem Abschnitt werden einige wichtige Dateien im Repository kurz erläutert. Die WebView2APISample-App ist vertikal in Komponenten und nicht horizontal in Ebenen unterteilt. Jede Komponente implementiert den gesamten Workflow einer Kategorie von Beispielfeatures, vom Lauschen auf Menübefehle bis hin zum Aufrufen von WebView-API-Methoden, um sie zu implementieren.

App.cpp

Dies ist die Datei der obersten Ebene, die die WebView2APISample-App ausführt. Es liest Befehlszeilenoptionen, richtet die Prozessumgebung ein und verarbeitet das Threadingmodell der App.

AppWindow.cpp (Fenstermenü)

Diese Datei implementiert das Anwendungsfenster wie folgt:

1. Richten Sie alle Win32-Steuerelemente ein.

2. Initialisieren Sie die WebView-Umgebung und die WebView.

3. Fügen Sie der WebView Ereignishandler hinzu, und erstellen Sie alle Komponenten, die verschiedene Features der Anwendung behandeln.

Die AppWindow -Klasse verarbeitet Befehle aus dem Fenstermenü der Beispiel-App.

Diese Datei wird weiter unten unter Schlüsselfunktionen in AppWindow.cpp ausführlicher beschrieben.

FileComponent.cpp (Menü Datei)

Diese Komponente verarbeitet Befehle aus dem Menü Datei (mit Ausnahme von Exit) sowie das DocumentTitleChanged -Ereignis.

ScriptComponent.cpp (Skriptmenü)

Diese Komponente verarbeitet Befehle aus dem Menü Skript , bei denen die Interaktion mit der WebView durch Einfügen von JavaScript, Bereitstellen von WebMessages, Hinzufügen nativer Objekte zur Webseite oder Verwenden des DevTools-Protokolls für die Kommunikation mit der Webseite erfolgt.

ProcessComponent.cpp (Menü "Prozess")

Diese Komponente verarbeitet Befehle aus dem Menü Prozess , die eine Interaktion mit dem Prozess des Browsers beinhalten. Es behandelt auch das ProcessFailed -Ereignis, falls der Browserprozess oder einer seiner Renderprozesse abstürzt oder nicht reagiert.

SettingsComponent.cpp (Menü Einstellungen)

Diese Komponente verarbeitet Befehle aus dem Menü Einstellungen . Diese Komponente ist auch für das Kopieren von Einstellungen aus einer alten WebView zuständig, wenn eine neue erstellt wird. Der meiste Code, der mit der ICoreWebView2Settings -Schnittstelle interagiert, finden Sie hier.

ViewComponent.cpp (Menü Ansicht)

Diese Komponente verarbeitet Befehle aus dem Menü Ansicht sowie alle Funktionen im Zusammenhang mit der Dimensionierung und Sichtbarkeit der WebView. Wenn die Größe des App-Fensters geändert, minimiert oder wiederhergestellt wird, ViewComponent ändert die Größe, blendet oder zeigt die WebView als Antwort an. Außerdem wird auf das ZoomFactorChanged Ereignis reagiert.

ScenarioWebMessage.cpp und ScenarioWebMessage.html (Menü "Szenario")

Die ScenarioWebMessage Komponente wird erstellt, wenn Sie das Menüelement Scenario>Web Messaging auswählen. Diese Komponente implementiert eine Beispielanwendung mit einem C++-Teil und einem HTML + JavaScript-Teil, die miteinander kommunizieren, indem Nachrichten asynchron bereitgestellt und empfangen werden.

Diese Komponente wird unter ScenarioWebMessage (.html, .cpp und .h) weiter unten ausführlicher beschrieben.

ScenarioAddHostObject.cpp und ScenarioAddHostObject.html (Menü Szenario)

Diese Komponente wird erstellt, wenn Sie das MenüelementSzenariohostobjekte> auswählen. Es veranschaulicht die Kommunikation zwischen der nativen App und der HTML-Webseite mittels Hostobjektinjektion. Die Schnittstelle des Hostobjekts wird in HostObjectSample.idldeklariert, und das Objekt selbst wird in HostObjectSampleImpl.cppimplementiert.

Siehe auch:

• Aufrufen von systemeigenem Code aus webseitigem Code

Wichtige Funktionen in AppWindow.cpp

AppWindow.cpp implementiert das Anwendungsfenster wie folgt:

1. Richten Sie alle Win32-Steuerelemente ein.

2. Initialisieren Sie die WebView-Umgebung und die WebView.

3. Fügen Sie der WebView Ereignishandler hinzu, und erstellen Sie alle Komponenten, die verschiedene Features der Anwendung behandeln.

Die AppWindow -Klasse verarbeitet Befehle aus dem Fenstermenü der Beispiel-App. Im Folgenden sind einige der wichtigsten Funktionen in AppWindow.cppaufgeführt.

InitializeWebView()

In AppWindow.cpperstellt die InitializeWebView() Funktion die WebView2-Umgebung mithilfe von CreateCoreWebView2EnvironmentWithOptions.

Um diese API-Aufrufe in Aktion zu sehen, überprüfen Sie den folgenden Code von InitializeWebView():

HRESULT hr = CreateCoreWebView2EnvironmentWithOptions(
    subFolder, nullptr, options.Get(),
    Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
        this, &AppWindow::OnCreateEnvironmentCompleted)
        .Get());
if (!SUCCEEDED(hr))
{
    if (hr == HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND))
    {
        MessageBox(
            m_mainWindow,
            L"Couldn't find Edge installation. "
            "Do you have a version installed that's compatible with this "
            "WebView2 SDK version?",
            nullptr, MB_OK);
    }
    else
    {
        ShowFailure(hr, L"Failed to create webview environment");
    }
}

OnCreateEnvironmentCompleted()

Nach dem Erstellen der Umgebung erstellen wir die WebView mithilfe CreateCoreWebView2Controllervon .

Die OnCreateEnvironmentCompleted Rückruffunktion wird in CreateCoreWebView2EnvironmentWithOptionsInitializeWebView()an übergeben. Der Rückruf speichert den Umgebungszeiger und verwendet ihn dann, um eine neue WebView zu erstellen:

HRESULT AppWindow::OnCreateEnvironmentCompleted(
    HRESULT result, ICoreWebView2Environment* environment)
{
    CHECK_FAILURE(result);

    m_webViewEnvironment = environment;

    CHECK_FAILURE(m_webViewEnvironment->CreateCoreWebView2Controller(
        m_mainWindow, Callback<ICoreWebView2CreateCoreWebView2ControllerCompletedHandler>(
                            this, &AppWindow::OnCreateCoreWebView2ControllerCompleted)
                            .Get()));
    return S_OK;
}

OnCreateCoreWebView2ControllerCompleted()

Die OnCreateCoreWebView2ControllerCompleted Rückruffunktion wird in CreateCoreWebView2ControllerInitializeWebView()an übergeben. Dieser Rückruf:

• Initialisiert den WebView-bezogenen Zustand.
• Registriert einige Ereignishandler.
• Erstellt die App-Komponenten.

RegisterEventHandlers()

Die RegisterEventHandlers Funktion wird in CreateCoreWebView2Controlleraufgerufen. Es richtet einige der von der Anwendung verwendeten Ereignishandler ein und fügt sie der WebView hinzu.

Weitere Informationen zu Ereignishandlern in WebView2 finden Sie unter ICoreWebView2.

Im Folgenden finden Sie einen Codeausschnitt aus RegisterEventHandlers(), in dem wir einen Ereignishandler für das NewWindowRequested -Ereignis einrichten. Dieses Ereignis wird ausgelöst, wenn JavaScript auf der Webseite aufruft window.open(). ICoreWebView2NewWindowRequestedEventHandlererstellt eine neue AppWindow und übergibt die WebView des neuen Fensters zurück an den Browser, damit sie vom window.open() Aufruf zurückgegeben werden kann. Im Gegensatz zu unseren Aufrufen von CreateCoreWebView2EnvironmentWithOptions und CreateCoreWebView2Controllerwird anstelle einer -Methode für den Rückruf nur ein C++-Lambda direkt und dort bereitgestellt:

CHECK_FAILURE(m_webView->add_NewWindowRequested(
    Callback<ICoreWebView2NewWindowRequestedEventHandler>(
        [this](
            ICoreWebView2* sender,
            ICoreWebView2NewWindowRequestedEventArgs* args) {
            wil::com_ptr<ICoreWebView2Deferral> deferral;
            CHECK_FAILURE(args->GetDeferral(&deferral));

            auto newAppWindow = new AppWindow(L"");
            newAppWindow->m_isPopupWindow = true;
            newAppWindow->m_onWebViewFirstInitialized = [args, deferral, newAppWindow]() {
                CHECK_FAILURE(args->put_NewWindow(newAppWindow->m_webView.get()));
                CHECK_FAILURE(args->put_Handled(TRUE));
                CHECK_FAILURE(deferral->Complete());
            };

            return S_OK;
        })
        .Get(),
    nullptr));

ScenarioWebMessage (.html, .cpp und .h)

Die ScenarioWebMessage Dateien zeigen, wie der Win32-Host die WebView ändern kann, wie die WebView den Win32-Host ändern kann und wie die WebView sich selbst ändern kann, indem auf Informationen vom Win32-Host zugegriffen wird. Dies erfolgt asynchron.

Die ScenarioWebMessage Komponente wird erstellt, wenn Sie das Menüelement Scenario>Web Messaging auswählen. Die ScenarioWebMessage Komponente implementiert eine Beispielanwendung mit einem C++-Teil und einem HTML+JavaScript-Teil, die miteinander kommunizieren, indem Nachrichten asynchron bereitgestellt und empfangen werden:

In den folgenden Abschnitten wird veranschaulicht, wie jede einzelne Funktion mit der WebView2APISample-App funktioniert. Anschließend wird erläutert, wie diese Funktionalität implementiert wird.

Wechseln Sie zunächst zur Web-App ScenarioWebMessage innerhalb der Beispiel-App:

1. Öffnen (ausführen) Sie die WebView2APISample-App .

2. Wählen Sie im Menü Szenario die Option Webmessaging aus.

   Die WebView zeigt eine Webseite mit dem Titel WebMessage-Beispielseite (ScenarioWebMessage.html):

   

Um die ScenarioWebMessage Funktionalität zu erkunden, können Sie den Anweisungen auf der Seite folgen oder die folgenden Schritte ausführen.

Veröffentlichen von Nachrichten vom Win32-Host in der WebView

Die folgenden Schritte zeigen, wie der Win32-Host eine WebView ändern kann. In diesem Beispiel wird der Text blau gedreht:

1. Öffnen Sie die WebMessage-Beispielseite (ScenarioWebMessage.html) wie oben beschrieben.

2. Wählen Sie im Menü Skript die Option Post Web Message JSON aus.

   Ein Dialogfeld mit dem vorgeschriebenen Code {"SetColor":"blue"} wird angezeigt.

3. Klicken Sie auf OK.

   Der Text im Abschnitt Posten von Nachrichten der Seite ändert sich von Schwarz in Blau.

So funktioniert es

1. In ScriptComponent.cppsendet der Aufruf von PostWebMessageAsJson Benutzereingaben an die ScenarioMessage.html Webanwendung:

   // Prompt the user for some JSON and then post it as a web message.
   void ScriptComponent::SendJsonWebMessage()
   {
      TextInputDialog dialog(
         m_appWindow->GetMainWindow(),
         L"Post Web Message JSON",
         L"Web message JSON:",
         L"Enter the web message as JSON.",
         L"{\"SetColor\":\"blue\"}");
      if (dialog.confirmed)
      {
         m_webView->PostWebMessageAsJson(dialog.input.c_str());
      }
   }
   

2. Innerhalb der Webanwendung werden Ereignislistener verwendet, um die Webnachricht zu empfangen und darauf zu reagieren. Der folgende Codeausschnitt stammt aus ScenarioWebMessage.html. Der Ereignislistener ändert die Farbe des Texts, wenn das Argument "SetColor" lautet:

   window.chrome.webview.addEventListener('message', arg => {
      if ("SetColor" in arg.data) {
         document.getElementById("colorable").style.color = arg.data.SetColor;
      }
   });
   

Empfangen von Nachrichten (von der WebView an den Win32-Host)

Die folgenden Schritte zeigen, wie webView die Win32-Host-App ändern kann, indem der Titel der Win32-App geändert wird:

1. Öffnen Sie die WebMessage-Beispielseite (ScenarioWebMessage.html) wie oben beschrieben.

2. Notieren Sie sich den Titel der WebView2APISample-App , die oben links im Fenster neben dem Symbol angezeigt wird. Es handelt sich zunächst um WebView2APISample – Microsoft Edge WebView2.

3. Geben Sie auf der Seite im Abschnitt Empfangene Nachrichten einen neuen Titel ein, und klicken Sie dann auf die Schaltfläche Senden .

4. Notieren Sie sich den neuen Titel, der in der Titelleiste der WebView2APISample-App angezeigt wird.

So funktioniert es

1. In ScenarioWebMessage.htmlsendet window.chrome.webview.postMessage() die Benutzereingabe an die Hostanwendung:

   function SetTitleText() {
      let titleText = document.getElementById("title-text");
      window.chrome.webview.postMessage(`SetTitleText ${titleText.value}`);
   }
   

2. In ScenarioWebMessage.cppverwenden wir add_WebMessageReceived , um den Ereignishandler zu registrieren. Wenn wir das Ereignis empfangen, ändern wir nach dem Überprüfen der Eingabe den Titel des App-Fensters (m_appWindow):

   // Setup the web message received event handler before navigating to
   // ensure we don't miss any messages.
   CHECK_FAILURE(m_webview->add_WebMessageReceived(
      Microsoft::WRL::Callback<ICoreWebView2WebMessageReceivedEventHandler>(
         [this](ICoreWebView2* sender, ICoreWebView2WebMessageReceivedEventArgs* args)
   {
      wil::unique_cotaskmem_string uri;
      CHECK_FAILURE(args->get_Source(&uri));
   
      // Always validate that the origin of the message is what you expect.
      if (uri.get() != m_sampleUri)
      {
         return S_OK;
      }
      wil::unique_cotaskmem_string messageRaw;
      CHECK_FAILURE(args->TryGetWebMessageAsString(&messageRaw));
      std::wstring message = messageRaw.get();
   
      if (message.compare(0, 13, L"SetTitleText ") == 0)
      {
         m_appWindow->SetTitleText(message.substr(13).c_str());
      }
      return S_OK;
   }).Get(), &m_webMessageReceivedToken));
   

Roundtripnachrichten (von der WebView zum Host zurück zur WebView)

Die folgenden Schritte zeigen, wie webView Informationen vom Win32-Host abrufen und sich selbst ändern kann, indem die Größe der Win32-App angezeigt wird.

1. Öffnen Sie die WebMessage-Beispielseite (ScenarioWebMessage.html) wie oben beschrieben.

2. Klicken Sie im Abschnitt Roundtrip der Seite auf die Schaltfläche GetWindowBounds .

   Das Textfeld unter der Schaltfläche zeigt die Begrenzungen für die WebView2APISample-App an.

So funktioniert es

1. Wenn auf die Schaltfläche Get window bounds (Fenstergrenzen abrufen) geklickt wird, wird die GetWindowBounds Funktion in ScenarioWebMessage.html aufgerufen. GetWindowBounds ruft window.chrome.webview.postMessage() auf, um eine Nachricht an die Hostanwendung zu senden:

   function GetWindowBounds() {
       window.chrome.webview.postMessage("GetWindowBounds");
   }
   

2. In ScenarioWebMessage.cppwird add_WebMessageReceived verwendet, um den empfangenen Ereignishandler zu registrieren. Nach dem Überprüfen der Eingabe ruft der Ereignishandler Fenstergrenzen aus dem App-Fenster ab. PostWebMessageAsJson sendet die Begrenzungen an die Webanwendung:

   if (message.compare(L"GetWindowBounds") == 0)
   {
      RECT bounds = m_appWindow->GetWindowBounds();
      std::wstring reply =
         L"{\"WindowBounds\":\"Left:" + std::to_wstring(bounds.left)
         + L"\\nTop:" + std::to_wstring(bounds.top)
         + L"\\nRight:" + std::to_wstring(bounds.right)
         + L"\\nBottom:" + std::to_wstring(bounds.bottom)
         + L"\"}";
      CHECK_FAILURE(sender->PostWebMessageAsJson(reply.c_str()));
   }
   

3. In ScenarioWebMessage.htmlantwortet ein Ereignislistener auf die WindowBounds Nachricht und zeigt die Grenzen des Fensters an:

   window.chrome.webview.addEventListener('message', arg => {
      if ("WindowBounds" in arg.data) {
         document.getElementById("window-bounds").value = arg.data.WindowBounds;
      }
   });
   

Siehe auch

• WebView2-API-Referenz
• Erste Schritte mit WebView2 in Win32-Apps
• Übersicht über WebView2-APIs
• Phasen des Hinzufügens von APIs in Den Anmerkungen zu dieser Version für das WebView2 SDK.