開始使用 Win32 應用程式中的 WebView2

本文是為了學習如何撰寫你自己的 WebView2 程式碼。如果你想先跑範例，可以參考 Win32 範例應用程式或其他範例應用程式文章。

在本文中，你會設定開發工具 (如果還沒) ，學習如何在 Win32 應用程式專案中加入 WebView2 程式碼，並在此過程中學習 WebView2 的概念。

這個教學從開啟一個已加入 WebView2 程式碼的 Win32 應用程式專案開始。專案使用了 repo 裡WebView2Samples的 Win32_GettingStarted (WebView2GettingStarted.sln) 目錄。要使用這篇文章，請執行以下步驟：

複製或下載 WebView2Samples 倉庫到本地硬碟。
執行完成的專案。
可以選擇刪除 WebView2 的程式碼 HelloWebView.cpp ，以恢復 Win32 的基準應用程式。
請依照本文剩餘步驟說明如何新增並理解 WebView2 程式碼。

這個教學從已完成的專案開始，該專案已經加入了 WebView2 程式碼。 (這個教學不需要你建立新專案;你不會在 Visual Studio 裡用專案範本建立新專案，然後再加入 WebView2 程式碼。)

完成的專案

完成的教學專案可在 WebView2Samples 倉庫中找到：

範例名稱： Win32_GettingStarted
倉庫目錄： Win32_GettingStarted
解答檔案： WebView2GettingStarted.sln

步驟 1 - 安裝 Visual Studio

此教學需要使用 Microsoft Visual Studio，而非 Microsoft Visual Studio Code。

如果 Microsoft Visual Studio 尚未安裝，請在新視窗或分頁中查看「安裝 Visual Studio 」中的 「設置你的 WebView2 開發環境」。照著那裡的步驟做基本的預設安裝 Visual Studio。

然後回到此頁繼續往下看。

步驟 2 - 複製或下載 WebView2Samples 倉庫

你在這教學步驟中加入的程式碼，已經被加入範例倉庫中，為你提供。以下有個可選步驟，可以讓你刪除 WebView2 的程式碼 HelloWebView.cpp，這樣你也可以自己加入。

為了讓這個教學聚焦於 WebView2 專屬的程式設計，我們從 WebView2Samples GitHub 倉庫中現有的 Microsoft Visual Studio 專案 () WebView2GettingStarted 開始。我們會新增 WebView2 的功能——其實功能已經加入，但請跟著設定和說明步驟操作。

我們將先從現有的 Visual Studio 專案開始，是標準 C++ Win32 桌面應用程式的範例程式碼之一。關於基礎的標準 Win32 應用程式範例，請在新視窗或分頁中閱讀「攻略：建立傳統 Windows 桌面應用程式 (C++) 」。

複製或下載 WebView2Samples 倉庫，方法如下：

如果你還沒做，可以複製 (或) WebView2Samples 倉庫下載。要做到這點，請在另一個視窗或分頁中，依照 Clone the WebView2Samples repo (或在 Download the WebView2Samples repo) 中的「 Set your Dev environment for WebView22」中的步驟操作。

接著繼續以下步驟。

步驟三 - 打開完成的溶液 (WebView2GettingStarted.sln)

你從一個包含單一主視窗的基本桌面專案開始。我們將從 WebView2Samples 倉庫中一個現有的應用程式專案開始，該專案是你在前一步從 GitHub 複製或下載的。

開啟 Visual Studio (Visual Studio Code) 。
開 WebView2GettingStarted.sln，位於路徑處： <your repo directory>/WebView2Samples/GettingStartedGuides/Win32_GettingStarted/WebView2GettingStarted.sln。

步驟 4 - 如果有提示就安裝工作負載

Visual Studio 安裝程式可能會開啟並提示你安裝一個工作負載：

Visual Studio 安裝程式提示安裝「Desktop Development with C++」工作負載

如果 Visual Studio 安裝程式提示你安裝工作負載：

選擇 桌面開發卡與 C++ 卡，這樣才會勾選一個勾選。
如果你願意，也可以選擇 .NET 桌面開發 卡 (這個教學) 不需要，這樣這張卡上也會有勾選標記。
點擊安裝按鈕。

安裝商關閉。

