interface ICoreWebView2Frame2

interface ICoreWebView2Frame2
  : public ICoreWebView2Frame

A continuation of the ICoreWebView2Frame interface with navigation events, executing script and posting web messages.

Summary

Applies to

Members

add_ContentLoading

Add an event handler for the ContentLoading event.

public HRESULT add_ContentLoading(ICoreWebView2FrameContentLoadingEventHandler * eventHandler, EventRegistrationToken * token)

ContentLoading triggers before any content is loaded, including scripts added with AddScriptToExecuteOnDocumentCreated. ContentLoading does not trigger if a same page navigation occurs (such as through fragment navigations or history.pushState navigations). This operation follows the NavigationStarting and precedes NavigationCompleted events.

add_DOMContentLoaded

Add an event handler for the DOMContentLoaded event.

public HRESULT add_DOMContentLoaded(ICoreWebView2FrameDOMContentLoadedEventHandler * eventHandler, EventRegistrationToken * token)

DOMContentLoaded is raised when the iframe html document has been parsed. This aligns with the document's DOMContentLoaded event in html.

add_NavigationCompleted

Add an event handler for the NavigationCompleted event.

public HRESULT add_NavigationCompleted(ICoreWebView2FrameNavigationCompletedEventHandler * eventHandler, EventRegistrationToken * token)

NavigationCompleted runs when the CoreWebView2Frame has completely loaded (concurrently when body.onload runs) or loading stopped with error.

add_NavigationStarting

Add an event handler for the NavigationStarting event.

public HRESULT add_NavigationStarting(ICoreWebView2FrameNavigationStartingEventHandler * eventHandler, EventRegistrationToken * token)

A frame navigation will raise a NavigationStarting event and a CoreWebView2.FrameNavigationStarting event. All of the FrameNavigationStarting event handlers for the current frame will be run before the NavigationStarting event handlers. All of the event handlers share a common NavigationStartingEventArgs object. Whichever event handler is last to change the NavigationStartingEventArgs.Cancel property will decide if the frame navigation will be cancelled. Redirects raise this event as well, and the navigation id is the same as the original one.

Navigations will be blocked until all NavigationStarting and CoreWebView2.FrameNavigationStarting event handlers return.

add_WebMessageReceived

Add an event handler for the WebMessageReceived event.

public HRESULT add_WebMessageReceived(ICoreWebView2FrameWebMessageReceivedEventHandler * handler, EventRegistrationToken * token)

WebMessageReceived runs when the ICoreWebView2Settings::IsWebMessageEnabled setting is set and the frame document runs window.chrome.webview.postMessage. The postMessage function is void postMessage(object) where object is any object supported by JSON conversion.

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

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

When the frame calls postMessage, the object parameter is converted to a JSON string and is posted asynchronously to the host process. This will result in the handlers Invoke method being called with the JSON string as its parameter.

            // Setup the web message received event handler before navigating to
            // ensure we don't miss any messages.
            CHECK_FAILURE(webviewFrame2->add_WebMessageReceived(
                Microsoft::WRL::Callback<ICoreWebView2FrameWebMessageReceivedEventHandler>(
                    [this](
                        ICoreWebView2Frame* 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)
                        {
                            // Ignore messages from untrusted sources.
                            return S_OK;
                        }
                        wil::unique_cotaskmem_string messageRaw;
                        HRESULT hr = args->TryGetWebMessageAsString(&messageRaw);
                        if (hr == E_INVALIDARG)
                        {
                            // Was not a string message. Ignore.
                            return S_OK;
                        }
                        // Any other problems are fatal.
                        CHECK_FAILURE(hr);
                        std::wstring message = messageRaw.get();

                        if (message.compare(0, 13, L"SetTitleText ") == 0)
                        {
                            m_appWindow->SetDocumentTitle(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"\"}";
                            wil::com_ptr<ICoreWebView2Frame2> webviewFrame2;
                            if (sender->QueryInterface(IID_PPV_ARGS(&webviewFrame2)) == S_OK)
                            {
                                CHECK_FAILURE(
                                    webviewFrame2->PostWebMessageAsJson(reply.c_str()));
                            }
                        }
                        else
                        {
                            // Ignore unrecognized messages, but log for further investigation
                            // since it suggests a mismatch between the web content and the host.
                            OutputDebugString(
                                std::wstring(L"Unexpected message from frame:" + message).c_str());
                        }
                        return S_OK;
                    })
                    .Get(),
                NULL));

