從 Web 端程式碼呼叫原生端 WinRT 程式碼

安裝 Visual Studio

• 如果尚未安裝 Visual Studio 2015 或更新版本，請在個別的視窗或索引標籤中，參閱在設定 WebView2 的開發環境中安裝 Visual Studio。 遵循該節中的步驟，然後返回此頁面並繼續執行下列步驟。 本文顯示 Visual Studio Community 2022 版的螢幕擷取畫面。

安裝 Microsoft Edge 的預覽通道

• 如果尚未在個別視窗或索引標籤中安裝 Microsoft Edge (Beta、Dev 或 Canary) 的預覽通道，請參閱在設定WebView2 的開發環境中安裝 Microsoft Edge 的預覽通道。 遵循該節中的步驟，然後返回此頁面並繼續執行下列步驟。

建立或開啟基本 WebView2 專案

1. 請執行下列任何方法來取得基準入門專案，其中包含內嵌 WebView2 控制項的幾行 WebView2 程式碼：

   • 使用提供的基準範例解決方案： 如果尚未完成，請將存放庫複製或下載 WebView2Samples 到本機磁片磁碟機。 在個別的視窗或索引標籤中，請參閱為WebView2 設定開發環境中的下載 WebView2Samples 存放庫。 請遵循該區段中的步驟，然後返回此頁面，然後繼續進行下列步驟。 這個方法會使用您的本機複本 https://github.com/MicrosoftEdge/WebView2Samples/tree/main/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln 。

   • 在 Visual Studio 中使用專案範本來建立基本 UWP 應用程式，並新增 WebView2 控制項： 執行 在 WinUI 2 中開始使用 WebView2 中的步驟 (UWP) 應用程式 ，以建立基準入門專案，其中包含內嵌 WebView2 控制項的幾行 WebView2 程式碼。

   • 使用您現有的程式碼基底： 如果您已經有自己的應用程式程式碼基底，您可以在 Visual Studio 中開啟該專案。

2. 在本機磁片磁碟機上，開啟您在上面取得的 .sln 檔案，例如範例存放庫解決方案：

   • <your-repos-directory>/WebView2Samples-main/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln
   • <your-repos-directory>/WebView2Samples/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln

   範例解決方案會在 Visual Studio 中開啟：

   

3. 在 Visual Studio 中，選取 [偵錯>開始偵錯]。 這會建置專案，然後執行專案的基準版本。 基準應用程式隨即開啟，例如 MyUWPGetStartApp 視窗：

   

   顯示的是已新增 WebView 控制項的 WinUI 2 (UWP) 應用程式，設定為一開始流覽至 Bing.com。 這是在 WinUI 2 中開始使用 WebView2 (UWP) 應用程式中執行步驟所產生的應用程式。

4. 關閉應用程式視窗。

1. 使用 Visual Studio 專案範本來建立全新的方案和專案。 若要這樣做，請執行在 WinUI 3 中開始使用 WebView2 中的步驟 (Windows 應用程式 SDK) 應用程式，然後在下方繼續進行。

   或者，如果您已經有自己的應用程式程式碼基底，您可以在 Visual Studio 中開啟該專案，並新增 WinRTAdapter 專案，如下所示。

   此時，Visual Studio 看起來可能如下所示：

   

   而 WinUI 桌面應用程式看起來可能如下所示：

   

2. 如果 WinUI 桌面 應用程式正在執行，請關閉應用程式。

3. 下列 Visual Studio 對話方塊可能會出現。 這些偵錯工具對話方塊是已知的錯誤。 按一下 [ 確定] 按鈕，然後按一下 [ 取消 ] 按鈕以關閉這些對話方塊：

   

1. 在 [ 專案名稱 ] 文字方塊中，將專案命名為 Project，特別是 WinRTAdapter。 注意： 目前，您必須使用此特定專案名稱。

   

   上述螢幕擷取畫面中的路徑會反映複製範例存放庫的方法。

2. 按一下 [ 建立] 按鈕。

   [ 新增 Windows 專案] 對話方塊隨即開啟：

   

3. 按一下 [ 確定] 按鈕。

   WinRTAdapter專案隨即建立，並新增至主要專案旁方案總管：

   

4. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

1. 在 [ 專案名稱 ] 文字方塊中，將專案命名為 Project，特別是 WinRTAdapter。 注意： 目前，您必須使用此特定專案名稱。

   

2. 按一下 [ 建立] 按鈕。

   [ 新增 Windows 專案] 對話方塊隨即開啟：

   

3. 按一下 [ 確定] 按鈕。

   WinRTAdapter專案隨即建立，並新增至主要專案旁方案總管：

   

4. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

1. 在方案總管中，以滑鼠右鍵按一下WinRTAdapter專案，然後選取 [管理 NuGet 套件]。 [NuGet 套件管理員]視窗會在 Visual Studio 中開啟。

