在 WinForms 應用程式中開始使用 WebView2

發行項
03/14/2024

本教學課程可協助您：

設定您的開發工具。
使用 C# Windows Forms App (.NET Framework) Visual Studio 專案範本來建立 WinForms 專案。
安裝 WinForms 專案的 Microsoft.Web.WebView2 SDK 套件。
一路瞭解 WebView2 概念。

步驟 1 - 選擇性複製或下載 WebView2Samples 存放庫

執行下列其中一項：

使用下列各節中的步驟，從專案範本開始，在Visual Studio中建立新專案。這會提供您最新的程式代碼和項目結構。
複製或下載 WebView2Samples 存放庫、在 Visual Studio 中開啟已完成的專案，並遵循本文中的步驟來瞭解如何建立 WinForms 專案，並瞭解新增的 WebView2 程式代碼。請參閱為 WebView2 設定開發環境中的下載 WebView2Samples 存放庫。此教學課程專案的完整版本可在 WebView2Samples 存放庫目錄 WinForms_GettingStarted中取得。
- 範例名稱： Win32_GettingStarted
- 存放庫目錄： Win32_GettingStarted
- 解決方案檔： WebView2GettingStarted.sln

存放庫中的範例可能不像您使用最新的 Visual Studio 專案範本建立的項目一樣是最新的。

步驟 2 - 安裝 Visual Studio

需要 Microsoft Visual Studio。本教學課程不支援 Microsoft Visual Studio Code。

如果尚未安裝 Visual Studio，請在新的視窗或索引標籤中開啟頁面 Microsoft Visual Studio ，然後安裝 Visual Studio 2017 或更新版本，例如 Visual Studio 2022 Professional。

然後返回這裏，然後繼續下方。

步驟 3 - 建立單一視窗應用程式

從包含單一主視窗的基本桌面項目開始。

開啟 Visual Studio。
選 取 [檔案>] [新增>專案]。

