Interoperabilität von nativem und webseitigem Code

Artikel
04/04/2023

Mit dem Microsoft Edge WebView2-Steuerelement können Sie Webinhalte in native Anwendungen einbetten. Sie können WebView2 auf unterschiedliche Weise verwenden, je nachdem, was Sie erreichen müssen. In diesem Artikel wird beschrieben, wie Sie mithilfe einfacher Nachrichten, JavaScript-Code und nativer Objekte kommunizieren.

Zu den gängigen Anwendungsfällen gehören:

Aktualisieren Sie den Titel des nativen Hostfensters, nachdem Sie zu einer anderen Website navigiert haben.
Senden Sie ein natives Kameraobjekt, und verwenden Sie dessen Methoden aus einer Web-App.
Führen Sie eine dedizierte JavaScript-Datei auf der Webseite einer Anwendung aus.

Bevor Sie beginnen

In diesem Tutorial wird der Code der Beispiel-App erläutert, um einige der Kommunikationsfunktionen in WebView2 zu veranschaulichen. Klonen Sie das WebView2Samples-Repository, öffnen Sie eine .sln Datei in Visual Studio, erstellen Sie das Projekt, und führen Sie (debuggen) aus, um die Schritte in diesem Artikel auszuführen.

Ausführliche Schritte zum Klonen des Repositorys finden Sie unter WebView2-Beispiele.

Szenario: Einfaches Messaging

Mit WebView2-Steuerelementen können Sie einfache Nachrichten zwischen Web- und nativen Seiten einer Anwendung austauschen. Sie können Datentypen wie JSON oder String verwenden, um Nachrichten zwischen der Hostanwendung und WebView2 zu senden.

Senden von Nachrichten von der Host-App an WebView2

Dieses Beispiel zeigt, wie die Beispiel-App die Textfarbe im Front-End basierend auf einer Nachricht der Host-App ändert.

So sehen Sie Messaging in Aktion:

Führen Sie die Beispiel-App aus, wählen Sie dann die Registerkarte Szenario und dann die Option Webmessaging aus.

Der folgende Bildschirm wird angezeigt:
Beachten Sie den ersten Abschnitt mit dem Titel Posting Messages. Befolgen Sie die Anweisungen, und wählen Sie Skript>post message JSON aus. Klicken Sie anschließend auf OK. Die Meldung wird blau:

Wie konnten wir die Textfarbe ändern? Das Beispiel beginnt mit dem Erstellen einer Schaltfläche auf der nativen Seite. Anschließend fügt das Beispiel den folgenden Code hinzu, um die Webnachricht zu posten, wenn auf die Schaltfläche geklickt wird. Dieser Code ändert die Farbe des Webtexts in Blau.

Das Beispiel enthält C++-Code zum Erstellen einer Windows-Schaltfläche, die beim Klicken aufruft SendJsonWebMessage() .

Weitere Informationen zum Erstellen einer Schaltfläche in C++ finden Sie unter Erstellen einer Schaltfläche.

Wenn auf die Schaltfläche geklickt wird, wird der folgende Code aus ScriptComponent.cpp aufgerufen.

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

Hinweis

Im restlichen Teil dieses Tutorials wird die Datei ScenarioWebMessage.html aus dem WebView2-Beispiel verwendet. Vergleichen Sie Ihre eigene HTML-Datei, während Sie arbeiten, oder kopieren Sie den Inhalt aus ScenarioWebMessage.html.

Im Beispiel wird ein JavaScript-Ereignislistener im Web verwendet.

ScenarioWebMessage.html enthält den folgenden JavaScript-Code im Header:

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

Der Ereignislistener lauscht auf ein Nachrichtenereignis und macht den Nachrichtentext farblich.

Die HTML-Datei beschreibt die Messaging-Übung:

<h1>WebMessage sample page</h1>
<p>This page demonstrates basic interaction between the host app 
and the webview by means of Web Messages.</p>

<h2>Posting Messages</h2>
<p id="colorable">Messages can be posted from the host app to the 
webview using the functions
<code>ICoreWebView2::PostWebMessageAsJson</code> and
<code>ICoreWebView2::PostWebMessageAsString</code>. Try selecting 
the menu item "Script > Post Message JSON" to send the message 
<code>{"SetColor":"blue"}</code>.
It should change the text color of this paragraph.</p>

Das Post Message JSON Menüelement befindet sich in der Microsoft Visual C++ generierten Ressourcenskriptdatei WebView2APISample.rc.
```
MENUITEM "Post Message JSON",           IDM_POST_WEB_MESSAGE_JSON
```
Die Skriptdatei wiederum ruft den Fall IDM_POST_WEB_MESSAGE_JSON in ScriptComponent.cpp auf.
```
case IDM_POST_WEB_MESSAGE_JSON:
   SendJsonWebMessage();
   return true;
```

