Erste Schritte mit WebView2Getting started with WebView2

Beginnen Sie in diesem Artikel mit dem Erstellen Ihrer ersten WebView2-App, und erfahren Sie mehr über die Hauptfeatures von WebView2.In this article, get started creating your first WebView2 app and learn about the main features of WebView2. Weitere Informationen zu einzelnen WebView2-APIs finden Sie unter API-Referenz.For more information about individual WebView2 APIs, navigate to API reference.

VoraussetzungenPrerequisites

Stellen Sie sicher, dass Sie die folgende Liste der Voraussetzungen installieren, bevor Sie fortfahren.Ensure you install the following list of pre-requisites before proceeding.

  • WebView2-Laufzeit oder ein nicht stabiler Microsoft Edge (Chromium)-Kanal, der unter unterstützten Betriebssystemen installiert ist (derzeit Windows 10, Windows 8.1 und Windows 7).WebView2 Runtime or any Microsoft Edge (Chromium) non-stable channel installed on supported OS (currently Windows 10, Windows 8.1, and Windows 7).

    Hinweis

    Das WebView-Team empfiehlt die Verwendung des Canary-Kanals, und die erforderliche Mindestversion ist 82.0.488.0.The WebView team recommends using the Canary channel and the minimum required version is 82.0.488.0.

  • Visual Studio 2015 oder höher mit installierter C++-Unterstützung.Visual Studio 2015 or later with C++ support installed.

Schritt 1 : Erstellen einer App mit einem FensterStep 1 - Create a single-window app

Beginnen Sie mit einem einfachen Desktopprojekt, das ein einzelnes Hauptfenster enthält.Start with a basic desktop project that contains a single main window.

Wichtig

Um die exemplarische Vorgehensweise besser zu fokussieren, verwenden Sie geänderten Beispielcode aus Walkthrough: Create a traditional Windows Desktop application (C++) for your sample app.To better focus the walkthrough, use modified sample code from Walkthrough: Create a traditional Windows Desktop application (C++) for your sample app. Um das geänderte Beispiel herunterzuladen und zu beginnen, navigieren Sie zu WebView2 Samples.To download the modified sample and get started, navigate to WebView2 Samples.

  1. Öffnen Visual Studio in der Datei WebView2GettingStarted.sln .In Visual Studio, open WebView2GettingStarted.sln.
    Wenn Sie eine ältere Version von Visual Studio verwenden, zeigen Sie auf das WebView2GettingStarted-Projekt, öffnen Sie das Kontextmenü (rechtsklicken), und wählen Sie Eigenschaften aus.If you use an older version of Visual Studio, hover on the WebView2GettingStarted project, open the contextual menu (right-click), and choose Properties. Ändern Sie unter KonfigurationseigenschaftenAllgemein windows SDK Version und Platform Toolset so, dass sie das > **** Win10 SDK und Visual Studio toolset verwenden, das Ihnen zur **** Verfügung steht. ****Under Configuration Properties > General, modify Windows SDK Version and Platform Toolset to use the Win10 SDK and Visual Studio toolset available to you.

Toolversion

Visual Studio können Fehler angezeigt werden, da in Ihrem Projekt die WebView2-Headerdatei fehlt.Visual Studio may display errors, because your project is missing the WebView2 header file. Die Fehler sollten nach Schritt 2 behoben werden.The errors should be fixed after Step 2.

Schritt 2 : Installieren des WebView2 SDKStep 2 - Install WebView2 SDK

