Erste Schritte mit WebView2 in Win32-Apps

Beginnen Sie in diesem Artikel mit dem Erstellen Ihrer ersten WebView2-App, und erfahren Sie mehr über die Hauptfeatures von WebView2. Für weitere Informationen zu einzelnen WebView2-APIs navigieren Sie zur API-Referenz.

Hinweis

Dieses Lernprogramm bezieht sich auf WebView2-Beispiele. Navigieren Sie zum Anzeigen oder Kopieren von Beispielcode zu WebView2-Beispielcode.

Voraussetzungen

Stellen Sie sicher, dass Sie die folgende Liste der erforderlichen Komponenten installieren, bevor Sie fortfahren.

Schritt 1: Erstellen einer Einzelfenster-App

Beginnen Sie mit einem einfachen Desktopprojekt, das ein einzelnes Hauptfenster enthält.

Wichtig

Um sich besser auf die exemplarische Vorgehensweise zu konzentrieren, verwenden Sie den geänderten Beispielcode aus walkthrough: Create a traditional Windows Desktop application (C++) für Ihre Beispiel-App. Navigieren Sie zu WebView2-Beispielen,um das geänderte Beispiel herunterzuladen und zu beginnen.

  1. Öffnen Sie in Visual Studio WebView2GettingStarted.sln . Wenn Sie eine ältere Version von Visual Studio verwenden, zeigen Sie auf das WebView2GettingStarted-Projekt, öffnen Sie das Kontextmenü (Rechtsklick), und wählen Sie Eigenschaftenaus. Ändern Sie unter "Konfigurationseigenschaften > allgemein" Windows SDK-Versions- und Plattformtoolset, um das Win10 SDK und Visual Studio Toolset zu verwenden, das Ihnen zur Verfügung steht.

Toolversion

Visual Studio können Fehler anzeigen, da dem Projekt die WebView2-Headerdatei fehlt. Die Fehler sollten nach Schritt 2behoben werden.

Schritt 2: Installieren des WebView2 SDK

Fügen Sie das WebView2 SDK zum Projekt hinzu. Verwenden Sie NuGet, um das Win32 SDK zu installieren.

  1. Zeigen Sie auf das Projekt, öffnen Sie das Kontextmenü (rechtsklick), und wählen Sie "Verwalten NuGet Pakete" aus.

    NuGet-Pakete verwalten

  2. Installieren Sie die Windows Implementierungsbibliothek.

    1. Geben Sie in der Suchleiste Microsoft.Windows.ImplementationLibrary > Wählen Sie "Microsoft.Windows" aus. ImplementationLibrary.

    2. Wählen Sie im rechten Fenster die Option "Installieren" aus. NuGet lädt die Bibliothek auf Ihren Computer herunter.

      Hinweis

      Die Windows-Implementierungsbibliothek und Windows Runtime-C++-Vorlagenbibliothek sind optional und erleichtern das Arbeiten mit COM für das Beispiel.

      Windows Implementierungsbibliothek

  3. Installieren Sie das WebView2 SDK.

    1. Geben Sie in der Suchleiste Microsoft.Web.WebView2 > wählen Sie Microsoft.Web.WebView2aus.

    2. Wählen Sie im rechten Fenster die Option "Installieren" aus. NuGet lädt das SDK auf Ihren Computer herunter.

      NuGet Paket-Manager

  4. Fügen Sie WebView2-Header zu Ihrem Projekt hinzu.

    Kopieren Sie in der HelloWebView.cpp Datei den folgenden Codeausschnitt, und fügen Sie ihn nach der letzten #include Zeile ein.

    // include WebView2 header
    #include "WebView2.h"
    

    Der Include-Abschnitt sollte dem folgenden Codeausschnitt ähneln.

    ...
    #include <wrl.h>
    #include <wil/com.h>
    // include WebView2 header
    #include "WebView2.h"
    

Bereit für die Verwendung und Erstellung für die WebView2-API.

Erstellen Einer leeren Beispiel-App

Um die Beispiel-App zu erstellen und auszuführen, wählen Sie F5 . Ihre App zeigt ein leeres Fenster an.

Leere App

Schritt 3: Erstellen einer einzelnen WebView im übergeordneten Fenster

Fügen Sie dem Hauptfenster eine WebView hinzu.

Verwenden Sie die CreateCoreWebView2Environment Methode, um die Umgebung einzurichten und den Microsoft Edge Browser zu suchen, der das Steuerelement ansteuert. Sie können die Methode auch verwenden, wenn Sie den CreateCoreWebView2EnvironmentWithOptions Speicherort des Browsers, den Benutzerordner, Browserflags usw. anstelle der Standardeinstellung angeben möchten. Führen Sie nach Abschluss der CreateCoreWebView2Environment Methode die Methode innerhalb des ICoreWebView2Environment::CreateCoreWebView2Controller ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler Rückrufs aus, und führen Sie die ICoreWebView2Controller::get_CoreWebView2 Methode aus, um die zugeordnete WebView abzurufen.

