在 WinUI 3 (Windows App SDK) 應用程式中開始使用 WebView2

本文涵蓋如何設定您的開發工具，並建立適用於 WinUI 3 的初始 WebView2 應用程式 (Windows App SDK) ，以及瞭解一路的 WebView2 概念。

在本教學課程中，您會使用 空白應用程式、封裝在桌面 (WinUI) Visual Studio 專案範本來建立空白的 WinUI 3 專案。 該專案範本會使用 WindowsAppSDK，其中包含 WebView2 SDK。 您可以新增 WebView2 控制件。 然後，當使用者嘗試瀏覽至具有 http:// 前置詞的 URL 時，您會新增網址列和邏輯來顯示警告對話方塊。

已完成的專案

自 2020 年起 (此教學課程專案的完整版本) 可在 WebView2Samples 存放 庫中取得：

• 範例名稱： WinUI3_GettingStarted
• 存放庫目錄： WinUI3_GettingStarted
• 解決方案檔： WinUI_Sample.sln

本教學課程已更新，且只會建立單一專案，而不是像 2020 年一樣的第二個「 (封裝) 」專案。

步驟 1 - 安裝 Visual Studio 和 Windows App SDK

即使您已安裝 Visual Studio，請閱讀下列頁面，並可能更新您的軟體並安裝專案範本。

1. 在新的視窗或索引標籤中，開啟 Windows App SDK 的 [安裝工具 ] 頁面，然後遵循該頁面上的步驟，安裝 Microsoft Visual Studio，例如 Visual Studio 2022。

1. 如有需要，在新的視窗或索引標籤中，請參閱在設定 WebView2 的開發環境中安裝 Visual Studio。

從該頁面返回，並繼續執行下列步驟。