[Visual Studio 開啟最近開啟] 視窗隨即出現：
在右側，按兩下 [ 建立新的專案 ] 卡片。 Visual Studio [建立新專案] 視窗隨即開啟。
在 [ 搜尋] 文字框中，貼上或開始輸入下列內容：
```
C# Windows Forms App (.NET Framework)
```
搜尋結果隨即出現，並列出項目類型。
選取 C# Windows Forms 應用程式 (.NET Framework) 卡片。請確定名稱相符，並使用 C# 圖示，然後應用程式 Windows Forms 名稱 (.NET Framework) 。然後按下 一步： 按鈕：
在 [ 項目名稱 ] 文字框中，輸入專案名稱。本教學課程文章使用名稱 WinForms_GettingStarted，例如已完成專案的存放庫目錄名稱。
在 [ 位置 ] 文本框中，輸入路徑，例如 “C：\Users\username\Documents\MyWebView2Projects”。
在 [架構] 下拉式清單中，選取 [.NET Framework 4.7.2 或更新版本，例如 .NET Framework 4.8：
按兩下 [ 建立] 按鈕。

Visual Studio 視窗隨即開啟，顯示方案總管中的基準 WinForms 專案，並顯示表單 Designer 視窗：
選取 [檔案全部儲存> (Ctrl+Shift+S) 。
選 取 [偵錯>開始偵 錯] (F5) 。

從全新的 WinForms 專案中，會開啟空白的 Form1 視窗：
關閉 [ Form1] 視窗。

您現在有執行的空白 WinForms 專案。接下來，設定專案以新增 WebView2 內容。

步驟 4 - 安裝 WebView2 SDK

針對每個 WebView2 專案，您可以使用 Visual Studio 中的 NuGet 套件管理員，將 WebView2 SDK 新增至專案。您會安裝 Microsoft.Web.WebView2 SDK NuGet 套件，以供目前的專案使用。

使用 NuGet 將 WebView2 SDK 新增至專案，如下所示：

在 方案總管 中，以滑鼠右鍵按兩下專案名稱， (非其上方的方案名稱) ，然後選取 [管理 NuGet 套件]：

NuGet 套件管理員會在 Visual Studio 中開啟。
按兩下左上方的 [ 瀏覽 ] 索引標籤。
清除 [ 包含發行前版本] 複 選框。
在搜尋列中，輸入 WebView2，然後在搜尋列下方按兩下 [Microsoft.Web.WebView2 ] 加以選取：

若要縮放，請以滑鼠右鍵按兩下 > [在新索引卷標中開啟影像]。
按兩下 [ 安裝 (] 或 [ 更新) ] 按鈕。 [ 預覽變更 ] 對話框隨即開啟：
按兩下 [ 確定] 按鈕。
選 取 [檔案>全部儲存 (Ctrl+Shift+S) 以儲存專案。
關閉 [NuGet 套件管理員] 視窗。
選 取 [偵錯>開始偵 錯] (F5) 來建置和執行專案。

執行中的項目會顯示與之前相同的空白視窗：
關閉 [ Form1] 視窗。

您已將 WebView2 SDK 新增至專案，但尚未將任何 WebView2 程式代碼新增至專案。

步驟 5 - 建立單一 WebView2 控件

現在已針對 WinForms 專案安裝 WebView2 SDK，請將 WebView2 控制項新增至應用程式，如下所示：

入門項目已經有表單，但我們會將另一個 Form1.cs 新增為 Form2.cs，以瞭解如何執行這項操作。

選取 [專案>][新增表單 (Windows Forms) ] 。
在 [新增專案] 視窗的左側，選取 [Visual C# 專案>Windows Forms] 。
在右側，選取 [窗體 (Windows Forms) ]，然後按兩下 [新增] 按鈕：

項目現在有一個額外的表單，其檔名Form2.cs會顯示在表單 Designer 和方案總管：
按兩下 [Form1] 畫布。我們不會使用 Form2。
選 取 [檢視>工具箱]。

以下是您將 WebView2 特定內容新增至應用程式的位置：
在 [工具箱] 中，按兩下 [WebView2 Windows Forms 控件] 展開選項。

在 Visual Studio 2017 中，預設不會在 [工具箱] 中顯示 WebView2。若要讓 WebView2 顯示在 [ 工具箱] 中，請選取 [ 工具>選項>一般> ]，並將 [ 自動填入工具箱 ] 設定設為 [True]。
在 [工具箱] 中，按兩下或拖曳 WebView2 控制件到您新增之控件的 [表單 Designer 畫布，例如 Form2.cs：
拖曳 WebView2 控件的側邊，使其幾乎填滿所有的畫布。
請確定已選取表單上的新 WebView2 控制件。在 [ 屬性] 面板的 [ 設計 ] 區段中，將 [ (名稱) ] 屬性設定為 webView (小寫 'w'，大寫 'V'，沒有數位後綴) 。控件一開始可能會命名為其他名稱，例如 webView21。視需要使用 [分類 ] 和 [ 依字母 順序排序] 選項按鈕來尋找屬性：
在 [ 屬性] 面板的 [ Misc] 區 段中，將 Source 屬性設定為 https://www.microsoft.com。 Source 屬性會設定將顯示在 WebView2 控制件中的初始 URL。
選 取 [檔案>全部儲存 (Ctrl+Shift+S) 以儲存專案。
按 F5 以組建及執行專案。

如果按下 Alt+Tab 以切換至視窗，WebView2 控件會在 Windows Forms 窗體的 WebView2 控制件中顯示來自的內容https://www.microsoft.com，並具有 [跳至主要內容] 連結：
如有需要，請按兩下 [跳至主要內容] 連結。

WebView2 控制件會在 WebView2 控制件中以 Windows Forms 形式顯示的內容https://www.microsoft.com：
關閉 [ Form1] 視窗。

如果您正在使用高解析度監視器，您可能需要設定 Windows Forms 應用程式以獲得高 DPI 支援。

步驟 6 - 新增控件和處理視窗調整事件大小

從工具箱將更多控件新增至 Windows Forms 窗體，然後處理視窗重設大小事件，如下所示。

選 取 [檢視>工具箱]，或按下左側的 [ 工具箱 ] 索引標籤。
在 [ 工具箱] 中，按兩下 [ 通用控制件]。

新增文字框控件，如下所示：
將 TextBox 控制件拖曳到Form1.cs窗體 Designer 畫布上。
請確定 TextBox 控制件具有焦點。
在 [ 屬性] 面板的 [ 設計 ] 區段中，將 [ (名稱]) (從 textBox1) 變更為 addressBar。

新增按鈕控件，如下所示：
將按鈕控件拖曳到Form1.cs窗體 Designer 畫布上。
請確定按鈕控制件具有焦點。

在 [ 屬性] 面板的 [粗體外觀 ] 區段中， (向下) 約 15 個屬性，將 Text 屬性 (可能從 button1 變更) 為 Go！

對齊文本框和現有的按鈕，如下所示：
將文字框放在表單的左側，垂直對齊按鈕，如下所示：
調整文字框的大小，如下所示：
點選 「檢視>程式代碼 」以開啟 Form1.cs。

定義 Form_Resize 以在調整應用程式視窗大致時保留控件，如下所示。

刪除下列程式代碼：

   public Form1()
{
   InitializeComponent();
}

將此程式代碼貼到相同位置：

public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);
}

private void Form_Resize(object sender, EventArgs e)
{
   webView.Size = this.ClientSize - new System.Drawing.Size(webView.Location);
   goButton.Left = this.ClientSize.Width - goButton.Width;
   addressBar.Width = goButton.Left - addressBar.Left;
}

已新增Form_Resize程序代碼

選 取 [檔案>全部儲存 (Ctrl+Shift+S) 以儲存專案。
按 F5 以組建及執行專案。

[Form1] 視窗隨即出現，其中顯示來自 https://www.microsoft.com的網頁內容：

如果您按 Alt+Tab 以切換至 Form1 視窗，您可能需要按兩下 [ 跳至新增的主要內容 ] 連結。
使用滑鼠滾輪向上和向下捲動視窗。輸入控件會保持就地。
拖曳視窗的角落以調整其大小。文字框會變更寬度。
關閉 [ Form1] 視窗。

讓用戶藉由讀取文本框中輸入的文字來變更 WebView2 控件顯示的 URL，以做為網址列。

選 取 [檢視>程序代碼 ]， Form1.cs 以便在程式代碼編輯器中開啟。
在 Form1.cs中， CoreWebView2 將下列程式代碼插入檔案頂端作為第 1 行，以新增命名空間：
```
using Microsoft.Web.WebView2.Core;
```
選 取 [Form1.cs [設計] 索引標籤，然後按兩下 Go! 按鈕。方法 goButton_Click 會加入檔案中 Form1.cs 。
將下列程式代碼貼到檔案中以取代空白 goButton_Click 方法，讓方法主體如下所示：
```
private void goButton_Click(object sender, EventArgs e)
{
   if (webView != null && webView.CoreWebView2 != null)
   {
      webView.CoreWebView2.Navigate(addressBar.Text);
   }
}
```
現在函式 goButton_Click 會將 WebView2 控制件巡覽至網址列文字框中輸入的 URL。
選 取 [檔案>全部儲存 (Ctrl+Shift+S) 以儲存專案。
按 F5 以組建及執行專案。
在網址列中，輸入開頭為 https的 URL，例如 https://www.bing.com，然後按下 [ 執行！] 按鈕：

WebView2 控件會顯示 URL 的網頁內容。
在網址列中，輸入不是以 http開頭的字串，例如 www.bing.com，然後按兩下 [ 執行！] 按鈕。

如果 URL 開頭http://https://不是或，ArgumentException則會擲回。
選 取 [偵錯>停止偵錯]，或按兩下 [ 繼續]。 [Form1] 視窗隨即關閉。

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

NavigationStarting
SourceChanged
ContentLoading
HistoryChanged
NavigationCompleted

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

導覽事件

發生錯誤時，會引發下列事件，而且可能取決於流覽至錯誤網頁：

SourceChanged
ContentLoading
HistoryChanged

注意事項

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

若要示範如何使用事件，請先註冊的處理程式 NavigationStarting ，以取消任何未使用 HTTPS 的要求。

在 Form1.cs中 Form1() ，更新建構函式以符合下列程式代碼，同時在建構函式下方新增 EnsureHttps(sender, args) 函式，如下所示：

public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);

   webView.NavigationStarting += EnsureHttps;
}

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

在建構函式中， EnsureHttps 會註冊為 WebView2 控件上 NavigationStarting 事件的事件處理程式。

選 取 [檔案>全部儲存 (Ctrl+Shift+S) 以儲存專案。
按 F5 以組建及執行專案。
在網址列中，輸入以 https開頭的 URL，例如 https://www.bing.com，然後按兩下 [ 執行！] 按鈕。

HTTPs URL 會載入;Web 內容會從預設的 Microsoft.com 變更為 Bing.com。
在網址列中，輸入以 http開頭的 URL，例如 http://www.microsoft.com，然後按兩下 [ 執行！] 按鈕。

不會載入 HTTP URL;Bing.com 頁仍會顯示。相反地，輸入 http://www.microsoft.com Microsoft Edge 會正常運作;它會重新導向至 HTTPs 網站以進行 Microsoft.com。
在網址列中，輸入以 https開頭的 URL，例如 https://www.microsoft.com，然後按兩下 [ 執行！] 按鈕。

HTTPs URL 會載入;Microsoft.com 網頁現在會出現，因為您已在『HTTP』之後新增『s』。

步驟 9 - 腳本

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

在建立全域對象之後，執行插入的 JavaScript。
在執行 HTML 檔中包含的任何其他腳本之前，執行插入的 JavaScript。

例如，新增腳本，以在用戶流覽至非 HTTPS 網站時傳送警示，如下所示：

變更函式 EnsureHttps 以新增下列包含 ExecuteScriptAsync的行：

void EnsureHttps(object sender, CoreWebView2NavigationStartingEventArgs args)
{
   String uri = args.Uri;
   if (!uri.StartsWith("https://"))
   {
      webView.CoreWebView2.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
      args.Cancel = true;
   }
}

新增的行會將腳本插入使用 ExecuteScriptAsync 方法的 Web 內容中。新增的文稿為：

alert('{uri} is not safe, try an https link')

選 取 [檔案>全部儲存 (Ctrl+Shift+S) 以儲存專案。
按 F5 以組建及執行專案。
請嘗試使用移至 http://www.bing.com (http ，而不是 https 前置詞) 。

應用程式會顯示警示：

步驟 10 - 主機與 Web 內容之間的通訊

主機和 Web 內容可用 postMessage 來彼此通訊，如下所示：

WebView2 控制件中的 Web 內容可用 window.chrome.webview.postMessage 來將訊息張貼到主機。主機會使用主機上任何已註冊 WebMessageReceived 的來處理訊息。
主機使用 CoreWebView2.PostWebMessageAsString 或 CoreWebView2.PostWebMessageAsJSON，將訊息張貼至 WebView2 控制件中的 Web 內容。新增至的處理程式會攔截這些 window.chrome.webview.addEventListener訊息。

通訊機制會使用原生功能，將來自 Web 內容的訊息傳遞至主機。

在您的專案中，當 WebView2 控制件流覽至 URL 時，它會在網址列中顯示 URL，並警示使用者 WebView2 控件中顯示的 URL。

在 Form1.cs中，更新建構函式， Form1() 並在其下方建立 InitializeAsync() 符合下列程式代碼的函式：
```
public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);
   webView.NavigationStarting += EnsureHttps;
   InitializeAsync();
}

async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
}
```
函 InitializeAsync 式會等候 EnsureCoreWebView2Async，因為的 CoreWebView2 初始化是異步的。

接下來，註冊事件處理程式以回應 WebMessageReceived。初始化之後 CoreWebView2 ，將會註冊此事件處理程式。
在 Form1.cs中，更新 InitializeAsync，並在其下方新增 UpdateAddressBar ，如下所示：
```
async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
   webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;
}

void UpdateAddressBar(object sender, CoreWebView2WebMessageReceivedEventArgs args)
{
   String uri = args.TryGetWebMessageAsString();
   addressBar.Text = uri;
   webView.CoreWebView2.PostWebMessageAsString(uri);
}
```
接下來，若要讓 WebView2 傳送和回應 Web 訊息，在初始化之後 CoreWebView2 ，主機會在 Web 內容中插入腳本，以執行下列動作：
- 使用 postMessage將 URL 傳送至主機。
- 註冊事件處理程式，以在顯示網頁內容之前，於警示方塊中顯示從主機傳送的訊息。

在 Form1.cs中，更新 InitializeAsync 以符合下列程序代碼：

async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
   webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;

   await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.postMessage(window.document.URL);");
   await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.addEventListener(\'message\', event => alert(event.data));");
}

選取 [檔案全部儲存> (Ctrl+Shift+S) 以儲存變更。
按 F5 以組建及執行專案。
輸入網址，例如 https://www.bing.com：

一開始會出現警示，顯示從主機網站傳送的結果 URL。
按兩下 [ 確定] 按鈕。

WebView2 控件現在會在網址列中顯示新的 URL，而來自 URL 的網頁內容會顯示在 WinForms 視窗的 WebView2 控制件中：
- 當應用程式啟動時，預設 URL 為 https://www.microsoft.com，而產生的顯示位址會顯示地區設定，例如 https://www.microsoft.com/en-us/。
- 如果您輸入 https://www.bing.com，產生的位址會是變體，例如 https://www4.bing.com/?form=DCDN。

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

散發 WebView2 應用程式

如果您要散發本教學課程所產生的應用程式，則必須與應用程式一起散發 WebView2 運行時間。然後 WebView2 執行時間會自動安裝到用戶電腦上。如需詳細資訊，請參閱散發您的應用程式和 WebView2 運行時間。

另請參閱

散發您的應用程式和 WebView2 執行時間
WinForms 範例應用程式 - 示範比目前教學課程更多的 WebView2 API。
WebView2 API 參考