2. 在 [NuGet 套件管理員] 視窗中，按一下 [ 流覽] 索引卷 標。

3. 在 [NuGet 套件管理員] 視窗的 [ 搜尋 ] 方塊中，輸入 Windows 實作程式庫，然後選取 [Windows 實作程式庫 ] 卡片：

   

4. 按一下 [ 安裝] 按鈕。 [ 預覽變更 ] 對話方塊隨即開啟：

   

5. 按一下 [ 確定] 按鈕。

6. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

1. 在方案總管中，以滑鼠右鍵按一下WinRTAdapter專案，然後選取 [管理 NuGet 套件]。 [NuGet 套件管理員]視窗會在 Visual Studio 中開啟。

2. 在 [NuGet 套件管理員] 視窗中，按一下 [ 流覽] 索引卷 標。

3. 在 [NuGet 套件管理員] 視窗的 [ 搜尋 ] 方塊中，輸入 Windows 實作程式庫，然後選取 [Windows 實作程式庫 ] 卡片：

   

4. 按一下 [ 安裝] 按鈕。

5. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

1. 在方案總管中，以滑鼠右鍵按一下WinRTAdapter專案，然後選取 [管理 NuGet 套件]。 [NuGet 套件管理員] 視窗隨即開啟。

2. 在 [NuGet 套件管理員] 視窗中，按一下 [ 流覽] 索引卷 標。

3. 選取 [ 包含發行前版本] 複 選框。

4. 在 [ 搜尋] 方 塊中，輸入 WebView2。

5. 按一下 Microsoft.Web.WebView2 卡片。 詳細資訊會出現在視窗的中間區域。

6. 在 [ 版本] 下拉式清單中，選取 WebView2 SDK 的 發行前 版本，或確定已選取 [最新發行前版本 ]。 版本必須是 1.0.1243.0 或更高版本。 請注意您選取的版本號碼。

   

7. 按一下 [ 安裝] 按鈕。 [ 預覽變更 ] 對話方塊隨即開啟：

   

8. 按一下 [ 確定] 按鈕。

9. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

1. 在方案總管中，以滑鼠右鍵按一下WinRTAdapter專案，然後選取 [管理 NuGet 套件]。 [NuGet 套件管理員] 視窗隨即開啟。

2. 在 [NuGet 套件管理員] 視窗中，按一下 [ 流覽] 索引卷 標。

3. 選取 [ 包含發行前版本] 複 選框。

4. 在 [ 搜尋] 方 塊中，輸入 WebView2。

5. 按一下 Microsoft.Web.WebView2 卡片。 詳細資訊會出現在視窗的中間區域。

6. 在 [ 版本] 下拉式清單中，選取 WebView2 SDK 的 發行前 版本，或確定已選取 [最新發行前版本 ]。 版本必須是 1.0.1243.0 或更高版本。 請注意您選取的版本號碼。

   

7. 按一下 [ 安裝] 按鈕。

8. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

在主要專案中，例如 MyUWPGetStartApp，安裝與您為 WinRTAdapter 專案安裝的相同 WebView2 SDK 發行前版本，如下所示：

1. 在方案總管中，以滑鼠右鍵按一下主要專案，例如MyUWPGetStartApp，然後選取 [管理 NuGet 套件]。 [NuGet 套件管理員] 視窗隨即開啟。

2. 選取 [ 包含發行前版本] 複 選框。

3. 選取 [ 流覽] 索引卷 標。

4. 在 [ 搜尋] 方 塊中，輸入 WebView2。

5. 按一下 Microsoft.Web.WebView2 卡片。 詳細資訊會出現在視窗的中間區域。

6. 在 [ 版本] 下拉式清單中，選取 WebView2 SDK 的 發行前 版本，或確定已選取 [最新發行前版本 ]。 請務必使用 與 WinRTAdapter 專案所使用的相同版本;針對以 WinUI 2 (UWP) 為目標的 WinRT WebView2 應用程式，這必須與 WinRTAdapter 專案版本相同。 版本必須是 1.0.1243.0 或更高版本。

7. 按一下 [ 安裝] 按鈕。 [預覽變更] 對話方塊隨即開啟，將 WebView2 新增至主要專案。

8. 按一下 [ 確定] 按鈕。

   Visual Studio 看起來應該類似上述的步驟區段，不同之處在于現在 ，NuGet 套 件管理員已針對主要專案而非 WinRTAdapter 專案開啟。

9. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

現在已針對主要專案安裝 WebView2 發行前版本 SDK。

如果您的應用程式以 WinUI 3 (Windows 應用程式 SDK) 為目標，請略過此步驟，因為：

