|
| 1 | +# Background |
| 2 | + |
| 3 | +In response to consumers' requests for an event similar to the old [WebView DOMContentLoaded](https://docs.microsoft.com/en-us/microsoft-edge/hosting/webview#mswebviewdomcontentloaded), the WebView2 team has introduced DOMContentLoaded API which indicates that the main DOM elements have finished loading. |
| 4 | +In this document we describe the new API. We'd appreciate your feedback. |
| 5 | + |
| 6 | +# Description |
| 7 | +We propose adding DOMContentLoaded to CoreWebView2. This allows the developer to have an event that fires when the DOM is loaded after the WebView2 navigates to a page. |
| 8 | + |
| 9 | +# Examples |
| 10 | +## Win32 C++ |
| 11 | +``` |
| 12 | +ScenarioDOMContentLoaded::ScenarioDOMContentLoaded(AppWindow* appWindow) |
| 13 | + : m_appWindow(appWindow), m_webView(appWindow->GetWebView()) |
| 14 | +{ |
| 15 | + //! [DOMContentLoaded] |
| 16 | + // Register a handler for the DOMContentLoaded event. |
| 17 | + // Check whether the DOM content loaded |
| 18 | + CHECK_FAILURE(m_webView->add_DOMContentLoaded( |
| 19 | + Callback<ICoreWebView2DOMContentLoadedEventHandler>( |
| 20 | + [this](ICoreWebView2* sender, ICoreWebView2DOMContentLoadedEventArgs* args) |
| 21 | + -> HRESULT { |
| 22 | + m_webView->ExecuteScript( |
| 23 | + L"let " |
| 24 | + L"content=document.createElement(\"h2\");content.style.color='blue';" |
| 25 | + L"content.textContent=\"This text was added by the host " |
| 26 | + L"app\";document.body.appendChild(content);", |
| 27 | + Callback<ICoreWebView2ExecuteScriptCompletedHandler>( |
| 28 | + [](HRESULT error, PCWSTR result) -> HRESULT { return S_OK; }) |
| 29 | + .Get()); |
| 30 | + return S_OK; |
| 31 | + }) |
| 32 | + .Get(), |
| 33 | + &m_DOMContentLoadedToken)); |
| 34 | + //! [DOMContentLoaded] |
| 35 | +``` |
| 36 | + |
| 37 | +## C# |
| 38 | +``` |
| 39 | +webView.CoreWebView2.DOMContentLoaded += (object sender, CoreWebView2DOMContentLoadedEventArgs arg) => |
| 40 | +{ |
| 41 | + webView.ExecuteScriptAsync("let " |
| 42 | + "content=document.createElement(\"h2\");content.style.color=" |
| 43 | + "'blue';content.textContent= \"This text was added by the " |
| 44 | + "host app\";document.body.appendChild(content);"); |
| 45 | +}; |
| 46 | +webView.NavigateToString(@"<!DOCTYPE html><h1>DOMContentLoaded sample page</h1><h2>The content below will be added after DOM content is loaded </h2>"); |
| 47 | +
|
| 48 | +``` |
| 49 | + |
| 50 | +# API Notes |
| 51 | + |
| 52 | +See [API Details](#api-details) section below for API reference. |
| 53 | +# API Details |
| 54 | + |
| 55 | +## Win32 C++ |
| 56 | + |
| 57 | +```IDL |
| 58 | +interface ICoreWebView2_2; |
| 59 | +interface ICoreWebView2DOMContentLoadedEventArgs; |
| 60 | +interface ICoreWebView2DOMContentLoadedEventHandler; |
| 61 | +
|
| 62 | +[uuid(9810c82b-8483-4f1c-b2f4-6244f1010c05), object, pointer_default(unique)] |
| 63 | +interface ICoreWebView2_2 : ICoreWebView2 { |
| 64 | + /// Add an event handler for the DOMContentLoaded event. |
| 65 | + /// DOMContentLoaded fires when the initial html document has been parsed. |
| 66 | + /// This aligns with the the document's DOMContentLoaded event in html |
| 67 | + /// |
| 68 | + /// \snippet ScenarioDOMContentLoaded-Staging.cpp |
| 69 | + HRESULT add_DOMContentLoaded( |
| 70 | + [in] ICoreWebView2StagingDOMContentLoadedEventHandler* eventHandler, |
| 71 | + [out] EventRegistrationToken* token); |
| 72 | + /// Remove an event handler previously added with add_DOMContentLoaded. |
| 73 | + HRESULT remove_DOMContentLoaded( |
| 74 | + [in] EventRegistrationToken token); |
| 75 | +} |
| 76 | +
|
| 77 | +/// Event args for the DOMContentLoaded event. |
| 78 | +[uuid(E8BA4206-D6F8-42F1-9A6D-43C8A99C1F39), object, pointer_default(unique)] |
| 79 | +interface ICoreWebView2DOMContentLoadedEventArgs : IUnknown { |
| 80 | + /// The ID of the navigation. |
| 81 | + [propget] HRESULT NavigationId([out, retval] UINT64* navigation_id); |
| 82 | +} |
| 83 | +
|
| 84 | +/// The caller implements this interface to receive the DOMContentLoaded |
| 85 | +/// event. |
| 86 | +[uuid(1E649181-785D-40B2-B4AE-AFACD3C6B8DD), object, pointer_default(unique)] |
| 87 | +interface ICoreWebView2DOMContentLoadedEventHandler : IUnknown { |
| 88 | + /// Called to provide the implementer with the event args for the |
| 89 | + /// corresponding event. |
| 90 | + HRESULT Invoke( |
| 91 | + [in] ICoreWebView2* sender, |
| 92 | + [in] ICoreWebView2DOMContentLoadedEventArgs* args); |
| 93 | +} |
| 94 | +``` |
| 95 | + |
| 96 | +## .NET and WinRT |
| 97 | + |
| 98 | +```c# |
| 99 | +namespace Microsoft.Web.WebView2.Core |
| 100 | +{ |
| 101 | + runtimeclass CoreWebView2DOMContentLoadedEventArgs; |
| 102 | + |
| 103 | + runtimeclass CoreWebView2DOMContentLoadedEventArgs |
| 104 | + { |
| 105 | + // CoreWebView2DOMContentLoadedEventArgs |
| 106 | + UInt64 NavigationId { get; }; |
| 107 | + } |
| 108 | + |
| 109 | + runtimeclass CoreWebView2 |
| 110 | + { |
| 111 | + // CoreWebView2 |
| 112 | + event Windows.Foundation.TypedEventHandler<CoreWebView2, CoreWebView2DOMContentLoadedEventArgs> DOMContentLoaded; |
| 113 | + } |
| 114 | + |
| 115 | + |
| 116 | +} |
| 117 | +``` |
0 commit comments