再目標專案

可能會跳出 Visual Studio 檢視解決方案行動 的對話框，提示你是否要 重新定向專案：

Visual Studio 的「檢視解決方案動作」對話框，提示重新投放專案

如果出現那個對話框，你可以點擊確定。

WebView2GettingStarted 解決方案會在 Visual Studio 中開啟。解決方案包含一個專案： WebView2GettingStarted，該專案包含一個.cpp檔案： HelloWebView.cpp。

步驟 5 - 在 Visual Studio 中查看已開啟的專案

如果 WebView2GettingStarted 專案在 Visual Studio 中沒有開啟，請在 Visual Studio 中開啟：

開 WebView2GettingStarted.sln，位於路徑處： <your repo directory>/WebView2Samples/GettingStartedGuides/Win32_GettingStarted/WebView2GettingStarted.sln。
在方案總管中，展開「來源檔案」節點，然後選擇HelloWebView.cpp。

HelloWebView.cpp 在 Visual Studio 的程式碼編輯器中開啟。

上面的截圖顯示了一些 WebView2 (#include "WebView2.h") 程式碼，這些程式碼在複製 (下載後) 檔案中就已經存在了。

設定解決方案使用 Win10 SDK 和 Visual Studio 工具組

這個步驟只適用於舊版 Visual Studio，所以你大概可以跳過。不過你還是可以看看這個介面：

在 Visual Studio 的方案總管中，右鍵點擊 WebView2GettingStarted專案， (非同名解決方案，) ，然後選擇屬性。
選擇「 配置屬性>一般」，然後 (如果設定不正確) ：
1. 修改 Windows SDK 版本以使用 Win10 SDK。
2. 修改 平台工具組 以使用 Visual Studio 工具組。
這些修改僅適用於較舊版本的 Visual Studio。

這是一張 Visual Studio 2017 的截圖，顯示了一些有效的設定：

以下是一張 Visual Studio 2022 的截圖;數值本身就正確，因此不需要更改：

請繼續以下步驟。

步驟 6 - 建立並執行倉庫完成的專案

此時，你的開發環境已設定為在 Visual Studio 中以除錯模式執行 Win32 WebView2 應用程式，並加入 WebView2 功能。

為了確認你的系統已設定為 WebView2 編碼，請以除錯模式執行專案，如下：

選擇除錯>開始除錯 (F5) 以建立並執行專案。

範例應用程式首先會打開一個彈出視窗，顯示將載入的網址，並附帶 一個確定 按鈕：
點擊確定按鈕關閉彈出視窗，繼續查看網址：

WebView2 視窗現在顯示網頁內容：Bing 網站。 http://www.bing.com
關閉 WebView 範例 視窗。

步驟7 - 更新或安裝 Windows 實作函式庫 (WIL)

WIL 已經安裝在專案的倉庫裡，但請先走以下步驟，了解設定流程並檢查專案設定狀況。

馬上，你將安裝 Windows 實作函式庫 (WIL) ——一個僅標頭的 C++ 函式庫，透過可讀且型別安全的 C++ 介面，讓 Windows 上的開發者更輕鬆地使用。你透過 Visual Studio 的方案總管安裝這個 Microsoft.Windows.ImplementationLibrary 套件，用於專案。

本教學也使用 Windows 執行階段 C++ 模板庫 (WRL) ——一個提供低階方式撰寫與使用Windows 執行階段元件的範本庫。

從 Visual Studio 內安裝 Windows 實作函式庫 (WIL) ，如下：

在 Visual Studio 中，請確保 WebView2GettingStarted 解決方案仍然開啟著。
在 方案總管 中，右鍵點擊 WebView2GettingStarted 專案節點 (非解決方案節點) ，然後選擇管理 NuGet 套件。
在 NuGet 視窗中，點 選瀏覽標籤 。
在左上角的搜尋欄輸入 Microsoft.Windows.ImplementationLibrary。或者，複製貼上下面的單行程式碼區塊。然後選擇 Microsoft.Windows.ImplementationLibrary。
```
Microsoft.Windows.ImplementationLibrary
```
在 Visual Studio 的 NuGet 套件管理器中選擇 Microsoft.Windows.ImplementationLibrary 套件：

要放大，請右鍵點擊>「在新分頁開啟圖片」。

如果你沒看到 Microsoft.Windows.ImplementationLibrary 這個欄位，請檢查 NuGet 的來源位置，如下：
1. 選擇工具>選項>NuGet 套件管理器>套件來源。
2. 確保在 Package 來源中有一個指向 https://api.nuget.org/v3/index.jsonnuget.com 的來源。
3. 如果 Package source 沒有包含該來源，請nuget.com輸入名稱文字框和https://api.nuget.org/v3/index.json來源文字框。然後點 「更新 」並 「確定」。
在右上角，點擊安裝按鈕 (或更新按鈕) 。 NuGet 會下載 Windows 實作函式庫 (WIL) 到你的電腦。

Windows 實作函式庫 (WIL) 現已安裝，並Windows 執行階段 C++ 範本函式庫 (WRL) 。

請繼續以下步驟。

步驟 8 - 更新或安裝 WebView2 SDK

倉庫中完成的專案已經安裝了 WebView2 SDK 版本。如果你從零開始用 Win32 專案範本建立專案，你需要安裝專案的 WebView SDK 套件，就像這裡描述的那樣。

接著，更新 (或安裝) WebView2 SDK。 WebView2 SDK 包含由 Microsoft Edge 驅動的 WebView2 控制項，讓您能將 HTML、CSS 和 JavaScript) (網頁技術嵌入原生應用程式中。

更新 (或安裝) WebView2 SDK，具體如下：

在 Visual Studio 中，請確保 WebView2GettingStarted 解決方案如上所述是開啟的。
在方案總管中，右鍵點擊 WebView2GettingStarted 專案節點 (非 WebView2GettingStarted 解決方案節點) ，然後選擇管理 NuGet 套件。

NuGet 套件管理器的分頁和面板會在 Visual Studio 中開啟。
如果 WebView2 SDK 已經安裝在專案中，就像倉庫專案一樣，在 NuGet 視窗中點選 「已安裝 」標籤或 「更新 」標籤。
或者，如果你正在新專案中安裝 WebView2 SDK，請點擊「瀏覽」標籤。
在搜尋列右側，除非你確定想要 SDK) 的預釋版本，否則 (勾選包含 預釋版 。
在左上角的搜尋欄輸入 Microsoft.Web.WebView2。或者，複製貼上下面的單行程式碼區塊。然後選擇 Microsoft.Web.WebView2。
```
Microsoft.Web.WebView2
```
在右側視窗，點擊 「更新 (」或 「安裝) 」。 NuGet 會把 WebView2 SDK 下載到你的電腦。
關閉 NuGet 套件管理器 分頁。

WebView2 SDK 現在已經更新或安裝，因此你的開發環境已經準備好，可以為你的 Win32 應用程式新增 WebView2 的功能。

請繼續以下步驟。

步驟 9 - 可選擇性地從 HelloWebView.cpp 刪除 WebView2 程式碼

如果你想依照以下步驟將 WebView2 程式碼 HelloWebView.cpp 加入自己，請刪除 WebView2 程式碼的兩個區塊，如下：

在 HelloWebView.cpp中，刪除以下程式碼：

// include WebView2 header
#include "WebView2.h"

在 HelloWebView.cpp中，刪除這兩行註解行之間的程式碼，但保留這兩行註解：
```
// <-- WebView2 sample code starts here -->
...
// <-- WebView2 sample code ends here -->
```

步驟 10 - 在 HelloWebView.cpp 中加入 WebView2.h 標頭

上面，我們做了以下幾件事：

複製或下載了範例庫，包括包含標準 C++ Windows 桌面應用程式的現有專案。
更新或安裝 Windows 實作函式庫 (WIL) 。
更新或安裝 WebView2 SDK，以加入 WebView2 的功能。
可選擇性地從 . 中刪除 WebView2 程式碼。HelloWebView.cpp

接著，為應用程式新增 WebView2 功能，如下：

在 Visual Studio 裡，請確保 WebView2GettingStarted 解決方案是開啟的。
在方案總管中，展開「原始檔案」，然後點選 HelloWebView.cpp。
如果以下程式碼尚未出現，請在最後一#include行後貼上以下程式碼HelloWebView.cpp：
```
// include WebView2 header
#include "WebView2.h"
```
請確保該 include 區塊看起來像以下內容：
```
...
#include <wrl.h>
#include <wil/com.h>
// include WebView2 header
#include "WebView2.h"
```
請注意所使用的標頭：
- wrl.h- Windows 執行階段 C++ 模板庫 (WRL) - 一個提供低階方式撰寫與使用Windows 執行階段元件的範本函式庫。
- wil/com.h - Windows 實作函式庫 (WIL) - 一個僅標頭的 C++ 函式庫，透過可讀且型別安全的 C++ 介面，讓 Windows 開發者更輕鬆地使用常見 Windows 編碼模式。
- WebView2.h - WebView2 控制項由 Microsoft Edge 驅動，讓您能將 HTML、CSS 和 JavaScript (網頁技術嵌入原生應用程式) 中。
選擇>檔案「全部儲存」 (Ctrl+Shift+S) 來儲存專案。

原始碼檔案和專案已準備好使用並針對 WebView2 API 建置。

請繼續以下步驟。

步驟 11 - 建立你的空白範例應用程式

選擇除錯>開始除錯 (F5) 以建立並執行專案。

範例應用程式會打開並顯示一個空白視窗：

你現在有一個運行中的空 Win32 桌面應用程式，並具備潛在的 WebView2 功能。
關閉 WebView 範例 應用程式視窗。

請繼續以下步驟。

步驟 12 - 在父視窗新增 WebView2 控制項

接著，在主視窗新增一個 WebView2 控制項。

你會用這個 CreateCoreWebView2Environment 方法來設定環境，並找到驅動控制的 Microsoft Edge 瀏覽器。

請注意，如果你想覆蓋以下預設值，可以改用該方法的「with options」版本： CreateCoreWebView2EnvironmentWithOptions

瀏覽器位置
使用者資料資料夾
瀏覽器標誌

完成 CreateCoreWebView2Environment 這個方法後，你將：

在回調中ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler執行該ICoreWebView2Environment::CreateCoreWebView2Controller方法。
執行 ICoreWebView2Controller::get_CoreWebView2 該方法以取得相關的 WebView2 控制項。

現在要做上述操作，在回調時你會：

再設定幾個設定。
調整 WebView2 控制項大小，填滿父視窗的 100%。
接著在 Win32 應用程式的 WebView2 控制項中顯示 Bing.com 網站。

在 HelloWebView.cpp中，定位以下編碼：

   UpdateWindow(hWnd);

   // <-- WebView2 sample code starts here -->

如果以下程式碼尚未存在，請將以下程式碼貼入 HelloWebView.cpp。將程式碼貼在行 // <-- WebView2 sample code starts here --> 間，然後 // <-- WebView2 sample code ends here -->：

// Step 3 - Create a single WebView within the parent window
// Locate the browser and set up the environment for WebView
CreateCoreWebView2EnvironmentWithOptions(nullptr, nullptr, nullptr,
   Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
      [hWnd](HRESULT result, ICoreWebView2Environment* env) -> HRESULT {

         // Create a CoreWebView2Controller and get the associated CoreWebView2 whose parent is the main window hWnd
         env->CreateCoreWebView2Controller(hWnd, Callback<ICoreWebView2CreateCoreWebView2ControllerCompletedHandler>(
            [hWnd](HRESULT result, ICoreWebView2Controller* controller) -> HRESULT {
               if (controller != nullptr) {
                  webviewController = controller;
                  webviewController->get_CoreWebView2(&webview);
               }

               // Add a few settings for the webview
               // The demo step is redundant since the values are the default settings
               wil::com_ptr<ICoreWebView2Settings> settings;
               webview->get_Settings(&settings);
               settings->put_IsScriptEnabled(TRUE);
               settings->put_AreDefaultScriptDialogsEnabled(TRUE);
               settings->put_IsWebMessageEnabled(TRUE);

               // Resize WebView to fit the bounds of the parent window
               RECT bounds;
               GetClientRect(hWnd, &bounds);
               webviewController->put_Bounds(bounds);

               // Schedule an async task to navigate to Bing
               webview->Navigate(L"https://www.bing.com/");

               // Step 4 - Navigation events

               // Step 5 - Scripting

               // Step 6 - Communication between host and web content

               return S_OK;
            }).Get());
         return S_OK;
      }).Get());