Fügen Sie dem Projekt das WebView2 SDK hinzu.Add the WebView2 SDK into the project. Verwenden Sie NuGet, um das Win32 SDK zu installieren.Use NuGet to install the Win32 SDK.

  1. Zeigen Sie auf das Projekt, öffnen Sie das Kontextmenü (klicken Sie mit der rechten Maustaste), und wählen Sie NuGet-Pakete verwalten aus.Hover on the project, open the contextual menu (right-click), and choose Manage NuGet Packages.

    NuGet-Pakete verwalten

  2. Installieren Sie die Windows-Implementierungsbibliothek.Install the Windows Implementation Library.

    1. Geben Sie in der Suchleiste Microsoft.Windows.ImplementationLibrary > Wählen Sie Microsoft.Windows.ImplementationLibrary aus.In the search bar, type Microsoft.Windows.ImplementationLibrary > choose Microsoft.Windows.ImplementationLibrary.

    2. Wählen Sie im rechten Fenster Installieren aus.In the right-hand side window, choose Install. NuGet lädt die Bibliothek auf Ihren Computer herunter.NuGet downloads the library to your machine.

      Hinweis

      Die Windows-Implementierungsbibliothek und die Windows-Runtime-C++-Vorlagenbibliothek sind optional und erleichtern das Arbeiten mit COM für das Beispiel.The Windows Implementation Library and Windows Runtime C++ Template Library are optional and make working with COM easier for the example.

      Windows-Implementierungsbibliothek

  3. Installieren Sie das WebView2 SDK.Install the WebView2 SDK.

    1. Geben Sie in der Suchleiste Microsoft.Web.WebView2 > Wählen Sie Microsoft.Web.WebView2 aus.In the search bar, type Microsoft.Web.WebView2 > choose Microsoft.Web.WebView2.

    2. Wählen Sie im rechten Fenster Installieren aus.In the right-hand side window, choose Install. NuGet lädt das SDK auf Ihren Computer herunter.NuGet downloads the SDK to your machine.

      NuGet Paket-Manager

  4. Fügen Sie Ihrem Projekt WebView2-Header hinzu.Add WebView2 header to your project.

    Kopieren Sie HelloWebView.cpp in der Datei den folgenden Codeausschnitt, und fügen Sie ihn nach der letzten Zeile #include ein.In the HelloWebView.cpp file, copy the following code snippet and paste it after the last #include line.

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

    Der Include-Abschnitt sollte dem folgenden Codeausschnitt ähnlich aussehen.The include section should look similar to the following code snippet.

    ...
    #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.Ready to use and build against the WebView2 API.

Erstellen Einer leeren Beispiel-AppBuild your empty sample app

Wählen Sie aus, um die Beispiel-App zu erstellen und F5 ausführen.To build and run the sample app, select F5. Ihre App zeigt ein leeres Fenster an.Your app displays an empty window.

Leere App

Schritt 3: Erstellen einer einzelnen WebView im übergeordneten FensterStep 3 - Create a single WebView within the parent window

Fügen Sie dem Hauptfenster eine WebView hinzu.Add a WebView to the main window.

Verwenden Sie die -Methode, um die Umgebung zu einrichten und CreateCoreWebView2Environment den Microsoft Edge (Chromium)-Browser zu finden, der das Steuerelement unterstützt.Use the CreateCoreWebView2Environment method to set up the environment and locate the Microsoft Edge (Chromium) browser powering the control. Sie können die Methode auch verwenden, wenn Sie browser location, user folder, browser flags und so weiter angeben möchten, anstatt die CreateCoreWebView2EnvironmentWithOptions Standardeinstellung zu verwenden.You may also use the CreateCoreWebView2EnvironmentWithOptions method if you want to specify browser location, user folder, browser flags, and so on, instead of using the default setting. Führen Sie nach Abschluss der Methode die Methode im Rückruf aus, und führen Sie die CreateCoreWebView2Environment -Methode aus, ICoreWebView2Environment::CreateCoreWebView2Controller um die ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler ICoreWebView2Controller::get_CoreWebView2 zugeordnete WebView zu erhalten.Upon the completion of the CreateCoreWebView2Environment method, run the ICoreWebView2Environment::CreateCoreWebView2Controller method inside the ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler callback and run the ICoreWebView2Controller::get_CoreWebView2 method to get the associated WebView.

Legen Sie im Rückruf einige weitere Einstellungen ein, ändern Sie die Größe der WebView auf 100 % des übergeordneten Fensters, und navigieren Sie zu Bing.In the callback, set a few more settings, resize the WebView to take 100% of the parent window, and navigate to 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.Copy the following code snippet and paste into HelloWebView.cpp after the // <-- WebView2 sample code starts here --> comment and before the // <-- WebView2 sample code ends here --> comment.

// 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-AppBuild your Bing sample app