• WinUI 3 會配套 WebView2 SDK，因此不需要個別下載 WebView2 SDK。

• WinUI 3 不支援發行前版本 WebView2 SDK。

在主要專案中，例如 MyUWPGetStartApp，新增指向 WinRTAdapter 專案的參考，如下所示：

1. 在方案總管中，展開主要專案，例如MyUWPGetStartApp，以滑鼠右鍵按一下 [參考]，然後選取 [新增參考]。 [ 參考管理員 ] 對話方塊隨即開啟。

2. 在左側樹狀結構中，選取 [ 專案]。 選取 [WinRTAdapter] 複 選框：

   

3. 按一下 [ 確定] 按鈕以關閉 [ 參考管理員 ] 對話方塊。

4. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

在非配接器主要專案中，例如 MyWebView2WinUI3，新增指向 WinRTAdapter 專案的參考，如下所示：

1. 在方案總管中，選取主要專案，例如MyWebView2WinUI3。 然後在功能表列中，選取 [專案>新增專案參考]。 [ 參考管理員 ] 對話方塊隨即開啟。

2. 在左側樹狀結構中，選取 [ 專案]。 選取 [WinRTAdapter] 複 選框：

   

3. 按一下 [ 確定] 按鈕以關閉 [ 參考管理員 ] 對話方塊。

4. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

如果您的應用程式適用于 WinUI 2 (UWP) ，請略過此步驟。

更新 OS 目標

本節僅適用于 WinUI 3 (Windows 應用程式 SDK) 。

1. 更新或檢查 TargetFramework 檔案中的 .csproj ，如下所示。

   如果您建置主要專案，您可能會在 [檢視>錯誤清單] 窗格中收到如下的警告：

   「MSB3851此專案的目標為 」Windows， Version=10.0.19041.0「，但它嘗試參考 」WinRTAdapter.winmd「 目標為 」UAP，Version=10.0.22000.0「，這是不正確。」

   

   修正該警告或檢查值，如下所示：

1. 判斷 WinRTAdapter 的目標版本：以滑鼠右鍵按一下WinRTAdapter專案，選取 [屬性]，展開並選取 [組態屬性>一般]，然後檢查 [目標平臺版本] 字段：

   

2. 記下 [目標平臺版本]，然後按一下 [ 確定] 按鈕以關閉 [ 屬性頁 ] 對話方塊。

1. 在 Visual Studio 中，選取[檔案>開啟>檔案]。 [ 開啟檔案] 對話方塊隨即開啟。

2. 開啟 .csproj 檔案，例如 MyWebView2WinUI3.csproj 。

3. 如果 Visual Studio 未在程式碼編輯器中顯示行號，請選擇性地開啟行號。 若要這樣做，請選取 [工具>選項>文字編輯器>所有語言>行號]。 然後按一下 [ 確定] 按鈕。

4. 在 檔案中 .csproj ，將 行中的 <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework> 版本號碼更新為與您在上面取得的 WinRT 配接器版本相同。

   例如，從下列專案變更行：

   <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
   

   自：

   <TargetFramework>net6.0-windows10.0.22000.0</TargetFramework>
   

5. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

OS 目標現在已更新。

在專案檔中新增 CsWinRT 和 WinRTAdapter

本節僅適用于 WinUI 3 (Windows 應用程式 SDK) 。

在專案檔中新增 CsWinRT 和 WinRTAdapter 套件：

1. 在 Visual Studio 中，選取[檔案>開啟>檔案]。 [ 開啟檔案] 對話方塊隨即開啟。

2. 開啟 .csproj 檔案，例如 MyWebView2WinUI3.csproj 。

3. 在已經包含某些 <PackageReference> 元素的 <ItemGroup> 元素內新增下列 <PackageReference> 專案。 您可以將它新增至其他 <PackageReference> 元素下方：

   <ItemGroup>
       ...
       <PackageReference Include="Microsoft.Windows.CsWinRT" Version="1.6.4"/>
       ...
   </ItemGroup>
   

4. 在 元素中 <PropertyGroup> ，新增下列屬性群組參考。 您可以將它新增至該元素的底部：

   <PropertyGroup>
       ...
       <CsWinRTIncludes>WinRTAdapter</CsWinRTIncludes>
   </PropertyGroup> 
   

5. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

安裝單一專案 MSIX 封裝工具

本節僅適用于 WinUI 3 (Windows 應用程式 SDK) 。

1. 在方案總管中，以滑鼠右鍵按一下WinRTAdapter專案，然後選取 [建置]。

2. 選取 [檢視>錯誤清單]。

3. 在方案總管中，以滑鼠右鍵按一下主要專案，然後選取 [建置]。

4. 選取 [檢視>錯誤清單]。

   您可能會收到下列錯誤：

   「無法參考 WinRTAdapter.winmd。 不支援在目標為 .NET 5 或更高版本時直接參考 Windows 中繼資料 NETSDK1 元件。」

   