在此範例中，您不需要個別安裝 WebView2 SDK。 在下方，您將選取專案範本 空白應用程式、在 Desktop) 中封裝 (WinUI ，其使用包含 WebView2 SDK 的 WindowsAppSDK。

步驟 2 - 建立空白 WinUI 3 專案

若要建立 WebView2 應用程式，請從建立基本桌面項目開始，以建立包含單一主視窗的傳統型應用程式：

1. 如果 Visual Studio 未執行，請啟動 Visual Studio (而非 Visual Studio Code) 。 在 Visual Studio 啟動視窗中，按兩下 [ 建立新的專案 ] 卡片。 [ 建立新專案] 視窗隨即開啟。

   或者，如果 Visual Studio 正在執行，請選取 [檔案>新增>專案]。 [ 建立新專案] 對話框隨即開啟。

   開啟開發人員模式： 當 Visual Studio 在本文步驟的某個時間點開啟時，系統可能會提示您開啟電腦的開發人員模式。 如需詳細資訊，如有需要，請參閱為 Windows 建置傳統型應用程式中的啟用您的裝置以進行開發。

2. 在 [ 建立新專案] 對話框的 [ 搜尋範本 ] 字段中，於 [桌面] 中輸入 WinUI 3：

   

3. 按兩下 [空白應用程式]、[已封裝 (桌面中的 WinUI]) 卡片來選取它，然後按兩下 [ 下一步] 按鈕。

   如果未列出 WinUI 範本，您必須從 Windows App SDK 的安裝工具安裝如上所述的項目範本。 讓範本出現的其他秘訣：

   安裝 Visual Studio 2022 Community 版本的「預設」選項之後，請在 Visual Studio 安裝程式中按下 .NET 卡片，然後選取右側的 [ Windows App SDK C# 範本] 複選框。

   如果仍然未出現正確的項目範本：在 Visual Studio 安裝程式中，按兩下 UWP 卡以選取它，選取右側 的 [v143 C++工具 ] 複選框，然後按兩下 [ 修改 ] 按鈕。

   [ 設定您的新專案 ] 對話框隨即出現。

4. 在 [ 項目名稱 ] 文字框中，輸入專案名稱，例如 MyWebView2WinUI3：

   

5. 在 [ 位置] 文字框中，輸入或瀏覽至位置，例如 C:\Users\username\Documents\WebView2。

6. 按兩下 [ 建立] 按鈕。

   新的 WinUI 3 專案會在 Visual Studio 的 [方案總管] 中開啟：

   

   • 檔案 App.xaml.cs 會定義代表 Application 您應用程式實例的類別。

   • 檔案 MainWindow.xaml.cs 會定義類別 MainWindow ，代表應用程式實例所顯示的主視窗。 類別衍生自 WinUI 命名空間中的 Microsoft.UI.Xaml 類型。

7. 在視窗) 頂端 (的 [ 解決方案 組態] 下拉式清單中，選取 [ 偵錯]。

8. 在 [ 解決方案平臺] 下拉式清單中，選取平臺，例如 x64。

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

10. 按 F5 以組建及執行專案。 空白的 WinUI 桌面應用程式隨即開啟，尚未新增任何 WebView2 控制項：

    

11. 關閉應用程式。

更新目標版本號碼

針對上述建置步驟：如果您要更新先前的專案，您可能需要更新 目標版本 和 最低版本的版本號碼。 若要這樣做，請在 [方案] 中，以滑鼠右鍵按兩下專案，然後選取 [ 編輯項目檔]。 您的 .csproj 檔案隨即開啟。 請確定值已更新如下，然後儲存任何變更並建置專案。

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

上述值代表：

• 目標版本： Windows 10 版本 2004 (組建 19041) 或更新版本。
• 最低版本： Windows 10 版本 1809 (組建 17763) 。

步驟 3 - 新增 WebView2 控制件

本教學課程專案是以專案範本 空白應用程式為基礎，已封裝 (計算機中的 WinUI) 。 此項目範本使用 WindowsAppSDK，其中包含 WebView2 SDK。

MainWindow.xaml編輯 和 MainWindow.xaml.cs 檔案，將 WebView2 控制項新增至空白的 WinUI 3 應用程式專案，如下所示：

1. 在 Visual Studio 的 [方案總管] 中，按兩下 MainWindow.xaml 以在程式碼編輯器中開啟它。

2. 在開始標記內 <Window> 插入下列屬性，以新增 WebView2 XAML 命名空間：

   xmlns:controls="using:Microsoft.UI.Xaml.Controls"
   

   請確定中的 MainWindow.xaml 程式代碼類似下列內容：

   <Window
       x:Class="MyWebView2WinUI3.MainWindow"
       xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       xmlns:local="using:MyWebView2WinUI3"
       xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
       xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
       mc:Ignorable="d">
   
       <StackPanel Orientation="Horizontal" HorizontalAlignment="Center" VerticalAlignment="Center">
           <Button x:Name="myButton" Click="myButton_Click">Click Me</Button>
       </StackPanel>
   </Window>
   

3. 若要新增 WebView2 控制件，請以下列<Grid>程式代碼取代整個<StackPanel>專案。 靠近 Source 底部的 屬性會設定 WebView2 控制件中顯示的初始 URI (https://www.microsoft.com) ：

   <Grid>
   
       <Grid.RowDefinitions>
           <RowDefinition Height="Auto"/>
           <RowDefinition Height="*"/>
       </Grid.RowDefinitions>
       <Grid.ColumnDefinitions>
           <ColumnDefinition Width="*"/>
           <ColumnDefinition Width="Auto"/>
       </Grid.ColumnDefinitions>
   
       <controls:WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
           Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/>
   
   </Grid>
   

4. 在 [方案總管] 中，展開 MainWindow.xaml ，然後開啟 MainWindow.xaml.cs。

5. 在 MainWindow.xaml.cs中，將下列這一行批注化，如下所示：

       // myButton.Content = "Clicked";
   

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

7. 按 F5 鍵以建置並執行專案。

8. 應用程式是包含 WebView2 控制件的 WebView2 主應用程式。 WebView2 控制件會顯示網站 https://www.microsoft.com：

   

9. 關閉應用程式。

WinAppSDK 支援自定義 WebView2 環境

WinAppSDK 支援自定義 WebView2 環境，從 WinAppSDK 1.5 (1.5.0-experimental2) 開始。 如需詳細資訊，請參閱 具有自定義 CoreWebView2Environment 的 WinUI3 WebView2。

若要具現化自定義 WebView2 環境，請使用下列其中一個 (覆 WebView2.EnsureCoreWebView2Async 寫初始化 WebView2) ，並傳入您的自定義 (，並選擇性地傳入自定義 CoreWebView2EnvironmentCoreWebView2ControllerOptions) ：

public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment)
public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment, CoreWebView2ControllerOptions controllerOptions)

另請參閱下方停 用 SmartScreen 導覽中的範例程式代碼。

API 參考：

• WebView2.EnsureCoreWebView2Async
• CoreWebView2ControllerOptions
• CoreWebView2Environment
• CoreWebView2EnvironmentOptions

步驟 4 - 新增導覽控件

若要允許使用者控制 WebView2 控制件中顯示的網頁，請將網址列新增至應用程式，如下所示：

1. 在 中 MainWindow.xaml，將下列程式代碼貼到 <Grid> 包含 元素的 元素內 <controls:WebView2> ：

      <TextBox Name="addressBar" Grid.Column="0"/>
      <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>
   

   請確定檔案中MainWindow.xaml產生的<Grid>專案符合下列專案：

   <Grid>
   
       <Grid.RowDefinitions>
           <RowDefinition Height="Auto"/>
           <RowDefinition Height="*"/>
       </Grid.RowDefinitions>
       <Grid.ColumnDefinitions>
           <ColumnDefinition Width="*"/>
           <ColumnDefinition Width="Auto"/>
       </Grid.ColumnDefinitions>
   
       <TextBox Name="addressBar" Grid.Column="0"/>
       <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>
   
       <controls:WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
       Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/>
   
   </Grid>
   

2. 在 MainWindow.xaml.cs中，將下列程式代碼貼到 myButton_Click中，覆寫幾乎空白) 的現有 myButton_Click 方法 (。 此程式代碼會將 WebView2 控制件巡覽至網址列中輸入的 URL。

   private void myButton_Click(object sender, RoutedEventArgs e)
   {
       try
       {
           Uri targetUri = new Uri(addressBar.Text);
           MyWebView.Source = targetUri;
       }
       catch (FormatException ex)
       {
           // Incorrect address entered.
       }
   }
   

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

4. 按 F5 以組建及執行專案。

5. 在網址列中輸入新的完整 URL，例如 https://www.bing.com，然後按下 [ 移至] 按鈕。

   應用程式中的 WebView2 控制件會顯示 Bing 網站。 網址列會顯示 URL，例如 https://www.bing.com：

   

6. 在網址列中輸入不完整的 URL，例如 bing.com，然後按下 [ 移至] 按鈕。

   系統 ArgumentException 會擲回例外狀況，而且會在您關閉應用程式之後出現，因為URL開頭 http:// 不是或 https://。

7. 關閉應用程式。

步驟 5 - 瀏覽事件

在本節中，您會新增程序代碼以匯入 WebView2 Core 連結庫。

1. 在 MainWindow.xaml.cs中，在頂端的其他語句上方 using 新增下列這一行：

   using Microsoft.Web.WebView2.Core;
   

   裝載 WebView2 控制件的應用程式會接聽 WebView2 控制件在網頁瀏覽期間引發的下列事件：

   • NavigationStarting
   • SourceChanged
   • ContentLoading
   • HistoryChanged
   • NavigationCompleted

   如果發生 HTTP 重新導向，則一個數據列中有多個 NavigationStarting 事件。

   如需詳細資訊，請參閱 WebView2 應用程式的導覽事件。

   發生錯誤時，會引發下列事件，而且可能會顯示錯誤網頁：

   • SourceChanged
   • ContentLoading
   • HistoryChanged

   如需如何使用事件的範例，請註冊 可取消任何非 HTTPS 要求的 處理程式 NavigationStarting ，如下所示：

2. 在 MainWindow.xaml.cs中的 建構函式中，新增下列 NavigationStarting 這一行來註冊 EnsureHttps 方法：

   public MainWindow()
   {
       this.InitializeComponent();
       MyWebView.NavigationStarting += EnsureHttps;
   }
   

3. 在 MainWindow.xaml.cs建構函式下方的 中，新增下列 EnsureHttps 方法：

   private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args)
   {
       String uri = args.Uri;
       if (!uri.StartsWith("https://"))
       {
           args.Cancel = true;
       }
       else
       {
           addressBar.Text = uri;
       }
   }
   

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

