共用方式為

在 WebView2 應用程式中使用框架

  • 發行項

框架可讓您將其他網頁內嵌到您自己的網頁。 框架是網頁內的子頁面或區域，例如網頁內的網頁。

iframe 是一種框架類型。 其他類型的框架為 frameset、 portal、 embed、 fencedFrame和 object。 框架的主要 WebView2 類型是 CoreWebView2Frame，目前已針對最上層 iframe 啟用。 計劃支援其他類型的框架。

WebView2 支援 API 與 iframe 互動。 您可以：

  • 瞭解建立 iframe 的時間。
  • 瞭解 iframe 何時巡覽至不同的 URL。 其運作方式與 WebView2 應用程式的狀態機器導覽事件相同。
  • 在主應用程式與 iframe 之間通訊，雙向傳送訊息。
  • 允許應用程式忽略 X-Frame-Options HTTP 回應標頭。

另請參閱:

訂閱 FrameCreated 事件以取得框架

若要與主應用程式中的畫面互動，第一個步驟是訂閱 FrameCreated 事件，讓您的主應用程式取得框架物件。 FrameCreated每當建立新的框架時，就會引發 事件。 在您的主應用程式取得框架對象之後，請使用框架物件來監視變更，並與這個特定的框架互動。

您的主應用程式必須藉由訂閱事件來 CoreWebView2Frame.Destroyed 監視框架的存留期，因為當框架終結時，您的主應用程式就無法再參考該畫面。 在每個新的網頁導覽期間，畫面都會建立並終結。 CoreWebView2Frame.IsDestroyed使用方法來檢查框架是否仍然存在。

另請參閱:

  • WebView2 功能和 API 概觀中的iframe。

建立框架之後，框架會巡覽至框架的來源URL。 iframe 會使用瀏覽和瀏覽事件，例如 FrameNavigationStarting 和 NavigationCompleted。 當畫面巡覽至來源 URL 時，會引發下列導覽事件：

  • NavigationStarting
  • ContentLoading
  • HistoryChanged
  • DOMContentLoaded
  • NavigationCompleted

在框架內巡覽的頻率

導覽可能會在框架內發生。 簡單使用案例是， iframe 元素的 source 屬性是URL，例如 wikipedia.com，而URL會載入iframe中。 通常會在建立框架之後立即進行導覽。 接著 ContentLoading會引發、 DOMContentLoaded和 NavigationCompleted 事件。

框架本身正在巡覽。 網頁會流覽至 URL。 同樣地，框架也可能會巡覽。

建立框架之後，畫面會以主應用程式驅動方式流覽。 若要監視主頁面中發生的情況，、和 HistoryChanged 等NavigationStartingNavigationCompleted事件可讓主應用程式在畫面或網頁之間來回流覽。 畫面格流覽至新 URL 的頻率低於網頁，但支援相同的瀏覽樣式。 使用者通常無法在框架內瀏覽，雖然 JavaScript 會啟用該功能;框架通常是關於導覽的靜態。

另請參閱:

導覽事件：

關於重複的對等 NavigationStarting 和 NavigationCompleted 事件，建議在 上 CoreWebView2Frame 的事件，而不是上對等的取代事件 CoreWebView2，因為 CoreWebView2Frame 類型支援更多案例，以允許與畫面互動。

另請參閱:

在 iframe 中使用主機物件

若要在主應用程式的原生端與 iframe 中的 JavaScript 之間進行通訊，請使用主機物件。 主機物件是您在主應用程式中建立的物件，然後從應用程式網頁端的 JavaScript 程式代碼使用。

透過主機物件，從框架內的腳本使用原生端 API，類似於 Web/原生 Interop 頁面結構，如 從 Web 端程式代碼呼叫原生端程式代碼中所述：

若要在 iframe 內使用主機物件：

  1. 定義主物件並實作 IDispatch。
  2. 使用 AddHostObjectToScriptWithOrigins (Win32) 或 AddHostObjectToScript (.NET) ，在原生端新增主機物件。
  3. 從 Web 端程式代碼中的 JavaScript，使用 chrome.webview.hostObjects.<name> API 存取此主機物件。

若要從框架中的 Web 端 JavaScript 存取及控制原生端物件，請使用 AddHostObjectToScriptWithOrigins (Win32) 或 CoreWebView2Frame.AddHostObjectToScript (.NET) ，其具有 origins 參數。 參數 origins 會指定基於安全性理由，允許哪些 URL iframe 存取。 此參數會識別 iframe 可存取主機物件的 URL。

