interface ICoreWebView2ExperimentalFrame2
Note
This reference is no longer being maintained. For the latest API reference, see WebView2 API Reference.
Note
This an experimental API that is shipped with our prerelease SDK. See WebView2 release notes.
interface ICoreWebView2ExperimentalFrame2
: public IUnknown
This is the ICoreWebView2Frame2 Experimental interface.
Summary
Members | Descriptions |
---|---|
add_WebMessageReceived | Add an event handler for the WebMessageReceived event. |
PostWebMessageAsJson | Posts the specified webMessage to the frame. |
PostWebMessageAsString | Posts a message that is a simple string rather than a JSON string representation of a JavaScript object. |
remove_WebMessageReceived | Remove an event handler previously added with add_WebMessageReceived . |
Applies to
Product | Introduced |
---|---|
WebView2 Win32 | N/A |
WebView2 Win32 Prerelease | 1.0.1083 |
Members
add_WebMessageReceived
Add an event handler for the WebMessageReceived
event.
public HRESULT add_WebMessageReceived(ICoreWebView2ExperimentalFrameWebMessageReceivedEventHandler * 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(frameExperimental->add_WebMessageReceived(
Microsoft::WRL::Callback<
ICoreWebView2ExperimentalFrameWebMessageReceivedEventHandler>(
[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<ICoreWebView2ExperimentalFrame2> frameExperimental;
if (sender->QueryInterface(IID_PPV_ARGS(&frameExperimental)) ==
S_OK)
{
CHECK_FAILURE(
frameExperimental->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));
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 this method fails with E_INVALIDARG
. 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_WebMessageReceived
Remove an event handler previously added with add_WebMessageReceived
.
public HRESULT remove_WebMessageReceived(EventRegistrationToken token)