Начало работы с WebView2 в приложениях Win32
В этой статье вы настроите средства разработки (если это еще не сделано), узнаете, как добавить код WebView2 в проект приложения Win32 и основные понятия WebView2.
Это руководство начинается с открытия существующего проекта приложения Win32 с добавленным кодом WebView2. Проект использует каталог Win32_GettingStarted (WebView2GettingStarted.sln), который является частью репозитория WebView2Samples
. Чтобы использовать эту статью, сделайте следующее:
- Клонируйте или скачайте репозиторий
WebView2Samples
на локальный диск. - Запустите завершенный проект.
- При необходимости удалите код WebView2 из ,
HelloWebView.cpp
чтобы восстановить базовое приложение Win32. - Выполните действия, описанные в этой статье о добавлении и понимании кода WebView2.
В этом руководстве нет создания нового проекта. шаблон проекта в Visual Studio не используется для создания нового проекта. Вместо этого вы начинаете с завершенного проекта, который находится в репозитории.
Завершенный проект
Готовый проект учебника доступен в репозитории 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, мы начнем с существующего проекта Microsoft Visual Studio (WebView2GettingStarted
), хранящегося в репозитории WebView2Samples
GitHub. Мы добавим функции WebView2. Фактически, функции уже добавлены, но следуйте инструкциям по настройке и объяснению.
Существующий проект Visual Studio, с который мы начнем, является частью примера кода из стандартного классического приложения Win32 на C++. Сведения о базовом стандартном примере приложения Win32 в новом окне или вкладке см. в разделе Пошаговое руководство. Создание традиционного классического приложения Windows (C++).
Клонируйте или скачайте репозиторий WebView2Samples следующим образом:
- Если вы еще этого не сделали, клонируйте или скачайте репозиторий
WebView2Samples
. Для этого в отдельном окне или на вкладке выполните действия, описанные в статье Скачивание репозитория WebView2Samples или клонирование репозитория WebView2Samples в разделе Настройка среды разработки для WebView2.
Затем вернитесь сюда после копирования репозитория на локальный диск и выполните следующие действия.
Шаг 3. Открытие готового решения (WebView2GettingStarted.sln)
Вы начинаете с базового классического проекта, который содержит одно главное окно. Мы начнем с существующего проекта приложения из репозитория WebView2Samples , который вы клонировали или скачали из GitHub на предыдущем шаге.
Откройте Visual Studio (не Visual Studio Code).
Откройте
WebView2GettingStarted.sln
, который находится по пути:<your repo directory>/WebView2Samples/GettingStartedGuides/Win32_GettingStarted/WebView2GettingStarted.sln
.
Шаг 4. Установка рабочих нагрузок при появлении запроса
Visual Studio Installer может открыться и предложить установить рабочую нагрузку:
Если Visual Studio Installer предлагает установить рабочую нагрузку:
Выберите карточку Разработка классических приложений на C++ , чтобы появилась галочка.
При необходимости также выберите карточку разработки классических приложений .NET (не требуется для этого руководства), чтобы на этой карточке также появилась галочка.
Нажмите кнопку Установить .
Установщик закроется.
Ретаргетинг проектов
Может появиться диалоговое окно Действия решения проверки 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"
), который уже присутствует в файле сразу после клонирования (скачивания) репозитория.
Настройка решения для использования пакета SDK для Win10 и набора инструментов Visual Studio
Этот шаг необходим только для более старых версий Visual Studio, поэтому, скорее всего, его можно пропустить. Но вы можете взглянуть на этот пользовательский интерфейс в любом случае:
В обозревателе решений Visual Studio щелкните правой кнопкой мыши проектWebView2GettingStarted (не решение с тем же именем) и выберите пункт Свойства.
Выберите Свойства> конфигурацииОбщие, а затем (если это уже не правильный параметр):
Измените версию windows SDK , чтобы использовать пакет SDK для Win10.
Измените набор инструментов платформы, чтобы использовать набор инструментов Visual Studio.
Эти изменения необходимы только для более ранних версий Visual Studio.
Ниже приведен снимок экрана Visual Studio 2017, показывающий некоторые допустимые параметры:
Ниже приведен снимок экрана Visual Studio 2022. значения уже были правильными, поэтому никаких изменений не требовалось:
Выполните указанные ниже действия.
Шаг 6. Сборка и запуск готового проекта репозитория
На этом этапе среда разработки настроена для запуска приложений Win32 WebView2 в режиме отладки в Visual Studio и добавления функций WebView2.
Чтобы убедиться, что в системе настроено кодирование WebView2, запустите проект в режиме отладки следующим образом:
Выберите Отладка>Начать отладку (F5), чтобы выполнить сборку и запуск проекта.
В примере приложения сначала открывается всплывающее окно, в котором отображается URL-адрес, который будет загружен, а также кнопка ОК :
Нажмите кнопку ОК , чтобы закрыть всплывающее окно и перейти по URL-адресу:
В окне WebView2 теперь отображается содержимое веб-страницы: веб-сайт Bing,
http://www.bing.com
.Закройте окно примера WebView .
Шаг 7. Обновление или установка библиотек реализации Windows (WIL)
Программа WIL уже установлена в проекте в репозитории, но выполните следующие действия, чтобы узнать о настройке и проверить настройку проекта.
Через некоторое время вы установите Библиотеки реализации Windows (WIL) — библиотеку C++, доступную только для заголовков, чтобы упростить жизнь разработчикам в Windows с помощью читаемых и типобезопасных интерфейсов C++ для шаблонов com-кода Windows. Этот пакет Microsoft.Windows.ImplementationLibrary устанавливается с помощью обозревателя решений в Visual Studio для проекта.
В этом руководстве также используется библиотека шаблонов C++ среды выполнения Windows (WRL) — библиотека шаблонов, которая предоставляет низкоуровневый способ создания и использования компонентов среды выполнения Windows.
Установите библиотеки реализации Windows (WIL) из Visual Studio следующим образом:
В Visual Studio убедитесь, что решение WebView2GettingStarted по-прежнему открыто.
В обозревателе решений щелкните правой кнопкой мыши узел проекта WebView2GettingStarted (не узел решения) и выберите Управление пакетами NuGet.
В окне NuGet откройте вкладку Обзор .
В строке поиска в левом верхнем углу введите
Microsoft.Windows.ImplementationLibrary
. Или скопируйте и вставьте однострочный блок кода ниже. Затем выберите Microsoft.Windows.ImplementationLibrary.Microsoft.Windows.ImplementationLibrary
Выбор пакета Microsoft.Windows.ImplementationLibrary в диспетчере пакетов NuGet в Visual Studio:
Чтобы увеличить масштаб, щелкните правой кнопкой мыши >Открыть изображение на новой вкладке.
Если вы не видите Microsoft.Windows.ImplementationLibrary в списке, проверьте исходное расположение NuGet следующим образом:
Выберите Сервис>Параметры> Источникипакетов диспетчера >пакетов NuGet.
Убедитесь, что в источниках пакетов есть nuget.com источник, указывающий на
https://api.nuget.org/v3/index.json
.Если источник пакета не содержит этого источника, введите
nuget.com
в текстовом поле Имя иhttps://api.nuget.org/v3/index.json
в текстовом поле Источник . Затем нажмите кнопки Обновить и ОК.
В правом верхнем углу нажмите кнопку Установить (или обновить ). NuGet загружает библиотеку реализации Windows (WIL) на компьютер.
Теперь установлены библиотеки реализации Windows (WIL), а также библиотека шаблонов C++ среды выполнения Windows (WRL).
Выполните указанные ниже действия.
Шаг 8. Обновление или установка пакета SDK для WebView2
Готовый проект в репозитории уже имеет версию пакета SDK для WebView2, установленную для проекта. Если вы создавали проект с нуля с помощью шаблона проекта Win32, вам потребуется установить пакет SDK WebView для проекта, как описано здесь.
Затем обновите (или установите) пакет SDK для WebView2. Пакет SDK для WebView2 включает элемент управления WebView2 на базе Microsoft Edge и позволяет внедрять веб-технологии (HTML, CSS и JavaScript) в собственные приложения.
Обновите (или установите) пакет SDK для WebView2 следующим образом:
В Visual Studio убедитесь, что решение WebView2GettingStarted открыто, как описано выше.
В обозревателе решений щелкните правой кнопкой мыши узел проекта WebView2GettingStarted (а не узел решения WebView2GettingStarted ) и выберите Управление пакетами NuGet.
В Visual Studio откроется вкладка и панель Диспетчер пакетов NuGet .
Если пакет SDK для WebView2 уже установлен для проекта, как в случае с проектом репозитория, в окне NuGet щелкните вкладку Установленные или Обновить .
Если вы устанавливаете пакет SDK для WebView2 в новом проекте, перейдите на вкладку Обзор .
В правой части панели поиска снимите флажок Включить предварительную версию (если вы не знаете, что требуется предварительная версия пакета SDK).
В строке поиска в левом верхнем углу введите
Microsoft.Web.WebView2
. Или скопируйте и вставьте однострочный блок кода ниже. Затем выберите Microsoft.Web.WebView2.Microsoft.Web.WebView2
В правом окне щелкните Обновить (или Установить). NuGet скачивает пакет SDK для WebView2 на компьютер.
Закройте вкладку Диспетчер пакетов NuGet .
Пакет SDK для WebView2 обновлен или установлен, поэтому среда разработки теперь настроена для добавления функций WebView2 в приложение Win32.
Выполните указанные ниже действия.
Шаг 9. При необходимости удалите код WebView2 из HelloWebView.cpp
Если вы хотите выполнить приведенные ниже действия, чтобы добавить в себя код HelloWebView.cpp
WebView2, удалите два блока кода WebView2 следующим образом:
В
HelloWebView.cpp
удалите следующий код:// include WebView2 header #include "WebView2.h"
В
HelloWebView.cpp
удалите строки кода, которые находятся между этими двумя строками комментариев, но сохраните эти две строки комментариев:// <-- WebView2 sample code starts here --> ... // <-- WebView2 sample code ends here -->
Шаг 10. Включение заголовка WebView2.h в HelloWebView.cpp
Выше мы сделали следующее:
- Клонирован или скачан репозиторий примеров, включая существующий проект, содержащий стандартное классическое приложение Windows C++.
- Обновлена или установлена библиотека реализации Windows (WIL).
- Обновлен или установлен пакет SDK для WebView2, чтобы добавить функции WebView2.
- При необходимости удален код WebView2 из
HelloWebView.cpp
.
Затем добавьте в приложение функции WebView2, как показано ниже.
В Visual Studio убедитесь, что решение WebView2GettingStarted открыто.
В обозревателе решений разверните узел Исходные файлы и нажмите кнопку
HelloWebView.cpp
.Если следующий код еще не указан, вставьте следующий код в
HelloWebView.cpp
, после последней#include
строки:// include WebView2 header #include "WebView2.h"
Убедитесь, что
include
раздел выглядит следующим образом:... #include <wrl.h> #include <wil/com.h> // include WebView2 header #include "WebView2.h"
Обратите внимание на используемые заголовки:
wrl.h
— Библиотека шаблонов C++ среды выполнения Windows (WRL) — библиотека шаблонов, которая предоставляет низкоуровневый способ создания и использования компонентов среды выполнения Windows.wil/com.h
— Библиотеки реализации Windows (WIL) — библиотека C++, доступная только для заголовков, чтобы упростить жизнь разработчикам в Windows с помощью читаемых и типобезопасных интерфейсов C++ для распространенных шаблонов кодирования Windows.WebView2.h
— Элемент управления WebView2 работает на базе Microsoft Edge и позволяет внедрять веб-технологии (HTML, CSS и JavaScript) в собственные приложения.
Выберите Файл>Сохранить все (CTRL+SHIFT+S), чтобы сохранить проект.
Файл исходного кода и проект готовы к использованию и сборке в API WebView2.
Выполните указанные ниже действия.
Шаг 11. Создание пустого примера приложения
Выберите Отладка>Начать отладку (F5), чтобы выполнить сборку и запуск проекта.
Откроется пример приложения, в котором отображается пустое окно:
Теперь у вас есть работающее пустое классическое приложение Win32 с потенциальными возможностями WebView2.
Закройте окно примера приложения WebView .
Выполните указанные ниже действия.
Шаг 12. Добавление элемента управления WebView2 в родительское окно
Затем добавьте элемент управления WebView2 в главное окно.
Вы будете CreateCoreWebView2Environment
использовать метод для настройки среды и поиска браузера Microsoft Edge, питающего элемент управления.
Обратите внимание, что если вы хотите переопределить следующие значения по умолчанию, вместо этого можно использовать версию "с параметрами" этого метода: CreateCoreWebView2EnvironmentWithOptions
- Расположение браузера
- Папка данных пользователя
- Флаги браузера
После завершения CreateCoreWebView2Environment
метода вы:
ICoreWebView2Environment::CreateCoreWebView2Controller
Запустите метод внутри обратногоICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler
вызова.Запустите метод ,
ICoreWebView2Controller::get_CoreWebView2
чтобы получить связанный элемент управления WebView2.
Теперь, чтобы выполнить описанные выше действия, в обратном вызове выполните следующие действия:
- Задайте еще несколько параметров.
- Измените размер элемента управления WebView2, чтобы заполнить 100 % родительского окна.
- Затем откройте веб-сайт Bing.com в элементе управления WebView2 в приложении Win32.
В
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, на этом этапе откроется всплывающее окно WebView2 с диалоговым окном оповещения из Bing над пустым окном WebView2. Нажмите кнопку ОК , чтобы закрыть диалоговое окно Bing. Теперь элемент управления WebView2 заполняется содержимым страницы Bing:
Если окно примера приложения WebView открыто, закройте его.
Выполните указанные ниже действия.
Шаг 13. События навигации
На предыдущем шаге мы обсуждали переход по URL-адресу с помощью ICoreWebView2::Navigate
метода . Во время навигации 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 внедрения скриптов (и некоторые другие API WebView2) являются асинхронными. Таким образом, если код должен выполняться в определенном порядке, следует использовать обратные вызовы.
Выполните указанные ниже действия.
Шаг 15. Обмен данными между хост-контентом и веб-сайтом
Узел и веб-содержимое также могут взаимодействовать друг с другом с помощью postMessage
метода . Веб-содержимое, выполняемое в элементе управления WebView2, может отправляться на узел с помощью window.chrome.webview.postMessage
метода , а сообщение обрабатывается любым зарегистрированным ICoreWebView2WebMessageReceivedEventHandler
обработчиком событий на узле.
Аналогичным образом узел может сообщения веб-содержимого с помощью ICoreWebView2::PostWebMessageAsString
метода или ICoreWebView2::PostWebMessageAsJSON
, а сообщение перехватывалось обработчиками, добавляемыми window.chrome.webview.addEventListener
из прослушивателя. Этот механизм связи позволяет веб-содержимому использовать собственные возможности, передавая сообщения с запросом на запуск собственных API узла.
В качестве примера для понимания механизма при попытке вывода URL-адреса документа в 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, чтобы выполнить сборку и запуск проекта.
В примере приложения сначала открывается всплывающее окно, в котором отображается URL-адрес, который будет загружен, а также кнопка ОК :
Нажмите кнопку ОК , чтобы закрыть всплывающее окно и перейти по URL-адресу:
В окне WebView2 теперь отображается содержимое веб-страницы: веб-сайт Bing,
http://www.bing.com
.Когда все будет готово, закройте окно примера WebView .
Поздравляем, вы создали приложение Win32, которое размещает и использует элемент управления WebView2! Теперь ваша среда разработки настроена для разработки приложений WebView2, чтобы включить элемент управления WebView2 в приложения Win32. Вы также ввели общие сведения о концепциях программирования WebView2.
Справочник по API
- Справочник по API для WebView2 Win32 C++
- Справочник по API WebView2 — справочник по API для каждой платформы.