你的網頁端 JavaScript 程式碼可以利用 wv2winrt 工具 (WebView2 WinRT JS 投影工具) 來存取原生端的 WinRT 方法與屬性。 wv2winrt 工具會產生 JavaScript 程式碼所需的程式碼檔，並啟用任何 WinRT API 的方法與屬性，包括：
- 你的 WebView2 主機應用程式的 WinRT API。
- Windows WinRT API。
- 第三方 WinRT API。
想了解更多關於為什麼你希望網頁端 JavaScript 程式碼存取 WinRT 主機應用程式的方法與屬性，請參考 Call 原生端程式碼的介紹。
為什麼 WinRT 和 .NET 採用不同的方法
本文是針對 WinRT WebView2 API，而非 .NET WebView2 API。 本文中的 C# 程式碼會為 .NET WebView2 API 建置，但不會執行。
AddHostObjectToScript使用本文中 .NET WebView2 API 的 C# 程式碼呼叫會產生錯誤訊息。
wv2winrt 工具 (WebView2 WinRT JS 投影工具) 投影 WinRT 物件時是必需的，因為 WinRT 不支援IDispatch或任何其他機制來動態檢查與互動 WinRT 物件，而 WebView2 的 Win32 和 .NET 平台則支援此功能。 關於 .NET 的 AddHostObjectToScript使用 ，請參見 「從網頁端程式碼呼叫原生端程式碼 」，而非本文。
WinUI 3 與 WinUI 2 的設定差異
如果您的 WinRT WebView2 應用程式針對 WinUI (Windows App 3 SDK) ，而非 WinUI 2 (UWP) ，以下將提供以下 WinUI 3 專屬步驟的概述：
對於非封裝應用程式，你必須做一些額外步驟，這些步驟在文章《使用 Windows 執行階段元件強化非封裝桌面應用程式》中有說明。
加入
WinRTAdapterCsWinRTIncludes。對於 WinUI 3 (Windows App SDK) 應用程式，主應用程式專案會有一個 WinAppSDK 的參考，而 WinAppSDK 會直接包含 WebView2 SDK 檔案的副本，因此你無法在主應用程式專案中加入 WebView2 SDK 的參考，否則會產生錯誤訊息。
專案轉接器版本不必完全相同。
安裝 Visual Studio 2022 社群版的「預設」選項後，在 Visual Studio 安裝程式中點選 .NET 卡片，然後在右側勾選 Windows App SDK C# 範本的勾選框。
如果正確的專案範本仍然不出現：在 Visual Studio 安裝程式中，點選 UWP 卡片選擇它，然後在右側勾選 v143 C++ 工具的勾選框，然後點擊修改按鈕。
這個例子的策略與最終目標
策略
本文將帶你了解以下主要步驟：
為 WebView2 WinRT JS 投影工具) (建立 wv2winrt 工具的 WinRTAdapter 專案。
在此範例中，請指定以下主機端 API 進行投影：
執行 wv2winrt 工具，產生選取的命名空間或類別的 C++/WinRT 原始碼。
在你的主 WinUI 專案中呼叫 AddHostObjectToScript。
從你的網頁端 JavaScript 程式碼 (或 DevTools 主控台) 呼叫主機物件的方法和屬性。
最終目標
首先，我們會挑選一些我們有興趣從 JavaScript 程式碼呼叫的 WinRT API。 在這個範例中，我們將使用 WinRT Language 類別，它位於 Windows.Globalization 命名空間中，用於 Windows UWP 應用程式。
Windows.Globalization.Language 類別能從用戶端原生作業系統取得語言資訊。
在 WebView2 主機應用程式中，網頁端的 JavaScript 程式碼可以存取原生端程式碼中物件的方法和屬性 Language 。
透過 DevTools Console 存取投影的 API
在這個範例攻略結束時，你會使用 Microsoft Edge DevTools 的 主控台 來測試讀取 displayName 主機的類別屬性 Language ：
const Windows = chrome.webview.hostObjects.sync.Windows;
(new Windows.Globalization.Language("en-US")).displayName;
DevTools 主控台接著會輸出 English (United States)，或是另一種語言的顯示名稱，顯示你已從網頁端的 JavaScript 程式碼呼叫原生端程式碼：
你也可以類似地存取 Windows.System.UserProfile 命名空間 成員。
透過原始碼檔案存取投影的 API
同樣地，你可以在原始碼檔案中存取投影的主機物件，而非 DevTools 主控台。 首先，你執行腳本的設定程式碼：
// early in setup code:
const Windows = chrome.webview.hostObjects.sync.Windows;
然後在程式碼主體中，你要對投影物件加入呼叫，例如以下操作：
(new Windows.Globalization.Language("en-US")).displayName;
你也可以類似地存取 Windows.System.UserProfile 命名空間 成員。
讓我們開始吧！
步驟 1：建立或取得一個基本的 WebView2 專案
安裝 Visual Studio
- 如果還沒安裝 Visual Studio 2015 或更新版本，請在另一個視窗或分頁中，請參考「 安裝 Visual Studio 」的「 設定你的 WebView2 開發環境」。 請依照該部分的步驟操作，然後返回此頁面繼續以下步驟。 本文展示了 Visual Studio Community Edition 2022 的截圖。
安裝 Microsoft Edge 的預覽頻道
- 如果 Microsoft Edge (Beta、Dev 或 Canary) 的預覽頻道尚未安裝，請在另一個視窗或分頁中查看「為 WebView2 設置你的開發者環境」中的「安裝 Microsoft Edge 預覽頻道」。 請依照該部分的步驟操作，然後返回此頁面繼續以下步驟。
建立或開啟一個基本的 WebView2 專案
請採用以下任一方法，取得包含幾行 WebView2 程式碼、嵌入 WebView2 控制項的基線入門專案：
請使用提供的基線樣本解： 如果還沒做，請複製或下載
WebView2Samples倉庫到本地硬碟。 在另一個視窗或分頁中，請參考「為 WebView2 建立你的開發環境下載 WebView2Samples 倉庫」。 請依照該部分的步驟操作，然後返回此頁繼續下方。 此方法使用你本地的副本。https://github.com/MicrosoftEdge/WebView2Samples/tree/main/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln在 Visual Studio 中使用專案範本建立一個基本的 UWP 應用程式，並新增 WebView2 控制項： 在 WinUI 2 (UWP) 應用程式中，依照「Get Start with WebView2 」的步驟，建立一個包含幾行 WebView2 程式碼的基礎起始專案，內嵌 WebView2 控制項。
使用你現有的程式碼庫： 如果你已經有自己的應用程式程式碼庫，可以在 Visual Studio 裡開啟那個專案。
在你的本地硬碟上，打開
.sln你上面取得的檔案，例如 Samples repo 解決方案：<your-repos-directory>/WebView2Samples-main/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln<your-repos-directory>/WebView2Samples/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln
範例解答可在 Visual Studio 開啟：
在 Visual Studio 中，選擇除錯>開始除錯。 這樣會建立專案，然後執行專案的基線版本。 基線應用程式會開啟，例如 MyUWPGetStartApp 視窗：
圖中顯示的是 WinUI 2 (UWP) 應用程式，新增了 WebView 控制項，設定為初始導覽至 Bing.com。 這是透過在 WinUI 2 (UWP) 應用程式中完成「開始使用 WebView2」步驟後產生的應用程式。
關閉應用程式視窗。
步驟 2：為 wv2winrt 工具新增 WinRTAdapter 專案
接著，為 WebView2 WinRT JS 投影工具) (wv2winrt 工具建立 WinRTAdapter 專案。 這個專案會根據執行工具產生的程式碼建構一個函式庫。 這些產生的程式碼允許 WinRT API 暴露在 WebView2 控制項中。
為 wv2winrt 工具新增專案，如下：
在 Visual Studio 裡，從前一步開啟你的 WinUI 專案。
在方案總管中，右鍵點選解決方案 (非專案) ，然後選擇新增>專案。 「 新增專案 」對話框隨即開啟。
在搜尋文字框中輸入 Windows 執行階段 元件 (C++/WinRT) 。
替代方法：如果你沒有依照以下步驟說明，使用 Windows 執行階段 元件範本加入 C++/WinRT () 的專案範本，那麼你需要依照 UWP 應用程式>中的步驟安裝通用 Windows 平台開發工作負載，說明 C++/WinRT 簡介。
選擇 C++/WinRT) (Windows 執行階段 元件卡，然後點擊「下一個」按鈕：
便條： 確保範本名稱中包含「C++/WinRT」。 如果這個範本沒有列出，請從 Visual Studio 安裝程式中安裝通用 Windows 平台開發工作負載。 如果你使用 Visual Studio 2019 但仍然找不到範本，請安裝 Visual Studio >>擴充套件管理擴充套件中的 C++/WinRT 範本與 VS2019 擴充功能的視覺化工具。
「 配置您的新專案 」視窗會打開。
設定與建立專案
在 專案名稱 的文字框中，請指定專案名稱，特別是 WinRTAdapter。 便條： 目前，你必須使用這個特定的專案名稱。
上方截圖中的路徑反映了複製樣本庫的方法。
點擊 「建立 」按鈕。
新 Windows 專案 對話框開啟：
點擊 確定 按鈕。
WinRTAdapter 專案會建立並在方案總管中新增，位於主專案旁邊：
選擇 檔案>全部儲存 (ctrl+shift +s) 。
wv2winrt 工具 (WebView2 WinRT JS 投影工具) 將在此 WinRTAdapter 專案中執行。 在接下來的步驟中，你將為本專案中選定的類別產生程式碼。
步驟 3：安裝 Windows 實作函式庫，用於 WinRTAdapter 專案
在 WinRTAdapter 專案中，安裝 Windows 實作函式庫 (WIL) ，步驟如下：
在方案總管中，右鍵點擊 WinRTAdapter 專案，然後選擇管理 NuGet 套件。 在 Visual Studio 會開啟 NuGet 套件管理器 視窗。
在 NuGet 套件管理器 視窗中，點選「 瀏覽 」標籤。
在 NuGet 套件管理器 視窗的 搜尋 框中，輸入 Windows 實作函式庫，然後選擇 Windows 實作函式庫 卡：
點擊 安裝 按鈕。 預覽 變更 對話框會開啟：
點擊 確定 按鈕。
選擇 檔案>全部儲存 (ctrl+shift +s) 。
WIL 現已安裝於 WinRTAdapter 專案中。 Windows 實作函式庫 (WIL) 是一個僅標頭的 C++ 函式庫，讓 Windows 的 COM 編碼更方便。 它提供可讀且型別安全的 C++ 介面，適用於 Windows COM 編碼模式。
步驟 4：安裝 WinRTAdapter 專案的 WebView2 預發布 SDK
在 WinRTAdapter 專案中，也安裝 WebView2 SDK 的預發布版本，如下：
在方案總管中，右鍵點擊 WinRTAdapter 專案，然後選擇管理 NuGet 套件。 NuGet 套件管理器視窗會打開。
在 NuGet 套件管理器 視窗中，點選「 瀏覽 」標籤。
選擇 「包含預發行 」勾選框。
在 搜尋 框中輸入 WebView2。
點擊 Microsoft.Web.WebView2 卡片。 詳細資訊顯示在視窗中間區域。
在 版本 下拉選單中，選擇 WebView2 SDK 的預發布 版本，或確保已選擇 「最新預發布 」。 版本必須是 1.0.1243.0 或更高。 請注意你選擇的版本號。
點擊 安裝 按鈕。 預覽 變更 對話框會開啟：
點擊 確定 按鈕。
選擇 檔案>全部儲存 (ctrl+shift +s) 。
WebView2 預發布 SDK 現已安裝於 WinRTAdapter 專案中。
步驟 5：安裝 WebView2 預發布版 SDK (僅 WinUI 2)
在主專案中，例如 MyUWPGetStartApp，安裝與 WinRTAdapter 專案相同的預發布版本 WebView2 SDK，如下：
在方案總管中，右鍵點擊主專案，例如 MyUWPGetStartApp，然後選擇「管理 NuGet 套件」。 NuGet 套件管理器視窗會打開。
選擇 「包含預發行 」勾選框。
選擇 瀏覽標籤 。
在 搜尋 框中輸入 WebView2。
點擊 Microsoft.Web.WebView2 卡片。 詳細資訊顯示在視窗中間區域。
在 版本 下拉選單中，選擇 WebView2 SDK 的預發布 版本，或確保已選擇 「最新預發布 」。 務必使用與 WinRTAdapter 專案相同的版本;對於針對 WinUI 2 (UWP) 的 WinRT WebView2 應用程式，這個版本必須與 WinRTAdapter 專案相同。 版本必須是 1.0.1243.0 或更高。
點擊 安裝 按鈕。 預覽變更對話框會打開，將 WebView2 加入主專案。
點擊 確定 按鈕。
Visual Studio 應該看起來和上述步驟區塊類似，只是現在主專案開啟的是 NuGet 套件管理器 ，而不是 WinRTAdapter 專案。
選擇 檔案>全部儲存 (ctrl+shift +s) 。
WebView2 預發布的 SDK 現已安裝於主專案中。
步驟 6：產生選定主機 API 的原始碼
接著，將 wv2winrt 工具 (WebView2 WinRT JS 投影工具) ，整合你想使用的 WinRT 類別。 這會產生原始碼檔案，然後被編譯。 產生這些 API 的程式碼，讓你的網頁端 JavaScript 程式碼能夠呼叫這些 API。
在以下範例步驟中，我們將指定兩個 Windows 命名空間， wv2winrt 工具將僅為這些命名空間下的 API 產生原始碼：
之後，當範例應用程式執行時，你會從 DevTools 控制台呼叫這些 API，以示範這些指定的主機端 API 可以從網頁端程式碼中呼叫。
指定命名空間與類別如下：
在方案總管中，右鍵點選 WinRTAdapter 專案，然後選擇屬性。 WinRTAdapter 屬性頁面對話框會打開。
在左側展開並選擇 Common PropertiesWebView2>。
將使用 WebView2 WinRT API 設為「No」。 這是為了避免 WebView2 SDK 將 WebView2 的 WinRT 元件複製到專案輸出中。 這個 WinRTAdapter 專案沒有呼叫任何 WebView2 的 WinRT API，所以不需要 WinRT 元件。
設定 使用 wv2winrt 工具 為 「是」。
將 使用 JavaScript 的案例 設為 「是」。
在 「包含」篩選 器列中，點選右側欄位，點擊該儲存格的下拉選單，然後點 選「編輯」。 「 包含過濾器 」對話框隨即開啟。
在最頂端的文字框中，將以下字串分開貼在不同行，且不加前置或後置空白：
Windows.System.UserProfile Windows.Globalization.Language
你需要指定命名空間或類別的完整名稱，如上所示。
點擊 確定 按鈕以關閉 「包含篩選器 」對話框。
請確保 WinRTAdapter 屬性頁面 對話框在本次攻略中呈現如下樣貌：
點擊 確定 按鈕以關閉 物業頁面 對話框。
選擇 檔案>全部儲存 (ctrl+shift +s) 。
新增指向轉接器專案的參考
接著，在主專案中新增一個參考，指向轉接專案。
在主專案中，如 MyUWPGetStartApp，請新增指向 WinRTAdapter 專案的參考，如下：
在方案總管中，展開主專案，例如 MyUWPGetStartApp，右鍵點擊參考資料，然後選擇新增參考資料。 參考 管理員 對話框會打開。
在左側的樹狀結構中，選擇 專案。 選擇 WinRTAdapter 的勾選框：
點擊 確定 按鈕關閉 參考資料管理員 對話框。
選擇 檔案>全部儲存 (ctrl+shift +s) 。
產生 API 程式碼
接著，產生 API 程式碼：
右鍵點選 WinRTAdapter 專案，然後選擇 建置。
原始碼會產生你在 wv2winrt 工具的 Include filters 對話框中指定的命名空間或類別， (WebView2 WinRT JS 投影工具) ：
-
Windows.System.UserProfile命名空間 -
Windows.Globalization.Language班
-
建置完成後，選擇>檔案全部儲存 (Ctrl+Shift+S) 。
重要事項
如果你安裝了 WebView2 SDK 的版本，但你的建置在 時失敗 error MIDL2011: [msg]unresolved type declaration [context]: Microsoft.Web.WebView2.Core.ICoreWebView2DispatchAdapter [ RuntimeClass 'WinRTAdapter.DispatchAdapter' ]，這在 WebView2 SDK 的發行版本中是個問題，你需要依照上述步驟將 Use WebView2 WinRT API 改為 「是 」。
或者，在專案檔案WinRTAdapter.vcxproj的最後一個</ItemGroup>後面加上以下內容：
<ItemGroup Condition="'$(WebView2UseDispatchAdapter)' == 'true'">
<Reference Include="$(WebView2SDKPath)lib\Microsoft.Web.WebView2.Core.winmd">
<!-- wv2winrt needs Dispatch Adapter metadata to generate code -->
</Reference>
</ItemGroup>
請將 替換 $(WebView2SDKPath) 為安裝 WebView2 SDK 的目錄，末尾加上 a \ 。 例如：..\<sample-directory>\packages\Microsoft.Web.WebView2.1.0.1264.42\。
步驟 7：只更新目標框架 (WinUI 3)
如果你的應用程式是為 WinUI 2 (UWP) 設計，請跳過這個步驟。
步驟 8：在主專案中新增主機物件
接著，將 WinRT 物件從主機應用程式的原生端傳遞到主機應用程式的網頁端。 為此，加入 InitializeWebView2Async 一個呼叫 AddHostObjectToScript的方法，如下：
在方案總管中，展開主專案，例如 MyUWPGetStartApp，展開 MainPage.xaml，然後選擇MainPage.xaml.cs。
在構造子下方
MainPage，加入以下InitializeWebView2Async方法：private async void InitializeWebView2Async() { await WebView2.EnsureCoreWebView2Async(); var dispatchAdapter = new WinRTAdapter.DispatchAdapter(); WebView2.CoreWebView2.AddHostObjectToScript("Windows", dispatchAdapter.WrapNamedObject("Windows", dispatchAdapter)); }此方法呼叫
AddHostObjectToScript。在這行
AddHostObjectToScript("Windows", ...中，Windows是頂層命名空間。 如果你有其他頂層命名空間，可以為 加入額外的呼叫AddHostObjectToScript，例如以下範例：WebView2.CoreWebView2.AddHostObjectToScript("RuntimeComponent1", dispatchAdapter.WrapNamedObject("RuntimeComponent1", dispatchAdapter));呼叫會
WrapNamedObject為命名空間建立一個包裝物件RuntimeComponent1。 呼叫會AddHostObjectToScript將該包裹物件加入腳本，名稱為RuntimeComponent1。關於如何使用自訂 WinRT 元件的完整指引，請參閱下方 的「自訂 (第三方) WinRT 元件」。
在下方
this.InitializeComponent();的MainPage構造子中，加入以下程式碼：InitializeWebView2Async();右鍵點擊主專案，例如 MyUWPGetStartApp，然後選擇 「設定為啟動專案」。 粗體字表示新創專案。
選擇 檔案>全部儲存 (ctrl+shift +s) 。
按 F5 來執行範例應用程式。 啟用 WebView2 的 WinUI 2 (UWP) 應用程式開啟：
主機應用程式的網頁端程式碼 (與 DevTools 主控台) 現在可以呼叫主機物件指定命名空間或類別的方法與屬性。
步驟 9：從網頁端 JavaScript 呼叫主機物件的方法與屬性
透過 DevTools Console 存取投影的 API
接著，使用 DevTools 控制台示範網頁端程式碼可呼叫 wv2winrt 工具 (WebView2 WinRT JS 投影工具中指定的主機端 API，) ：
如果應用程式沒有執行，在 Visual Studio 按 F5 執行範例應用程式。
點擊 WebView2 範例應用程式視窗的主要部分以顯示焦點，然後按 Ctrl+Shift+I 開啟 Microsoft Edge DevTools。 或者，右鍵點擊頁面，然後選擇 檢查。
Microsoft Edge DevTools 視窗會打開。
如果 Microsoft Edge DevTools 視窗沒有顯示，請按 Alt+Tab 來顯示。
在 DevTools 視窗中，選擇 主控台 標籤。
點擊 「清除主控台 」 (
) 按鈕，或在 主控台 中右鍵點擊，然後選擇 「清空主控台」。 訊息可能會定期出現在主控台中。在 DevTools 主控台中，將以下 Windows.Globalization.Language 類別 程式碼貼上，然後按下 Enter：
const Windows = chrome.webview.hostObjects.sync.Windows; (new Windows.Globalization.Language("en-US")).displayName;主控台會輸出一個語言名稱字串，例如
English (United States)，展示你的應用程式主機端 (原生端) 程式碼可以從網頁端的 JavaScript 程式碼呼叫：
試著省略括號。 在 DevTools 控制台輸入以下陳述：
new Windows.Globalization.Language("en-US").displayName;控制台會輸出一個語言名稱字串，例如
English (United States)。你也可以類似地存取 Windows.System.UserProfile 命名空間 成員。
關閉 DevTools 視窗。
關閉應用程式。
恭喜您！ 你已經完成了從 JavaScript 程式碼呼叫 WinRT 程式碼的範例示範。
透過原始碼檔案存取投影的 API
上面，我們使用 DevTools 主控台來執行存取投影主機物件的 JavaScript 語句。 同樣地，你也可以從原始碼檔案中存取投影的主機物件。 要做到這點，首先你要執行腳本的設定程式碼：
// early in setup code:
const Windows = chrome.webview.hostObjects.sync.Windows;
然後在程式碼主體中，你要對投影物件加入呼叫，例如以下操作：
(new Windows.Globalization.Language("en-US")).displayName;
你也可以類似地存取 Windows.System.UserProfile API 成員。
這就是教學步驟的結束。 以下章節為 WebView2 WinRT 應用程式的一般資訊。
自訂 (第三方) WinRT 元件
wv2winrt 工具 (WebView2 WinRT JS 投影工具，) 支援自訂第三方 WinRT 元件，以及第一方作業系統的 WinRT API。
要使用 wv2winrt 工具使用自訂 (第三方) WinRT 元件，除了上述步驟外，還可執行以下步驟：
在你的 Visual Studio 解決方案中加入第三個專案，除了主應用程式之外， () WinRTAdapter 專案。
讓 WinRTAdapter 專案「新增一個參考」到你新的第三個專案，裡面包含你的 WinRT 類別。
更新 WinRTAdapter 專案的屬性中的 Include 篩選器，讓新類別也包含在內。
新增一行以
InitializeWebView2Async加入你 winrt 類別的命名空間：WebView2.CoreWebView2.AddHostObjectToScript("MyCustomNamespace", dispatchAdapter.WrapNamedObject("MyCustomNamespace", dispatchAdapter));為了方便從網頁調用方法，可以選擇在腳本中將命名空間同步代理加入為全域物件。 例如：
window.MyCustomNamespace = chrome.webview.hostObjects.sync.MyCustomNamespace;
以下 WebView2 範例為例：
- uwp-wv2winrt-custom-csharp-winrt - 一個範例，作為分支。
非同步 WinRT 方法
按照上述指南的步驟，你應該可以使用同步代理。 對於非同步方法呼叫，你需要使用 chrome.webview.hostObjects.options.forceAsyncMethodMatches。
該 forceAsyncMethodMatches 特性是一個正則表達式陣列，若任何正則表達式與同步代理上的方法名稱相符，該方法將改為非同步執行。 將此 [/Async$/] 設定為 ，會與任何以後綴 Async結尾的方法相匹配。 然後匹配的方法呼叫就像非同步代理上的方法一樣，回傳一個你可以等待的承諾。
例如:
const Windows = chrome.webview.hostObjects.sync.Windows;
chrome.webview.hostObjects.options.forceAsyncMethodMatches = [/Async$/];
let result = await Windows.System.Launcher.launchUriAsync(new Windows.Foundation.Uri('https://contoso.com/'));
更多資訊請參閱 forceAsyncMethodMatchesCoreWebView2.AddHostObjectToScript 方法中的該列。
訂閱 WinRT 活動
WinRT 事件也會透過腳本代理被揭露。 你可以透過 addEventListener(string eventName, function handler) and removeEventListener(string eventName, function handler) 方法新增或移除實例 WinRT 事件和靜態 WinRT 事件的事件處理程序。
這些方法的運作方式與同名的 DOM 方法相似。 呼叫時，第一個 addEventListener 參數是你想訂閱的 WinRT 事件的字串名稱，並有一個函式回調，每次事件被觸發時都會呼叫。 用相同參數呼叫 removeEventListener 會取消訂閱該事件。 例如：
const Windows = chrome.webview.hostObjects.sync.Windows;
const coreApplication = Windows.ApplicationModel.Core.CoreApplication;
const coreApplicationView = coreApplication.getCurrentView();
const titleBar = coreApplicationView.titleBar;
titleBar.addEventListener('IsVisibleChanged', () => {
console.log('titlebar visibility changed to: ' + titleBar.isVisible);
});
對於提供事件 args 的 WinRT 事件，這些參數會作為事件處理函式的第一個參數。 例如， Windows.Foundation.Collections.PropertySet.MapChanged 事件中有 IMapChangedEventArgs<string, object> event arg 物件，而該物件作為回調的參數。
const Windows = chrome.webview.hostObjects.sync.Windows;
const propertySet = new Windows.Foundation.Collections.PropertySet();
propertySet.addEventListener('MapChanged', eventArgs => {
const key = eventArgs.key;
const collectionChange = eventArgs.collectionChange;
// ...
});
事件 args 物件還會具備以下屬性：
| 內容名稱 | 描述 |
|---|---|
target |
引發事件的物件 |
type |
事件的字串名稱 |
detail |
一個包含所有參數的陣列，提供給 WinRT 代理 |
讓 AddHostObjectToScript 的 JavaScript 代理更像其他 JavaScript API
AddHostObjectToScript 預設使用非同步且冗長的代理，但你可以讓 AddHostObjectToScript JavaScript 代理更像其他 JavaScript API 一樣運作。 想了解更多關於 AddHostObjectToScript 其預設行為，請參閱 AddHostObjectToScript。 此外，如果你是從 JavaScript 的 WinRT 投影遷移主機應用程式到 JavaScript UWP 應用程式，或是從基於 EdgeHTML 的 WebView 遷移過來，建議採用以下方法，以更好地匹配先前的行為。
為了讓 AddHostObjectToScript JavaScript 代理更像其他 JavaScript API，請設定以下屬性：
chrome.webview.hostObjects.option.defaultSyncProxy- 代理可以是非同步或同步的。 通常我們知道，當呼叫同步代理的方法時，結果也應該是同步代理。 但在某些情況下，我們會失去這個上下文，例如在提供函式參考給原生程式碼，然後本機程式碼之後再呼叫該函式時。 在這些情況下，代理將是非同步的，除非設定了這個屬性。chrome.webview.hostObjects.options.forceAsyncMethodMatches- 這是一個正則表達式陣列。 如果你呼叫同步代理上的方法，且該方法名稱與該陣列中的字串或正則表達式相符，該方法呼叫實際上會是非同步執行的。 將此值設為 [/Async$/]，任何以 結Async尾的方法都會變成非同步的方法呼叫。 如果非同步方法與此不符且未強制非同步，該方法將被同步呼叫，阻擋呼叫 JavaScript 的執行，然後回傳承諾的解析，而非回傳承諾。chrome.webview.hostObjects.options.ignoreMemberNotFoundError- 如果你嘗試取得代理的某個屬性值，而該屬性在對應的原生類別中不存在，你會遇到例外——除非你將此屬性設為true，否則行為會與 Chakra WinRT 投影行為 (及一般 JavaScript 行為相符，且) 且無錯誤地回傳undefined。
Chakra WinRT 投影會將 WinRT 命名空間直接放在根物件上。 相較之下：
-
AddHostObjectToScript在 上放置非同步根代理。chrome.webview.hostObjects -
AddHostObjectToScript在 上放置同步根代理。chrome.webview.hostObjects.sync
要存取 Chakra WinRT 投影程式碼預期的根代理，你可以將根代理的 WinRT 命名空間位置指派到根物件上。 例如：
window.Windows = chrome.webview.hostObjects.sync.Windows;
為了確保設定這些的 JavaScript 先執行，你可以把上述陳述加入你的 JavaScript，或者用這個 CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync 方法讓 WebView2 先注入上述陳述，再執行其他腳本。
以下範例展示了上述技術：
webview.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync(
"(() => {" +
"if (chrome && chrome.webview) {" +
"console.log('Setting up WinRT projection options');" +
"chrome.webview.hostObjects.options.defaultSyncProxy = true;" +
"chrome.webview.hostObjects.options.forceAsyncMethodMatches = [/Async$/,/AsyncWithSpeller$/];" +
"chrome.webview.hostObjects.options.ignoreMemberNotFoundError = true;" +
"window.Windows = chrome.webview.hostObjects.sync.Windows;" +
"}" +
"})();");
獲取 WebView2 物業資訊
關於 WebView2 物業的資訊可在兩個地方取得：
- WinRTAdapter 專案的屬性頁面。
-
wv2winrt.exe命令列幫助。 這是 WebView2 WinRT JS 投影工具) (wv2winrt 工具。
WinRTAdapter 專案的屬性頁面
在 WinRTAdapter 專案的物業頁面中，若需有關物件的協助，請點擊物件列。 說明框底部顯示幫助：
wv2winrt.exe 屬性的命令列幫助
命令列說明 wv2winrt.exe 提供了關於 WebView2 WinRT JS 投影工具) Wv2Winrt 工具參數 (資訊。 例如：
| 參數 | 描述 |
|---|---|
verbose |
列出一些內容以篩選，包括已建立的檔案及包含與排除規則的資訊。 |
include |
如上所述，列表預設會排除命名空間和執行類別，僅有列出的。 include 宣告可以是包含該命名空間中所有內容的命名空間，或是僅包含該 runtimeclass 的 runtimeclass 名稱。 |
use-javascript-case |
修改產生的程式碼，產生方法名稱、屬性名稱等，這些格式與 Chakra JavaScript WinRT 投影相同。 預設做法是製作與 winrt 相符的名字。 |
output-path |
設定產生檔案將被寫入的路徑。 |
output-namespace |
設定產生的 WinRT 類別所使用的命名空間。 |
winmd-paths |
一份以空間劃分的清單，列出所有應檢視用於程式碼產生的 winmd 檔案。 |
另請參閱
教學與範例：
- 開始使用 WinUI 2 (UWP) 應用程式 - 教學：使用專案範本使用 WebView2 建立應用程式的步驟。
- WinUI 2 (UWP) 範例應用程式 - 範例：下載、建置、執行及更新範例的步驟。
API 參考：
- WinRT： CoreWebView2.AddHostObjectToScript 方法
- Win32： ICoreWebView2：：AddHostObjectToScript 方法
- .NET： CoreWebView2.AddHostObjectToScript 方法
.NET 等效文章：
- 從網頁端程式碼呼叫原生端程式碼 ——涵蓋 Win32/C++，也涵蓋 .NET/C# 的部分框架內程式碼。