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

本文涵蓋如何設定您的開發工具，並建立 WinUI 3 的初始 WebView2 應用程式 (Windows 應用程式 SDK) ，以及瞭解一路的 WebView2 概念。 您會先在 Desktop) Visual Studio 專案範本 中使用空白應用程式、已封裝 (WinUI 3 ，其中使用包含 WebView2 SDK 的 WindowsAppSDK。 然後新增 WebView2 控制件、網址列和 [移 至] 按鈕，以及 URL 邏輯，只允許瀏覽至 HTTPS URL。

在本教學課程中，您會執行下列動作：

1. 設定開發環境。

2. 使用Desktop) Visual Studio專案範本 中的空白應用程式、已封裝 (WinUI 3 專案範本來建立空白的 WinUI 3 專案，以定義包含按鈕的應用程式。

3. 新增 WebView2 控制件而非按鈕，並一開始流覽至Microsoft首頁。 支援 WebView2，因為專案範本使用包含 WebView2 SDK 的 Microsoft.WindowsAppSDK NuGet 套件。

4. 新增網址列做為文字框控件，然後使用輸入的 HTTPS 字串巡覽至新的網頁：

   

5. 將 JavaScript 插入 WebView2 控件，以在使用者嘗試流覽至只有前置詞而https://非 http:// 的 URL 時，顯示警告警示 (對話) ：

   

已完成的專案

此教學課程專案的完整版本可在 WebView2Samples 存放 庫中取得：

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

步驟 1：安裝最新的 Visual Studio 2022

請確定已安裝Visual Studio 2022，並處於最新狀態。

若要安裝最新的 Visual Studio 2022：

1. 移至 [Visual Studio：適用於軟體開發人員和 Teams 的 IDE 和程式代碼 編輯器]，然後在 [Visual Studio 2022] 區段中，按兩下 [下載] 按鈕，然後選取 [Community 2022] 或其他版本。

2. 在 Microsoft Edge 右上方的 [ 下載 ] 彈出視窗中， VisualStudioSetup.exe 會列出 。 按兩下 [開啟檔案]。

   Visual Studio 安裝程式 會開啟。

3. 遵循提示，並接受預設值。 您將在下一個步驟中安裝或更新工作負載和工作負載的元件。

步驟 2：安裝最新的 Windows 應用程式 SDK

請確定已在Visual Studio 2022中安裝最新的 Windows 應用程式 SDK。 Windows 應用程式 SDK 包含 Visual Studio 專案範本，並包含 WebView2 SDK。 這些項目範本包括 空白應用程式、已封裝 (桌面) 項目範本中的 WinUI 3 ，其使用 WindowsAppSDK，包括 WebView2 SDK。

Windows 應用程式 SDK 會安裝為適用於 Visual Studio 之 .NET 桌面開發工作負載的 Windows 應用程式 SDK C# 範本元件。 在Visual Studio 2022 17.1版之前，Windows 應用程式 SDK 會改為安裝為Visual Studio擴充功能，如安裝 Windows 應用程式 SDK的工具中所述。

若要安裝最新的 Visual Studio 2022 最新 Windows 應用程式 SDK：

1. 在 Windows 中，按 [開始 ] 鍵，然後輸入 Visual Studio 2022。

   Visual Studio 2022 應用程式已列出。

2. 按一下 [開啟]。

   Visual Studio 2022 對話框隨即開啟，其中包含開啟 最近 開啟和 開始使用等區段。

3. 按兩下 [ 不使用程式代碼繼續]。

   Visual Studio 隨即開啟。

4. 在 [ 工具] 功能表中，選 取 [取得工具和功能]。

   Visual Studio 安裝程式 視窗隨即開啟。

5. 確定已選取 [ 工作負載] 索引標籤 。

6. 在 [ Desktop & Mobile ] 區段中，選取 [.NET 桌面開發 ] 工作負載的卡片，以顯示複選標記：

   

7. 在右側的 [安裝詳細數據] 樹狀結構中，於 [.NET 桌面開發>選擇性] 中，選取樹狀結構底部附近的 [Windows 應用程式 SDK C# 範本元件] 複選框。

8. 按兩下 [ 修改] 按鈕。

   [ 用戶帳戶控制] 對話框隨即開啟。

9. 按兩下 [ 是] 按鈕。

   系統會提示您關閉 Visual Studio。

10. 按兩下 [ 繼續 ] 按鈕 (假設您沒有未儲存的工作) 。

    Visual Studio 會下載並安裝最新的 Windows 應用程式 SDK C# 範本元件。 在 [Visual Studio 安裝程式] 視窗中，有一則訊息指出 [所有安裝都是最新狀態]，Visual Studio 2022 隨即開啟。

步驟 3：建立空白 WinUI 3 專案

接下來，建立 WinUI 3 基本 WebView2 應用程式的專案， (Windows 應用程式 SDK) 。 此傳統型應用程式將包含單一主視窗。 專案尚未包含任何 WebView2 程式代碼。

若要建立適用於 WinUI 3 的 WebView2 應用程式 (Windows 應用程式 SDK) ：

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

2. 如果 Visual Studio 2022 未執行：

   1. 在 Windows 中，按 [開始 ] 鍵，然後輸入 Visual Studio 2022。

      Visual Studio 2022 應用程式已列出。

   2. 按一下 [開啟]。

      Visual Studio 2022 啟動對話框隨即開啟，其中包含開啟 最近開 啟和 開始使用等區段。

   3. 在 [ 開始使用] 區段中，按兩下 [ 建立新的專案 ] 卡片。 [ 建立新專案] 視窗隨即開啟。

3. 在 [ 建立新專案] 視窗的 [ 搜尋範本 ] 欄位中，於 [桌面] 中輸入 WinUI 3：

   

   已在上一個主要步驟中安裝的專案範本會列出。

4. 按兩下 Desktop) 卡片中的 [空白應用程式]、[已封裝 (WinUI 3 ] 卡片，然後按兩下 [ 下一步] 按鈕。

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

5. 在 [ 專案名稱 ] 文本框中，輸入專案名稱，例如 WinUI3GetStarted：

   

6. 在 [ 位置] 文字框中，輸入或瀏覽至目錄，例如 C:\Users\myUsername\source\。

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

   專案隨即建立：

1. 如果出現對話框，指出「無法安裝 Microsoft.WindowsAppSDK 套件」，請按兩下 [ 確定] 按鈕。

步驟 4：更新或安裝 Windows 應用程式 SDK

當您在 Visual Studio 中建立新專案時，請檢查解決方案 NuGet 套件的狀態。 請確定專案範本已安裝所需的 NuGet 套件，並確定套件已更新，讓專案具有最新的功能和修正程式。

若要更新或安裝專案的最新 Windows 應用程式 SDK NuGet 套件：

1. 在 Visual Studio 的 方案總管 中，以滑鼠右鍵按兩下 WinUI3GetStarted 專案，然後選取 [管理 NuGet 套件]。

   在 Visual Studio 中， [NuGet： WinUI3GetStarted] 索 引卷標隨即開啟。 如果已使用專案範本在專案建立期間安裝 Microsoft.WindowsAppSDK 套件，則會選取 [已 安裝 ] 索引卷標，並列出該套件：

   

   如果 Microsoft.WindowsAppSDK 套件未列在 [已 安裝] 索 引標籤中：

2. 按兩下 [瀏覽] 索引標籤，然後在 [搜尋] 文字框中輸入 Microsoft.WindowsAppSDK。

3. 選 取 Microsoft.WindowsAppSDK 卡：

   

4. 按下右側的 [ 安裝 ] 按鈕。

   [ 預覽變更] 對話框隨即開啟。

5. 按兩下 [ 套用 ] 按鈕，然後接受授權條款。

   已安裝 Microsoft.WindowsAppSDK NuGet 套件。

6. 在 [NuGet - 解決方案] 索引標籤中，按兩下 [匯報] 索引卷標，然後選擇性地更新該處列出的任何套件。

7. 關閉 [NuGet - 解決方案] 索引 標籤。

步驟 5：建置並執行專案

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

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

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

若要建置並執行專案：

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

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

   [ 啟用 Windows 開發人員模式 ] 對話框可能會開啟：

   

3. 如果出現該對話框，請按兩下 開發人員的 [設定]、開啟 [ 開發人員模式 ] 切換、按兩下 [ 是 ] 按鈕，然後按兩下 [Visual Studio] 對話框的 [ 關閉 ] 按鈕。 如需開發人員模式的詳細資訊，請參閱為 Windows 建置傳統型應用程式中的啟用您的裝置以進行開發。

   專案會建置。 空白的 WinUI 桌面應用程式隨即開啟，尚未新增任何 WebView2 控制項：

   

4. 按 兩下 [按下我] 按鈕。

   按鈕標籤會變更為 [已點選]。

5. 關閉應用程式。

步驟 6：新增 WebView2 控制件

專案是以傳統型) 中已封 裝 (WinUI 3 的專案範本空白應用程式為基礎，其使用包含 WebView2 SDK 的 Microsoft.WindowsAppSDK NuGet 套件。 因此，我們可以新增 WebView2 程式代碼。 您將編輯 MainWindow.xaml 和 MainWindow.xaml.cs 檔案，以將 WebView2 控件新增至空白的 WinUI 3 應用程式專案，一開始會載入Microsoft首頁。 在 XAML 檔案中，WebView 控制項會標記如下：

<controls:WebView2 x:Name="MyWebView" Source="https://www.microsoft.com">

若要新增一開始流覽至Microsoft首頁的WebView2控件：

1. 在 Visual Studio 的 方案總管 中，按兩下 MainWindow.xaml。

   檔案會在程式代碼編輯器中開啟。

2. 在 XML 命名空間清單的結尾處，將下列屬性 <Window> 複製並貼到開始標記內：

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

   該程式代碼會新增 WebView2 XAML 命名空間。 請確定中的 MainWindow.xaml 程式代碼類似下列內容：

   <?xml version="1.0" encoding="utf-8"?>
   <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"
       xmlns:controls="using:Microsoft.UI.Xaml.Controls"
       mc:Ignorable="d">
   
       <StackPanel Orientation="Horizontal" HorizontalAlignment="Center" VerticalAlignment="Center">
           <Button x:Name="myButton" Click="myButton_Click">Click Me</Button>
       </StackPanel>
   </Window>
   

3. 刪除 <StackPanel> 專案 (三行) 。

4. 在結尾標記上方 </Window> ，貼上下列 <Grid> 元素：

   <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>
   

   此 <Grid> 元素包含 <controls:WebView2> 名為 的專案 MyWebView，其屬性 Source 會設定 WebView2 控件中顯示的初始 URI (https://www.microsoft.com) 。 當應用程式開啟時，它一開始會在 WebView2 控件中顯示 Microsoft.com 首頁。

5. 在 [方案總管 中，展開 MainWindow.xaml ，然後按兩下 MainWindow.xaml.cs。

6. 在 MainWindow.xaml.cs中，刪除 方法中的 myButton_Click 下列 C# 程式代碼列：

   myButton.Content = "Clicked";
   

   方法目前是空的。 我們稍後會將它用於網址列的 [移 至] 按鈕。

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

8. 按 [F5]****。

   專案會建置，應用程式隨即開啟：

   

   應用程式是包含 WebView2 控制件的 WebView2 主應用程式。 WebView2 控制件一開始會顯示網站 https://www.microsoft.com。 還沒有 [網址列] 文字框或 [移至 ] 按鈕。

9. 關閉應用程式。

步驟 7：新增導覽控件

若要允許使用者控制 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中，將下列 try/catch 區塊貼到 方法的主體中 myButton_Click ：

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

   當使用者按兩下 [ 移 至] 按鈕時，此程式代碼會將WebView2控件巡覽至使用者在網址列中輸入的URL，方法是重新設定 屬性的 MyWebView.Source 值，這相當於 Source 元素的 <controls:WebView2 x:Name="MyWebView"> 屬性。

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

4. 按 [F5]****。

   專案會建置，應用程式隨即開啟，一開始會顯示Microsoft首頁。 現在有 [網址列] 和 [ 移至] 按鈕。

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

   

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

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

   WebView2 控制件不會嘗試瀏覽至該 URL。 因為 URL 開頭 http:// 不是 或 https://，所以會擲回例外狀況。 在區 try 段中 addressBar.Text ，字串的開頭不是 或 http://https://，但非 URI 字串會傳遞至 Uri 建構函式，這會 System.UriFormatException 擲回例外狀況。 在 Visual Studio 中， [輸出] 窗格會顯示「擲回例外狀況：System.Private.Uri.dll 中的 'System.UriFormatException'」。 應用程式會繼續執行。

7. 關閉應用程式。

步驟 8：處理導覽事件

載入 WebView2 控制件的應用程式會接聽下列事件：

• NavigationStarting
• SourceChanged
• ContentLoading
• HistoryChanged
• NavigationCompleted

這些事件是由網頁瀏覽期間的 WebView2 控件所引發。 如果發生 HTTP 重新導向，則一個數據列中有多個 NavigationStarting 事件。 如需詳細資訊，請參閱 WebView2 應用程式的導覽事件。

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

• SourceChanged
• ContentLoading
• HistoryChanged

在本節中，您會新增程式代碼以匯入 WebView2 Core 連結庫，以處理導覽事件以移至各種類型的 URL。

若要處理導覽事件：

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

   using Microsoft.Web.WebView2.Core;
   

   註冊可取消任何非 HTTPS 要求的處理程式 NavigationStarting ：

2. 在 MainWindow.xaml.cs中的 建構函式中，新增下列 NavigationStarting 行：

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

   該行會 EnsureHttps 將方法註冊 (在下方新增) 做為事件的 NavigationStarting 接聽程式。

3. 在建構函式下方，新增下列 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. 在應用程式的網址列中，輸入沒有前置詞的字串，例如 bing.com，然後按下 [ 移至] 按鈕。

   應用程式不會流覽至該頁面。 如 UriFormatException 同先前一樣，會擲回例外狀況，並出現在Visual Studio的 [ 輸出 ] 窗格中。

9. 關閉應用程式。

步驟 9：插入 JavaScript 以警示使用者非 HTTPS 位址

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

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

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

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

若要在使用者嘗試瀏覽至非 HTTPS 網站時顯示警示：

1. 在 MainWindow.xaml.cs的 方法中 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 (Windows 應用程式 SDK) 應用程式！

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

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。