5. 若要修正該錯誤，請下載並安裝 適用于 VS 2022 的單一專案 MSIX 封裝工具。 如果沒有這些封裝工具，專案將會建置，但不會執行。

按兩下下載的檔案之後的 VSIX 安裝程式 對話方塊：

[ 安裝完成] 對話方塊：

1. 如果您的應用程式是未封裝的應用程式，您也必須執行使用 Windows 執行階段 元件增強非封裝桌面應用程式中的步驟。

2. 在方案總管中，以滑鼠右鍵按一下主要專案，然後選取 [建置]。

3. 選取 [檢視>錯誤清單]。

4. 選取 [偵錯>開始偵錯] (F5) 。

   WinUI 3 應用程式隨即開啟：

   

5. 關閉應用程式。

6. 下列 Visual Studio 對話方塊可能會出現。 這些偵錯工具對話方塊是已知的錯誤。 按一下 [ 確定] 按鈕，然後按一下 [ 取消 ] 按鈕以關閉這些對話方塊：

   

7. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

1. 在方案總管中，展開主要專案，例如MyUWPGetStartApp、展開MainPage.xaml，然後選取MainPage.xaml.cs。

2. 在 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 元件。

3. 在建構函式的 MainPage 下方 this.InitializeComponent(); ，新增下列程式碼：

   InitializeWebView2Async();
   

4. 以滑鼠右鍵按一下主要專案，例如 MyUWPGetStartApp，然後選 取 [設定為啟始專案]。 粗體表示啟動專案。

5. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

6. 按 F5 執行範例應用程式。 已啟用 WebView2 的 WinUI 2 (UWP) 應用程式隨即開啟：

   

接下來，將 WinRT 物件從主應用程式的原生端傳遞至主應用程式的 Web 端。 若要這樣做，請新增 InitializeWebView2Async 呼叫 AddHostObjectToScript 的方法，如下所示：

1. 在方案總管中，展開主要專案，例如MyWebView2WinUI3，然後選取MainWindow.xaml.cs。

2. 在 MainWindow 建構函式下方，新增下列 InitializeWebView2Async 方法：

   private async void InitializeWebView2Async()
   {
      await MyWebView.EnsureCoreWebView2Async();
      var dispatchAdapter = new WinRTAdapter.DispatchAdapter();
      MyWebView.CoreWebView2.AddHostObjectToScript("Windows", dispatchAdapter.WrapNamedObject("Windows", dispatchAdapter));
   }
   

   請注意，在上述兩個位置中，會使用變數名稱 MyWebView 。 此名稱必須符合檔案中的其他位置。 有些範例會改用這裡的名稱 webView2 。

   這個方法會呼叫 AddHostObjectToScript 。

   在 行中 AddHostObjectToScript("Windows", ... ， Windows 是最上層命名空間。 如果您有其他最上層命名空間，您可以將其他呼叫新增至 AddHostObjectToScript ，如下列範例所示：

   WebView2.CoreWebView2.AddHostObjectToScript("RuntimeComponent1", dispatchAdapter.WrapNamedObject("RuntimeComponent1", dispatchAdapter));
   

   呼叫 WrapNamedObject 會建立命名空間的 RuntimeComponent1 包裝函式物件。 呼叫會 AddHostObjectToScript 使用名稱 RuntimeComponent1 將包裝的物件加入腳本。

   如需如何使用自訂 WinRT 元件的完整指引，請參閱下方 的自訂 (協力廠商) WinRT 元件。

3. 在建構函式的 MainPageMyWebView.NavigationStarting += EnsureHttps; 行下方，新增下列程式碼：

   InitializeWebView2Async();
   

4. 以滑鼠右鍵按一下主要專案，例如 MyWebView2WinUI3，然後選 取 [設定為啟始專案]。 粗體表示啟動專案。

5. 選取 [檔案全部儲存> (Ctrl+Shift+S) 。

6. 按 F5 執行範例應用程式。 WinUI 桌面視窗隨即開啟：

   

恭喜您！ 您已完成從 JavaScript 程式碼呼叫 WinRT 程式碼的範例示範。

• 下列 Visual Studio 對話方塊可能會出現。 這些偵錯工具對話方塊是已知的錯誤。 按一下 [ 確定] 按鈕，然後按一下 [ 取消 ] 按鈕以關閉這些對話方塊：

  

恭喜您！ 您已完成從 JavaScript 程式碼呼叫 WinRT 程式碼的範例示範。

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;" +
                    "}" +
                "})();");

webView->CoreWebView2->AddScriptToExecuteOnDocumentCreatedAsync(
            LR"(
                (() => {
                    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;
                    }
                })();
            )"));