Legen Sie im Rückruf einige weitere Einstellungen fest, ändern Sie die Größe von WebView auf 100 % des übergeordneten Fensters, und navigieren Sie zu Bing.

Kopieren Sie den folgenden Codeausschnitt, und fügen Sie ihn HelloWebView.cpp nach dem Kommentar und vor dem Kommentar // <-- WebView2 sample code starts here --> // <-- WebView2 sample code ends here --> ein.

// Step 3 - Create a single WebView within the parent window
// Locate the browser and set up the environment for WebView
CreateCoreWebView2EnvironmentWithOptions(nullptr, nullptr, nullptr,
    Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
        [hWnd](HRESULT result, ICoreWebView2Environment* env) -> HRESULT {

            // Create a CoreWebView2Controller and get the associated CoreWebView2 whose parent is the main window hWnd
            env->CreateCoreWebView2Controller(hWnd, Callback<ICoreWebView2CreateCoreWebView2ControllerCompletedHandler>(
                [hWnd](HRESULT result, ICoreWebView2Controller* controller) -> HRESULT {
                if (controller != nullptr) {
                    webviewController = controller;
                    webviewController->get_CoreWebView2(&webviewWindow);
                }

                // Add a few settings for the webview
                // The demo step is redundant since the values are the default settings
                ICoreWebView2Settings* Settings;
                webviewWindow->get_Settings(&Settings);
                Settings->put_IsScriptEnabled(TRUE);
                Settings->put_AreDefaultScriptDialogsEnabled(TRUE);
                Settings->put_IsWebMessageEnabled(TRUE);

                // Resize WebView to fit the bounds of the parent window
                RECT bounds;
                GetClientRect(hWnd, &bounds);
                webviewController->put_Bounds(bounds);

                // Schedule an async task to navigate to Bing
                webviewWindow->Navigate(L"https://www.bing.com/");

                // Step 4 - Navigation events

                // Step 5 - Scripting

                // Step 6 - Communication between host and web content

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

Erstellen Ihrer Bing-Beispiel-App

Um die App zu erstellen und auszuführen, wählen Sie F5 . Nun wird in einem WebView-Fenster die Bing Seite angezeigt.

Bing Fenster

Schritt 4: Navigationsereignisse

Das WebView2-Team hat bereits im letzten Schritt die Navigation zur URL mithilfe ICoreWebView2::Navigate der Methode behandelt. Während der Navigation löst WebView eine Abfolge von Ereignissen aus, auf die der Host lauscht.

  1. NavigationStarting
  2. SourceChanged
  3. ContentLoading
  4. HistoryChanged
  5. NavigationCompleted

Navigieren Sie zu Navigationsereignissen,um weitere Informationen zu erfahren.

Navigationsereignisse

In Fehlerfällen kann eines oder mehrere der folgenden Ereignisse auftreten, je nachdem, ob die Navigation zu einer Fehlerwebseite fortgesetzt wurde.

  • SourceChanged
  • ContentLoading
  • HistoryChanged

Hinweis

Wenn eine HTTP-Umleitung erfolgt, gibt es mehrere NavigationStarting Ereignisse in einer Zeile.

Registrieren Sie als Beispiel für die Verwendung der Ereignisse einen Handler für das NavigationStarting Ereignis, um alle Nicht-HTTPS-Anforderungen abzubrechen. Kopieren Sie den folgenden Codeausschnitt, und fügen Sie ihn in HelloWebView.cpp .

// register an ICoreWebView2NavigationStartingEventHandler to cancel any non-https navigation
EventRegistrationToken token;
webviewWindow->add_NavigationStarting(Callback<ICoreWebView2NavigationStartingEventHandler>(
    [](ICoreWebView2* webview, ICoreWebView2NavigationStartingEventArgs * args) -> HRESULT {
        PWSTR uri;
        args->get_Uri(&uri);
        std::wstring source(uri);
        if (source.substr(0, 5) != L"https") {
            args->put_Cancel(true);
        }
        CoTaskMemFree(uri);
        return S_OK;
    }).Get(), &token);

Jetzt navigiert die App nicht mehr zu websites, die nicht https sind. Sie können einen ähnlichen Mechanismus verwenden, um andere Aufgaben auszuführen, z. B. das Einschränken der Navigation auf Ihre eigene Domäne.

Schritt 5 – Skripting

Sie können Host-Apps verwenden, um JavaScript-Code zur Laufzeit in WebView2-Steuerelemente einzufügen. Sie können WebView zum Ausführen beliebigen JavaScripts oder zum Hinzufügen von Initialisierungsskripts verwenden. Das eingefügte JavaScript gilt für alle neuen Dokumente der obersten Ebene und alle untergeordneten Frames, bis javaScript entfernt wird. Das eingefügte JavaScript wird mit einem bestimmten Timing ausgeführt.

  • Führen Sie es nach der Erstellung des globalen Objekts aus.
  • Führen Sie es aus, bevor ein anderes skript, das im HTML-Dokument enthalten ist, ausgeführt wird.

Kopieren Sie den folgenden Codeausschnitt, und fügen Sie ihn in HelloWebView.cpp .

// Schedule an async task to add initialization script that freezes the Object object
webviewWindow->AddScriptToExecuteOnDocumentCreated(L"Object.freeze(Object);", nullptr);
// Schedule an async task to get the document URL
webviewWindow->ExecuteScript(L"window.document.URL;", Callback<ICoreWebView2ExecuteScriptCompletedHandler>(
    [](HRESULT errorCode, LPCWSTR resultObjectAsJson) -> HRESULT {
        LPCWSTR URL = resultObjectAsJson;
        //doSomethingWithURL(URL);
        return S_OK;
    }).Get());

Jetzt sollte WebView das Objekt immer fixieren Object und das Seitendokument einmal zurückgeben.

Hinweis

Die Skripteinfügungs-APIs (und einige andere WebView2-APIs) sind asynchron. Sie sollten Rückrufe verwenden, wenn Code in einer bestimmten Reihenfolge ausgeführt werden muss.

Schritt 6 : Kommunikation zwischen Host- und Webinhalten

Der Host und der Webinhalt können auch über die Methode miteinander postMessage kommunizieren. Der in einer WebView ausgeführte Webinhalt kann über die Methode an den Host gesendet window.chrome.webview.postMessage werden, und die Nachricht wird von jedem registrierten ICoreWebView2WebMessageReceivedEventHandler Ereignishandler auf dem Host verarbeitet. Ebenso kann der Host die Nachricht an den Webinhalt oder die ICoreWebView2::PostWebMessageAsString ICoreWebView2::PostWebMessageAsJSON Methode senden, die von Handlern abgefangen wird, die vom Listener hinzugefügt window.chrome.webview.addEventListener wurden. Der Kommunikationsmechanismus ermöglicht es dem Webinhalt, systemeigene Funktionen zu verwenden, indem Nachrichten übergeben werden, um den Host aufzufordern, systemeigene APIs auszuführen.

Um den Mechanismus zu verstehen, werden die folgenden Schritte ausgeführt, wenn Sie versuchen, die Dokument-URL in WebView auszugeben.

  1. Der Host registriert einen Handler, um empfangene Nachrichten an den Webinhalt zurückzugeben
  2. Der Host fügt ein Skript in den Webinhalt ein, der einen Handler zum Drucken von Nachrichten vom Host registriert.
  3. Der Host fügt ein Skript in den Webinhalt ein, der die URL an den Host sendet
  4. Der Handler des Hosts wird ausgelöst und gibt die Nachricht (die URL) an den Webinhalt zurück.
  5. Der Handler des Webinhalts wird ausgelöst und druckt die Nachricht vom Host (die URL)

Kopieren Sie den folgenden Codeausschnitt, und fügen Sie ihn in HelloWebView.cpp .

// Set an event handler for the host to return received message back to the web content
webviewWindow->add_WebMessageReceived(Callback<ICoreWebView2WebMessageReceivedEventHandler>(
    [](ICoreWebView2* webview, ICoreWebView2WebMessageReceivedEventArgs * args) -> HRESULT {
        PWSTR message;
        args->TryGetWebMessageAsString(&message);
        // processMessage(&message);
        webview->PostWebMessageAsString(message);
        CoTaskMemFree(message);
        return S_OK;
    }).Get(), &token);

// Schedule an async task to add initialization script that
// 1) Add an listener to print message from the host
// 2) Post document URL to the host
webviewWindow->AddScriptToExecuteOnDocumentCreated(
    L"window.chrome.webview.addEventListener(\'message\', event => alert(event.data));" \
    L"window.chrome.webview.postMessage(window.document.URL);",
nullptr);

Erstellen der Beispiel-APP für die Anzeige-URL

Um die App zu erstellen und auszuführen, wählen Sie F5 . Die URL wird in einem Popupfenster angezeigt, bevor Sie zu einer Webseite navigieren.

Anzeige-URL

Herzlichen Glückwunsch, Sie haben Ihre erste WebView2-App erstellt!

Nächste Schritte

Weitere WebView2-Funktionen, die in diesem Artikel nicht behandelt werden, finden Sie in den folgenden Ressourcen.