5. 按 F5 以組建及執行專案。

6. 在應用程式的網址列中，輸入 HTTP URL，例如 http://bing.com，然後按下 [ 移至] 按鈕。

   不會發生任何事，因為導覽已封鎖至 HTTP 網站，而且我們尚未新增對話框來提供意見反應。

7. 輸入 HTTPS URL，例如 https://bing.com，然後按兩下 [ 移至] 按鈕。

   應用程式會流覽至指定的頁面，因為 HTTPS 網站允許流覽。

8. 關閉應用程式。

步驟 6 - 腳稿

您可以使用主應用程式，在運行時間將 JavaScript 程式代碼插入 WebView2 控制件。 您可以工作 WebView2 執行任意 JavaScript 或新增初始化腳本。 插入的 JavaScript 會套用至所有新的最上層檔和任何子框架，直到移除 JavaScript 為止。 插入的 JavaScript 會以特定時間執行，以執行至下列其中一項：

• 在建立全域對象之後，執行插入的 JavaScript。

• 執行插入的 JavaScript，再執行 HTML 檔中包含的任何其他腳本。

例如，接下來，您會新增腳本，以在使用者嘗試開啟非 HTTPS 網站時傳送警示。 若要這樣做，您可以將腳本插入使用 ExecuteScriptAsync 的 Web 內容中。