Wählen Sie zum Erstellen und Ausführen der App F5 aus.To build and run the app, select F5. Jetzt haben Sie ein WebView-Fenster, in dem die Bing-Seite angezeigt wird.Now you have a WebView window displaying the Bing page.

Bing-Fenster

Schritt 4 – NavigationsereignisseStep 4 - Navigation events

Das WebView-Team hat bereits im letzten Schritt die Navigation zu URL mithilfe der ICoreWebView2::Navigate -Methode behandelt.The WebView team already covered navigating to URL using the ICoreWebView2::Navigate method in the last step. Während der Navigation gibt WebView eine Abfolge von Ereignissen aus, auf die der Host lauschen kann.During navigation, WebView fires a sequence of events to which the host may listen.

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

Weitere Informationen finden Sie unter Navigationsereignisse.For more information, navigate to Navigation events.

Navigationsereignisse

In Fehlerfällen kann eines oder mehrere der folgenden Ereignisse auftreten, je nachdem, ob die Navigation zu einer Fehlerwebseite fortgesetzt wird.In error cases, one or more of the following events may occur depending on whether the navigation is continued to an error webpage.

  • SourceChanged
  • ContentLoading
  • HistoryChanged

Hinweis

Wenn eine HTTP-Umleitung auftritt, gibt es mehrere NavigationStarting Ereignisse in einer Zeile.If an HTTP redirect occurs, there are multiple NavigationStarting events in a row.

Registrieren Sie als Beispiel für die Verwendung der Ereignisse einen Handler für das Ereignis, NavigationStarting um alle Nicht-https-Anforderungen abbricht.As an example of using the events, register a handler for the NavigationStarting event to cancel any non-https requests. Kopieren Sie den folgenden Codeausschnitt, und fügen Sie ihn in HelloWebView.cpp ein.Copy the following code snippet and paste into 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 zu nicht https-Websites.Now the app does not navigate to any non-https sites. Sie können einen ähnlichen Mechanismus verwenden, um andere Aufgaben auszuführen, z. B. die Beschränkung der Navigation auf innerhalb Ihrer eigenen Domäne.You may use similar mechanism to accomplish other tasks, such as restricting navigation to within your own domain.

Schritt 5 – SkripterstellungStep 5 - Scripting

Sie können Host-Apps verwenden, um Zur Laufzeit JavaScript-Code in WebView2-Steuerelemente zu injizieren.You may use host apps to inject JavaScript code into WebView2 controls at runtime. Sie können WebView zum Ausführen beliebiger JavaScript- oder Initialisierungsskripts aufgaben.You may task WebView to run arbitrary JavaScript or add initialization scripts. Das injizierte JavaScript gilt für alle neuen Dokumente der obersten Ebene und alle untergeordneten Frames, bis das JavaScript entfernt wird.The injected JavaScript applies to all new top-level documents and any child frames until the JavaScript is removed. Das injizierte JavaScript wird mit einem bestimmten Timing ausgeführt.The injected JavaScript is run with specific timing.

  • Führen Sie es nach der Erstellung des globalen Objekts aus.Run it after the creation of the global object.
  • Führen Sie es aus, bevor ein anderes Skript ausgeführt wird, das im HTML-Dokument enthalten ist.Run it before any other script included in the HTML document is run.

Kopieren Sie den folgenden Codeausschnitt, und fügen Sie ihn in HelloWebView.cpp ein.Copy the following code snippet and paste into 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ückgibt.Now, WebView should always freeze the Object object and returns the page document once.

Hinweis

Die Skriptinjektions-APIs (und einige andere WebView2-APIs) sind asynchron. Sie sollten Rückrufe verwenden, wenn Code in einer bestimmten Reihenfolge ausgeführt werden muss.The script injection APIs (and some other WebView2 APIs) are asynchronous, you should use callbacks if code is must be run in a specific order.

Schritt 6 – Kommunikation zwischen Host- und WebinhaltenStep 6 - Communication between host and web content