選擇>檔案「全部儲存」 (Ctrl+Shift+S) 來儲存專案。

打造你的 Bing 範例應用程式

按 F5 以組建及執行專案。

如果你一開始就刪除了所有 WebView2 程式碼，現在你就有一個 Win32 視窗，裡面充滿了 WebView2 控制項，裡面充滿了網頁內容：
關閉 WebView 範例 應用程式視窗。

或者，如果你保留了所有 WebView2 程式碼，這時 Bing 會跳出一個視窗，裡面有 Bing 的警報對話框，視窗是空的。點擊確定按鈕關閉必應對話框。現在 WebView2 控制權由 Bing 頁面內容填滿：
如果 WebView 範例 應用程式視窗開啟，請關閉它。

請繼續以下步驟。

在前一步，我們討論了如何透過 Method ICoreWebView2::Navigate 來導航到 URL。導航時，WebView2 會觸發一連串事件，主持人可以聆聽：

NavigationStarting
SourceChanged
ContentLoading
HistoryChanged
NavigationCompleted

如果你現在想了解更多資訊，請在新視窗或分頁中查看 WebView2 應用程式的導航事件。

導航活動

在錯誤情況下，根據導覽是否繼續到錯誤網頁，可能會發生以下一項或多項事件：

SourceChanged
ContentLoading
HistoryChanged