ExecuteScript

Run JavaScript code from the javascript parameter in the current frame.

public HRESULT ExecuteScript(LPCWSTR javaScript, ICoreWebView2ExecuteScriptCompletedHandler * handler)

The result of evaluating the provided JavaScript is passed to the completion handler. The result value is a JSON encoded string. If the result is undefined, contains a reference cycle, or otherwise is not able to be encoded into JSON, then the result is considered to be null, which is encoded in JSON as the string "null".

    wil::com_ptr<ICoreWebView2_4> webview2_4 = m_webView.try_query<ICoreWebView2_4>();
    if (webview2_4)
    {
        CHECK_FAILURE(webview2_4->add_FrameCreated(
            Callback<ICoreWebView2FrameCreatedEventHandler>(
                [](ICoreWebView2* sender, ICoreWebView2FrameCreatedEventArgs* args) -> HRESULT {
                    wil::com_ptr<ICoreWebView2Frame> webviewFrame;
                    CHECK_FAILURE(args->get_Frame(&webviewFrame));
                    wil::com_ptr<ICoreWebView2Frame2> frame2 =
                        webviewFrame.try_query<ICoreWebView2Frame2>();
                    if (frame2)
                    {
                        frame2->add_DOMContentLoaded(
                            Callback<ICoreWebView2FrameDOMContentLoadedEventHandler>(
                                [](ICoreWebView2Frame* frame,
                                   ICoreWebView2DOMContentLoadedEventArgs* args) -> HRESULT {
                                    wil::com_ptr<ICoreWebView2Frame2> frame2;
                                    frame->QueryInterface(IID_PPV_ARGS(&frame2));
                                    frame2->ExecuteScript(
                                        LR"~(
                                        let content = document.createElement("h2");
                                        content.style.color = 'blue';
                                        content.textContent = "This text was added to the iframe by the host app";
                                        document.body.appendChild(content);
                                        )~",
                                        Callback<ICoreWebView2ExecuteScriptCompletedHandler>(
                                            [](HRESULT error, PCWSTR result) -> HRESULT {
                                                // Handle ExecuteScript error and result here if needed
                                                // or pass nullptr as callback parametr otherwise.
                                                return S_OK;
                                            })
                                            .Get());
                                    return S_OK;
                                })
                                .Get(),
                            NULL);
                    }
                    return S_OK;
                })
                .Get(),
            &m_frameCreatedToken));
    }

PostWebMessageAsJson

Posts the specified webMessage to the frame.

public HRESULT PostWebMessageAsJson(LPCWSTR webMessageAsJson)

The frame receives the message by subscribing to the message event of the window.chrome.webview of the frame document.

window.chrome.webview.addEventListener('message', handler)
window.chrome.webview.removeEventListener('message', handler)

The event args is an instances of MessageEvent. The ICoreWebView2Settings::IsWebMessageEnabled setting must be TRUE or the message will not be sent. The data property of the event args is the webMessage string parameter parsed as a JSON string into a JavaScript object. The source property of the event args is a reference to the window.chrome.webview object. For information about sending messages from the HTML document in the WebView to the host, navigate to add_WebMessageReceived. The message is delivered asynchronously. If a navigation occurs before the message is posted to the page, the message is discarded.

PostWebMessageAsString

Posts a message that is a simple string rather than a JSON string representation of a JavaScript object.

public HRESULT PostWebMessageAsString(LPCWSTR webMessageAsString)

This behaves in exactly the same manner as PostWebMessageAsJson, but the data property of the event args of the window.chrome.webview message is a string with the same value as webMessageAsString. Use this instead of PostWebMessageAsJson if you want to communicate using simple strings rather than JSON objects.

remove_ContentLoading

Remove an event handler previously added with add_ContentLoading.

public HRESULT remove_ContentLoading(EventRegistrationToken token)

remove_DOMContentLoaded

Remove an event handler previously added with add_DOMContentLoaded.

public HRESULT remove_DOMContentLoaded(EventRegistrationToken token)

remove_NavigationCompleted

Remove an event handler previously added with add_NavigationCompleted.

public HRESULT remove_NavigationCompleted(EventRegistrationToken token)

remove_NavigationStarting

Remove an event handler previously added with add_NavigationStarting.

public HRESULT remove_NavigationStarting(EventRegistrationToken token)

remove_WebMessageReceived

Remove an event handler previously added with add_WebMessageReceived.

public HRESULT remove_WebMessageReceived(EventRegistrationToken token)