如果框架巡覽至不在清單中的 origins URL，則框架將無法操作主機物件;框架將無法讀取或寫入任何屬性。 請參閱架構之 方法中AddHostObjectToScript的方法名稱數據表。 請參閱下列兩個資料列：

  • applyHostFunction、 getHostProperty和 setHostProperty。
  • getLocalProperty 和 setLocalProperty。

上述方法的運作方式如下列方法所示：

範例程序代碼

請參閱從網頁端程式代碼呼叫原生程序代碼中的步驟 6：呼叫 AddHostObjectToScript 將主機對象傳遞至網頁端程序代碼。

另請參閱:

傳送和接收訊息

您可以在 iframe 中的原生應用程式和 JavaScript 程式代碼之間傳送訊息：

  • 您可以在 HTML 頁面的 iframe 中，從 JavaScript 將訊息傳送至主應用程式。
  • 您可以在 HTML 頁面的 iframe 中，將訊息從主應用程式傳送至 JavaScript。

將 Web 訊息從 iframe 傳送至主應用程式

若要將 Web 訊息從 iframe 傳送至主應用程式，請使用 方法 window.chrome.webview.postMessage ：

window.chrome.webview.postMessage(`SetTitleText ${titleText.value}`);

若要在主應用程式中接收這些訊息，主應用程式必須訂閱 WebMessageReceived event。

將訊息從主應用程式傳送至 iframe

主應用程式會呼叫 PostWebMessageAsJson 或 PostWebMessageAsString 方法，將訊息傳送至 iframe。

iframe 會藉由訂閱 window.chrome.webview.addEventListener('message') 事件來接收訊息，如下所示：

window.chrome.webview.addEventListener('message', arg => {
    // implement event listener here
});

另請參閱:

使用 ExecuteScript 在 iframe 中執行 JavaScript 程式代碼

WebView2 應用程式可以使用 ExecuteScript，在框架中執行任何 JavaScript。

若要讓腳本在 iframe 中執行，必須建立執行內容。 執行內容會在 ContentLoading 事件之後建立，這就是為什麼在 ExecuteScript 引發事件之前 ContentLoading 呼叫 時，將不會執行腳本，而且會傳回字串 null 。

如需事件的 ContentLoading 相關信息，請參閱 WebView2 應用程式的導覽事件，其適用於畫面和網頁。

另請參閱:

在 iframe 中使用 WebResourceRequested 事件修改網路事件

這項功能是實驗性的

針對 iframe，您可以使用 WebResourceRequested 事件來接聽網路事件並加以修改。

另請參閱:

請參閱最新的發行前版本 API。 下列連結包含 1.0.1466-prerelease。 在 API 參考檔左上方的 [ 版本 ] 下拉式清單中，選取最新的發行前版本。

忽略 X-Frame-Options 以轉譯框架內的網頁

X-Frame-Options網頁會使用 HTTP 回應標頭來防止應用程式在框架內轉譯該網頁。 屬性 AdditionalAllowedFrameAncestors 可讓您的應用程式略過 X-Frame-Options 標頭，以轉譯框架內的網頁。

另請參閱:

在主應用程式中使用 iframe 的範例

此範例程式代碼示範如何使用框架 API，包括：

  • FrameCreated
    • CoreWebView2FrameCreatedEventArgs
  • DOMContentLoaded
    • CoreWebView2DOMContentLoadedEventArgs
  • ExecuteScript

此範例程式代碼是從 WebView2WpfBrowser 範例中的MainWindow.xaml.cs壓縮而來。

        void DOMContentLoadedCmdExecuted(object target, ExecutedRoutedEventArgs e)
        {
            // Subscribe to the FrameCreated event to obtain the frame object when 
            // it's created.
            webView.CoreWebView2.FrameCreated += WebView_FrameCreatedDOMContentLoaded;
            webView.NavigateToString(@"<!DOCTYPE html>" +
                                      "<h1>DOMContentLoaded sample page</h1>" +
                                      "<h2>The content to the iframe and below will be added after DOM content is loaded </h2>" +
                                      "<iframe style='height: 200px; width: 100%;'/>");
        }

        void WebView_FrameCreatedDOMContentLoaded(object sender, CoreWebView2FrameCreatedEventArgs args)
        {
            // In order for ExecuteScriptAsync to successfully run inside the iframe, 
            // subscribe to the ContentLoading or DOMContentLoaded event.  Once these 
            // events are raised, you can call ExecuteScriptAsync.
            args.Frame.DOMContentLoaded += (frameSender, DOMContentLoadedArgs) =>
            {
                args.Frame.ExecuteScriptAsync(
                    "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);");
            };
        }

API 參考概觀

WebView2 功能和 API 概觀中所列的下列功能包括框架相關的 API：

另請參閱

外部頁面：