如果發生 HTTP 重定向，會連續出現多個 NavigationStarting 事件。

以使用導航事件為例，註冊一個處理程序來 NavigationStarting 取消任何非 https (不安全的) 請求，具體如下。

如果還沒有，請將以下程式碼貼到 HelloWebView.cpp步驟 3 下方：

// Step 4 - Navigation events
// register an ICoreWebView2NavigationStartingEventHandler to cancel any non-https navigation
EventRegistrationToken token;
webview->add_NavigationStarting(Callback<ICoreWebView2NavigationStartingEventHandler>(
    [](ICoreWebView2* webview, ICoreWebView2NavigationStartingEventArgs* args) -> HRESULT {
        wil::unique_cotaskmem_string uri;
        args->get_Uri(&uri);
        std::wstring source(uri.get());
        if (source.substr(0, 5) != L"https") {
            args->put_Cancel(true);
        }
        return S_OK;
    }).Get(), &token);

現在這個應用程式不會開啟任何非 https 網站。你也可以用類似的機制來完成其他任務，例如限制導航只能在自己的領域內。

請繼續以下步驟。

步驟 14 - 腳本編寫

使用主機應用程式在執行時將 JavaScript 程式碼注入 WebView2 控制項。你可以指派 WebView2 執行任意的 JavaScript 或新增初始化腳本。注入的 JavaScript 會應用於所有新的頂層文件及子框架，直到 JavaScript 被移除為止。