Damit wird das Beispiel abgeschlossen, das zeigt, wie WebView2 über einfache Nachrichten kommuniziert.

Empfangen von Nachrichtenzeichenfolgen über postMessage

Dieses Beispiel folgt dem Receiving Messages Abschnitt der Webseite, um den Text der Titelleiste zu ändern. Die Host-App empfängt eine Nachricht von WebView2 mit dem neuen Titelleistentext.

Die C++-Datei verarbeitet den Titeltext und kommuniziert ihn als Zeichenfolge an die Host-App.

Wenn auf die Schaltfläche geklickt wird, überträgt WebView2 mithilfe von window.chrome.webview.postMessage in ScenarioWebMessage.htmleine Nachricht von der Webseite an die native Anwendung.
```
function SetTitleText() {
   let titleText = document.getElementById("title-text");
   window.chrome.webview.postMessage(`SetTitleText ${titleText.value}`);
}
```

Die HTML-Datei enthält ein Textfeld und eine Schaltfläche zum Senden einer Nachricht an die Host-App:

<h2>Receiving Messages</h2>
<p>The host app can receive messages by registering an event handler 
with <code>ICoreWebView2::add_WebMessageReceived</code>. If you 
enter text and click "Send", this page will send a message to the 
host app which will change the text of the title bar.</p>
<input type="text" id="title-text"/>
<button onclick="SetTitleText()">Send</button>

Der Ereignishandler in ScenarioWebMessage.cpp verarbeitet die neue Titeltextzeichenfolge und kommuniziert sie als Zeichenfolge an die Host-App.

// 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());
   }
   else 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()));
   }
   return S_OK;
}).Get(), &m_webMessageReceivedToken));

Roundtripnachrichten

Dieses Beispiel folgt dem <h2>Round trip</h2> Abschnitt der WebMessage-Beispielseite ScenarioWebMessage.html. Dieses Beispiel zeigt eine Roundtripnachricht von WebView2 zur Host-App und zurück. Die Host-App empfängt eine Anforderung von WebView2 und gibt die Begrenzungen des aktiven Fensters zurück.

Wenn sie von der Host-App angefordert wird, ruft die C++-Datei die Fenstergrenzen ab und sendet die Daten als JSON-Webnachricht an WebView2.

Die HTML-Datei enthält eine Schaltfläche zum Abrufen von Fenstergrenzen von der Host-App:

<h2>Round trip</h2>
<p>The host app can send messages back in response to received 
messages. If you click the <b>Get window bounds</b> button, the 
host app reports back the bounds of its window, which are 
displayed in the text box.</p>
<button onclick="GetWindowBounds()">Get window bounds</button><br>
<textarea id="window-bounds" rows="4" readonly></textarea>

Wenn der Benutzer auf die Schaltfläche klickt, überträgt WebView2 mithilfe window.chrome.webview.postMessagevon eine Nachricht von der Webseite an die native Anwendung.
```
function GetWindowBounds() {
   window.chrome.webview.postMessage("GetWindowBounds");
}
```

Der Ereignishandler in ScenarioWebMessage.cpp ruft die Fenstergrenzen ab und sendet die Daten mithilfe von TryGetWebMessageAsStringan die Host-App:

// 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());
   }
   else 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()));
   }
   return S_OK;
}).Get(), &m_webMessageReceivedToken));

Die Fenstergrenzen werden auf der Webseite angezeigt.

Szenario: Senden von JavaScript-Code

In diesem Szenario wird gezeigt, wie JavaScript auf der Webseite ausgeführt wird. Bei diesem Ansatz gibt die Host-App den auszuführenden JavaScript-Code an und übergibt den Code an ExecuteScriptAsyncdas Web. Die ExecuteScriptAsync Funktion gibt das JavaScript-Ergebnis an den ExecuteScript Aufrufer zurück.

Weitere Informationen finden Sie unter Verwenden von JavaScript in WebView2 (Ausführen von JavaScript aus nativem Code).

Szenario: Senden nativer Objekte

Übergeben Sie das native Objekt an das Web. Rufen Sie dann die Methoden des Objekts aus dem Web auf.

Verwenden Sie die API, um Nachrichten zu verwenden, die AddHostObjectToScript Methodenaufrufe darstellen. Auf hoher Ebene können Sie mit dieser API native (Host-)Objekte auf der Webseite verfügbar machen und als Proxy fungieren. Greifen Sie mithilfe window.chrome.webview.hostObjects.{name}von auf diese Objekte zu.

Das Übergeben eines nativen Objekts an die Webseite einer Anwendung wird im Abschnitt AddHostObjectToScript der Schnittstelle ICoreWebView2 beschrieben.

Herzlichen Glückwunsch! Sie haben Webinhalte erfolgreich in native Anwendungen eingebettet.

Siehe auch

Web-/native Interop in Übersicht über WebView2-Features und -APIs.

Freigeben über