Der Host und der Webinhalt können auch über die Methode miteinander postMessage kommunizieren.The host and the web content may also communicate with each other through the postMessage method. Der in einer WebView ausgeführte Webinhalt kann über die -Methode an den Host gesendet werden, und die Nachricht wird von allen registrierten Ereignishandlern auf window.chrome.webview.postMessage ICoreWebView2WebMessageReceivedEventHandler dem Host verarbeitet.The web content running within a WebView may post to the host through the window.chrome.webview.postMessage method, and the message is handled by any registered the ICoreWebView2WebMessageReceivedEventHandler event handler on the host. Ebenso kann der Host den Webinhalt über oder die -Methode senden, die von Handlern erfasst wird, die vom ICoreWebView2::PostWebMessageAsString ICoreWebView2::PostWebMessageAsJSON Listener hinzugefügt window.chrome.webview.addEventListener wurden.Likewise, the host may message the web content through ICoreWebView2::PostWebMessageAsString or ICoreWebView2::PostWebMessageAsJSON method, which is caught by handlers added from window.chrome.webview.addEventListener listener. Der Kommunikationsmechanismus ermöglicht es dem Webinhalt, systemeigene Funktionen zu verwenden, indem Nachrichten übergeben werden, um den Host zum Ausführen systemeigener APIs zu bitten.The communication mechanism allows the web content to use native capabilities by passing messages to ask the host to run native APIs.

Um den Mechanismus zu verstehen, führen Sie die folgenden Schritte aus, wenn Sie versuchen, die Dokument-URL in WebView auszuprobieren.As an example to understand the mechanism, the following steps occur when you try to output the document URL in WebView.

  1. Der Host registriert einen Handler, um empfangene Nachrichten an den Webinhalt zurückzukehrenThe host registers a handler to return received message back to the web content
  2. Der Host injiziert ein Skript in den Webinhalt, der einen Handler zum Drucken von Nachrichten vom Host registriertThe host injects a script to the web content that registers a handler to print message from the host
  3. Der Host injiziert ein Skript in den Webinhalt, der die URL auf dem Host veröffentlichtThe host injects a script to the web content that posts the URL to the host
  4. Der Handler des Hosts wird ausgelöst und gibt die Nachricht (die URL) an den Webinhalt zurück.The handler of the host is triggered and returns the message (the URL) to the web content
  5. Der Handler des Webinhalts wird ausgelöst und druckt die Nachricht vom Host (die URL)The handler of the web content is triggered and prints message from the host (the URL)

Kopieren Sie den folgenden Codeausschnitt, und fügen Sie ihn in HelloWebView.cpp ein.Copy the following code snippet and paste into 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-URLBuild your display URL sample app

Wählen Sie zum Erstellen und Ausführen der App F5 aus.To build and run the app, select F5. Die URL wird in einem Popupfenster angezeigt, bevor sie zu einer Webseite navigiert.The URL appears in a pop-up window before navigating to a webpage.

Anzeige-URL

Herzlichen Glückwunsch, Sie haben Ihre erste WebView2-App erstellt.Congratulations, you built your first WebView2 app.

Nächste SchritteNext steps

Viele der WebView2-Funktionen werden in diesem Artikel nicht behandelt, der folgende Abschnitt enthält weitere Ressourcen.Many of the WebView2 functionalities are not covered on this article, the following section provides more resources.

Weitere InformationenSee also

  • Ein umfassendes Beispiel für WebView2-Funktionen finden Sie unter WebView2-API-Beispiel.For a comprehensive example of WebView2 capabilities, navigate to WebView2 API Sample.
  • Navigieren Sie zu WebView2Browser,um eine mit WebView2 erstellte Beispiel-App zu navigieren.For a sample app built using WebView2, navigate to WebView2Browser.
  • Ausführliche Informationen zur WebView2-API finden Sie unter API-Referenz.For detailed information about the WebView2 API, navigate to API reference.

Kontakt mit dem Microsoft Edge WebView-TeamGetting in touch with the Microsoft Edge WebView team

Teilen Sie Ihr Feedback mit, um eine reichhaltigere WebView2-Erfahrung zu erstellen.Share your feedback to help build richer WebView2 experiences. Navigieren Sie zum Microsoft Edge WebView-Feedback-Repository, um Featureanforderungen oder Fehler zu übermitteln oder nach bekannten Problemen zu suchen.To submit feature requests or bugs, or search for known issues, navigate to the Microsoft Edge WebView feedback repo.