注入的 JavaScript 會以特定時間執行：

在建立全域物件後執行。
在執行 HTML 文件中其他腳本之前，先執行它。

如果以下程式碼尚未存在，請將以下程式碼貼上至 HelloWebView.cpp：

// Step 5 - Scripting
// Schedule an async task to add initialization script that freezes the Object object
webview->AddScriptToExecuteOnDocumentCreated(L"Object.freeze(Object);", nullptr);
// Schedule an async task to get the document URL
webview->ExecuteScript(L"window.document.URL;", Callback<ICoreWebView2ExecuteScriptCompletedHandler>(
    [](HRESULT errorCode, LPCWSTR resultObjectAsJson) -> HRESULT {
        LPCWSTR URL = resultObjectAsJson;
        //doSomethingWithURL(URL);
        return S_OK;
    }).Get());

選擇>檔案「全部儲存」 (Ctrl+Shift+S) 來儲存專案。

現在，WebView2 會凍結並 Object 回傳頁面文件一次。

如果程式碼必須依序執行，請使用回調

腳本注入 API (以及其他一些 WebView2 API) 是非同步的。所以，如果程式碼必須以特定順序執行，你應該使用回調。

請繼續以下步驟。

步驟 15 - 主機與網頁內容之間的溝通

主機與網站內容也能透過此 postMessage 方式相互溝通。在 WebView2 控制項中執行的網頁內容可透過此 window.chrome.webview.postMessage 方法發佈至主機，訊息由主機上任何註冊 ICoreWebView2WebMessageReceivedEventHandler 事件處理器處理。