1. 在 方法中 EnsureHttps ，新增下列 ExecuteScriptAsync 這一行：

   private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args)
   {
       String uri = args.Uri;
       if (!uri.StartsWith("https://"))
       {
           MyWebView.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
           args.Cancel = true;
       }
       else
       {
           addressBar.Text = uri;
       }
   }
   

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

3. 按 F5 以組建及執行專案。

4. 在應用程式的網址列中，輸入非 HTTPS URL，例如 http://www.bing.com，然後按下 [ 移至] 按鈕。

   應用程式的 WebView2 控制件會顯示非 HTTPS 網站的警示對話框，指出非 HTTPS uri 不安全：

   

5. 關閉應用程式。

恭喜，您建置了第一個 WebView2 應用程式！

WinUI 3 WebView2 特殊考慮

停用 SmartScreen 導覽

WebView2 會將應用程式中巡覽至 的 URL 傳送至 SmartScreen 服務，以確保您的客戶保持安全。 如果您要停用此導覽，請使用自訂 CoreWebView2Environment，如下所示：

CoreWebView2EnvironmentOptions environmentOptions = new CoreWebView2EnvironmentOptions();
environmentOptions.AdditionalBrowserArguments = "--disable-features=msSmartScreenProtection";

string browserFolder = null; // Use null to get default browser folder
string userDataFolder = null; // Use null to get default user data folder
CoreWebView2Environment environment = await CoreWebView2Environment.CreateWithOptionsAsync(
    browserFolder, userDataFolder, environmentOptions);

// ...

this.WebView2.EnsureCoreWebView2Async(environment);

使用環境變數停用 SmartScreen

我們不再建議使用環境變數。 請改用上述以 API 程式代碼為基礎的方法。

• Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");

此環境變數必須在建立之前 CoreWebView2 設定，這會在一開始設定 WebView2.Source屬性 或最初呼叫 WebView2.EnsureCoreWebView2Async方法 時發生。

設定 DefaultBackgroundColor

在 WinUI 3 的 WebView2 中 DefaultBackgroundColor ，設定存在於 WebView2 XAML 物件上。 例如：

public MainWindow()
{
    this.InitializeComponent();
    MyWebView.DefaultBackgroundColor = Colors.LightBlue;
}

透明度

WinUI 3 不支援透明背景。 請參閱 WebView2 的透明背景支援？問題 #2992。

自訂 WebView2 環境的 WinAppSDK 支援

請參閱上面的 WinAppSDK 支援自訂 WebView2 環境。

另請參閱

• WebView2 API 參考
• Microsoft Edge WebView2 簡介 - 功能概觀。
• 管理用戶資料資料夾
• WebView2 的範例程式代碼 - 存放庫指南 WebView2Samples 。
• WebView2 應用程式的開發最佳做法開發最佳做法

developer.microsoft.com：

• Microsoft Edge WebView2 - WebView2 功能的初始簡介，網 developer.microsoft.com。

GitHub：

• 在 WinUI3 中開始使用 WebView2
• 規格：WebView2 Xaml 控制項 - WebView2 控制件的 WinUI 3.0 版本。
• microsoft-ui-xaml 存放庫 > 問題 - 輸入 WinUI 特定的功能要求或 Bug。