同樣地，主機可以透過 or ICoreWebView2::PostWebMessageAsJSON 方法訊息網路內容ICoreWebView2::PostWebMessageAsString，訊息由從監聽者新增window.chrome.webview.addEventListener的處理器捕捉。此通訊機制允許網頁內容利用原生功能，傳遞訊息要求主機執行原生 API。

舉例來說，當你嘗試在 WebView2 中輸出文件 URL 時，會進行以下步驟：

主機會註冊一個處理器，將收到的訊息回傳至網頁內容。
主機會向網頁內容注入腳本，該腳本會註冊一個處理器以從主機列印訊息。
主機會注入一個腳本到網頁內容，將網址貼給主機。
主機的處理器會被觸發，並 (URL 回傳訊息，) 到網頁內容。
網頁內容的處理者會被觸發，並從主機 (URL) 列印訊息。

讓主機應用程式與網頁內容透過以下方式溝通 postMessage：

如果還沒有，請將以下程式碼貼上：HelloWebView.cpp

// Step 6 - Communication between host and web content
// Set an event handler for the host to return received message back to the web content
webview->add_WebMessageReceived(Callback<ICoreWebView2WebMessageReceivedEventHandler>(
    [](ICoreWebView2* webview, ICoreWebView2WebMessageReceivedEventArgs* args) -> HRESULT {
        wil::unique_cotaskmem_string message;
        args->TryGetWebMessageAsString(&message);
        // processMessage(&message);
        webview->PostWebMessageAsString(message.get());
        return S_OK;
    }).Get(), &token);

// Schedule an async task to add initialization script that
// 1) Add an listener to print message from the host
// 2) Post document URL to the host
webview->AddScriptToExecuteOnDocumentCreated(
    L"window.chrome.webview.addEventListener(\'message\', event => alert(event.data));" \
    L"window.chrome.webview.postMessage(window.document.URL);",
    nullptr);

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

範例應用程式首先會打開一個彈出視窗，顯示將載入的網址，並附帶 一個確定 按鈕：
點擊確定按鈕關閉彈出視窗，繼續查看網址：

WebView2 視窗現在顯示網頁內容：Bing 網站。 http://www.bing.com
準備好後，關閉 WebView 範例 視窗。

恭喜你，你打造了一個 Win32 應用程式，能承載並使用 WebView2 控制項！您的開發環境現在已設定為 WebView2 應用程式開發，將 WebView2 控制項納入您的 Win32 應用程式中。你也接觸過 WebView2 的程式設計概念。

API 參照

WebView2 Win32 C++ API 參考
WebView2 API 參考 - 各平台的 API 參考。

另請參閱

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-27

共用方式為

開始使用 Win32 應用程式中的 WebView2

完成的專案

步驟 1 - 安裝 Visual Studio

步驟 2 - 複製或下載 WebView2Samples 倉庫

步驟三 - 打開完成的溶液 (WebView2GettingStarted.sln)

步驟 4 - 如果有提示就安裝工作負載

再目標專案

步驟 5 - 在 Visual Studio 中查看已開啟的專案

設定解決方案使用 Win10 SDK 和 Visual Studio 工具組

步驟 6 - 建立並執行倉庫完成的專案

步驟7 - 更新或安裝 Windows 實作函式庫 (WIL)

步驟 8 - 更新或安裝 WebView2 SDK

步驟 9 - 可選擇性地從 HelloWebView.cpp 刪除 WebView2 程式碼

步驟 10 - 在 HelloWebView.cpp 中加入 WebView2.h 標頭

步驟 11 - 建立你的空白範例應用程式

步驟 12 - 在父視窗新增 WebView2 控制項

打造你的 Bing 範例應用程式

步驟 13 - 導航事件

步驟 14 - 腳本編寫

如果程式碼必須依序執行，請使用回調

步驟 15 - 主機與網頁內容之間的溝通

API 參照

另請參閱

意見反應

其他資源