Обзор функций и API WebView2

  • Статья

Внедрение элемента управления WebView2 в приложение предоставляет приложению доступ к различным методам и свойствам, предоставляемым через классы или интерфейсы WebView2. WebView2 содержит сотни API- интерфейсов, которые предоставляют широкий набор возможностей, начиная от расширения возможностей собственной платформы приложения до предоставления приложению возможности изменять возможности браузера. В этой статье представлена высокоуровневая группировка API WebView2, которая поможет вам понять, что можно сделать с помощью WebView2.

Обзор областей функций верхнего уровня

При размещении элемента управления WebView2 приложение имеет доступ к следующим функциям и API:

Функциональная область Назначение
Основные классы: Среда, Контроллер и Core Классы CoreWebView2Environment, CoreWebView2Controllerи CoreWebView2 (или эквивалентные интерфейсы) работают вместе, чтобы в приложении можно было разместить элемент управления браузера WebView2 и получить доступ к функциям браузера. Эти большие классы предоставляют широкий спектр API- интерфейсов, к которым может получить доступ ваше ведущее приложение, чтобы предоставить пользователям следующие категории функций, связанных с браузером.
Взаимодействие между веб-интерфейсом и собственным интерфейсом Внедрение веб-содержимого в собственные приложения. Обмен данными между машинным и веб-кодом с помощью простых сообщений, кода JavaScript и собственных объектов.
Функции браузера Элемент управления WebView2 предоставляет приложению доступ ко многим функциям браузера. Вы можете изменить эти функции браузера, включить или отключить их.
Управление процессами Получите сведения о выполнении процессов WebView2, выходе из процессов и сбоях процессов, чтобы ваше приложение смогла принять соответствующие меры.
Переход к страницам и управление загруженным содержимым Управление переходом к веб-страницам и управление содержимым, загруженным на веб-страницах.
Iframes Внедрение других веб-страниц в собственную веб-страницу. Определите, когда создаются внедренные веб-страницы, определите, когда внедренные веб-страницы перемещаются, и при необходимости обходить параметры x-frame.
Проверка подлинности Приложение может обрабатывать обычную проверку подлинности с помощью элемента управления WebView2. Обычная проверка подлинности — это особый подход к проверке подлинности, который является частью протокола HTTP.
Отрисовка WebView2 в приложениях, отличных от платформы Используйте эти API для настройки системы отрисовки WebView2, если в ведущем приложении не используется платформа пользовательского интерфейса. Эта настройка отрисовки определяет, как WebView2 отрисовывает выходные данные в хост-приложении и как WebView2 обрабатывает входные данные, фокус и специальные возможности.
Отрисовка WebView2 с использованием композиции Для отрисовки WebView2 на основе композиции используйте для CoreWebView2Environment создания CoreWebView2CompositionController. CoreWebView2CompositionController предоставляет те же API, что и CoreWebView2Controller, но также включает API для отрисовки на основе композиции.
Параметры среды Данные пользователя. Управление папкой пользовательских данных (UDF), которая является папкой на компьютере пользователя. UDF содержит данные, связанные с ведущим приложением и WebView2. Приложения WebView2 используют папки данных пользователей для хранения данных браузера, таких как файлы cookie, разрешения и кэшированные ресурсы. Управление несколькими профилями в рамках одной пользовательской функции.
Выбор среды выполнения поддерживает предварительное тестирование и самостоятельное размещение. Вы можете указать порядок поиска для каналов предварительного просмотра браузера и указать каналы предварительного просмотра браузера.
Производительность и отладка Анализ и отладка производительности, обработка событий, связанных с производительностью, а также управление использованием памяти для повышения скорости реагирования приложения.
Протокол Chrome DevTools (CDP) Инструментирование, проверка, отладка и профилирование браузеров на основе Chromium. Протокол Chrome DevTools (CDP) является основой для Microsoft Edge DevTools. Используйте протокол Chrome DevTools для функций, которые не реализованы на платформе WebView2.

На этой странице перечислены только API, которые находятся в пакетах SDK для выпуска; В нем нет списка экспериментальных API или стабильных API, которые еще не доступны в пакетах SDK для выпуска. Полный список API, включая экспериментальные API, см. в заметках о выпуске пакета SDK для WebView2.

Основные классы: Среда, Контроллер и Core

Классы CoreWebView2Environment, CoreWebView2Controllerи CoreWebView2 (или эквивалентные интерфейсы) работают вместе, чтобы в приложении можно было разместить элемент управления браузера WebView2 и получить доступ к функциям браузера. Эти три больших класса предоставляют широкий спектр API, к которым может получить доступ ведущее приложение, чтобы предоставить пользователям множество категорий функций, связанных с браузером.

  • Класс CoreWebView2Environment представляет группу элементов управления WebView2, которые используют один и тот же процесс браузера WebView2, папку данных пользователя и процессы отрисовщика. Из этого CoreWebView2Environment класса создаются пары экземпляров CoreWebView2Controller и CoreWebView2 .
  • Класс CoreWebView2Controller отвечает за функциональные возможности, связанные с размещением, такие как фокус окна, видимость, размер и ввод, где в приложении размещается элемент управления WebView2.
  • Класс CoreWebView2 предназначен для веб-частей элемента управления WebView2, включая сеть, навигацию, скрипт, а также анализ и отрисовку HTML.

См. также:

Взаимодействие между веб-интерфейсом и собственным интерфейсом

Элемент управления Microsoft Edge WebView2 позволяет внедрять веб-содержимое в собственные приложения. Вы можете взаимодействовать между машинным и веб-кодом с помощью простых сообщений, кода JavaScript и машинных объектов. Ниже приведены main API для взаимодействия между веб-кодом и машинным кодом.

Подразделы ниже:

Распространенные варианты использования веб-взаимодействия или собственного взаимодействия:

  • Обновите заголовок окна собственного узла после перехода на другой веб-сайт.
  • Отправьте собственный объект камеры и используйте его методы из веб-приложения.
  • Запустите выделенный файл JavaScript на веб-стороне приложения.

См. также:

Общий доступ к объектам узла или веб-сайта

WebView2 позволяет передавать объекты, определенные в машинном коде, в веб-код приложения. Объекты узла — это любые объекты, определенные в машинном коде, которые вы решили передать в веб-код приложения.

Объекты узла можно проецировать в JavaScript, чтобы можно было вызывать собственные методы объектов (или другие API) из веб-кода приложения. Например, приложение может вызывать такие API в результате взаимодействия с пользователем на веб-стороне приложения. Таким образом, вам не нужно повторно выполнять API собственных объектов, такие как методы или свойства, в веб-коде.

Выполнение скрипта

Позволяет ведущему приложению добавлять код JavaScript в веб-содержимое в элементе управления WebView2.

Веб-обмен сообщениями

Приложение может отправлять сообщения в веб-содержимое, которое находится в элементе управления WebView2, и получать сообщения из этого веб-содержимого. Сообщения отправляются в виде строк или объектов JSON.

Диалоговые окна скриптов

При размещении WebView2 приложение может управлять различными диалогами JavaScript, подавлять их или заменять пользовательскими диалогами.

Общий буфер

API SharedBuffer поддерживает буферы общего доступа между процессом ведущего приложения WebView2 и процессом отрисовщика WebView2 на основе общей памяти из ОС.

Функции браузера

Элемент управления WebView2 предоставляет приложению доступ ко многим функциям браузера. Вы можете изменить эти функции браузера, включить или отключить их.

Подразделы ниже:

Печать

Веб-страницу можно распечатать на принтере, в PDF-файле или в потоке PDF, настроив настраиваемые параметры печати.

См. также:

Файлы cookie

Файлы cookie в WebView2 можно использовать для управления сеансами пользователей, сохранения настроек персонализации пользователей и отслеживания поведения пользователей.

См. также:

Захват изображений

Размещая WebView2, приложение может записывать снимки экрана и указывать, какой формат следует использовать для сохранения изображения.

Загрузки

Приложение может управлять процессом скачивания в WebView2. Ваше приложение может:

  • Разрешить или заблокировать скачивание на основе разных метаданных.
  • Измените расположение скачивания.
  • Настройка пользовательского пользовательского интерфейса загрузки.
  • Настройка пользовательского интерфейса по умолчанию.

Общие:

Изменение интерфейса по умолчанию:

Пользовательский интерфейс загрузки:

Разрешения

Различные веб-страницы могут запрашивать разрешения на доступ к некоторым привилегированным ресурсам, таким как датчик геолокации, камера и микрофон. Ведущее приложение может программно отвечать на запросы разрешений и может заменить пользовательский интерфейс разрешений по умолчанию собственным пользовательским интерфейсом.

Контекстные меню

Элемент управления WebView2 предоставляет контекстное меню по умолчанию (контекстное меню), которое можно настроить или отключить, а также создать собственное контекстное меню.

См. также:

Строка состояния

Строка состояния находится в левом нижнем углу страницы и отображает состояние отображаемой веб-страницы. В WebView2 можно включить или отключить строку состояния, получить текст в строке состояния и узнать, когда текст строки состояния изменился.

Агент пользователя

Агент пользователя — это строка, представляющая удостоверение программы от имени пользователя, например имя браузера. В WebView2 можно задать агент пользователя.

См. также:

Автозаполнение

Приложение может независимо контролировать, включена ли функция автозаполнения браузера для общих сведений или паролей.

"Audio" (Аудио);

Ваше приложение может отключить и включить весь звук, а также узнать, когда воспроизводимый звук.

Тестирование нажатий щелчков мыши в регионах

Предоставляет результаты тестирования попадания в регионах, содержащихся в WebView2. Полезно для визуально размещенных приложений, которые хотят обрабатывать события мыши в не клиентской области окна WebView2.

Навигация с помощью жестов прокрутки

Размещая элемент управления WebView2, приложение может включать или отключать навигацию с помощью жестов прокрутки на устройствах с поддержкой сенсорного ввода. Этот жест позволяет конечным пользователям:

  • Проведите пальцем влево или вправо (по горизонтали), чтобы перейти к предыдущей или следующей странице в журнале навигации.
  • Потяните, чтобы обновить текущую страницу (проведите по вертикали).

В настоящее время эта функция отключена по умолчанию в браузере. Чтобы включить эту функцию в WebView2, задайте AdditionalBrowserArguments свойство , указав --pull-to-refresh параметр .

Включение или отключение ответа браузера на клавиши акселератора (сочетания клавиш)

ICoreWebView2AcceleratorKeyPressedEventArgsIsBrowserAcceleratorKeyEnabled имеет свойство, позволяющее управлять тем, обрабатывает ли браузер клавиши акселератора (сочетания клавиш), такие как CTRL+P или F3.

См. также:

Полноэкранный

В WebView2 можно узнать, когда ЭЛЕМЕНТ HTML входит в полноэкранное представление или покидает его.

Панель инструментов PDF

В средстве просмотра PDF-файлов браузера в верхней части находится панель инструментов для конкретного PDF-файла. В WebView2 некоторые элементы можно скрыть на панели инструментов средства просмотра PDF.

Темы

В WebView2 можно настроить цветовую тему как системную, светлую или темную.

Язык

Свойство Language задает язык интерфейса WebView2 по умолчанию, который применяется к пользовательскому интерфейсу браузера (например, контекстным меню и диалоговым окнам), а также задает accept-language http-заголовок, который WebView2 отправляет веб-сайтам.

Свойство ScriptLocale позволяет ведущему приложению задать языковой стандарт по умолчанию для всех Intl API JavaScript и других зависимых от него API JavaScript, таких как Intl.DateTimeFormat(), что влияет на форматирование строк в форматах времени и даты.

Новое окно

WebView2 предоставляет функциональные возможности для обработки функции window.open()JavaScript .

Закрыть окно

WebView2 предоставляет функциональные возможности для обработки функции window.close()JavaScript .

Название документа

Приложение может определить, когда изменилось название текущего документа верхнего уровня.

Значок

В WebView2 можно задать Favicon для веб-сайта или получать уведомления о его изменениях.

Безопасность и конфиденциальность

Предотвращение отслеживания

Предотвращение отслеживания позволяет ведущему приложению контролировать уровень предотвращения отслеживания элемента управления WebView2, связанного с профилем пользователя.

Smartscreen

Microsoft Defender SmartScreen ("SmartScreen") включен по умолчанию. Свойство IsReputationCheckingRequired определяет, включен ли SmartScreen.

Если вы не отключите SmartScreen, необходимо уведомить всех пользователей о том, что ваше программное обеспечение включает в себя Microsoft Defender SmartScreen, а также собирает и отправляет в корпорацию Майкрософт сведения о пользователе, как описано в Заявлении о конфиденциальности Майкрософт и Техническом документе о конфиденциальности Microsoft Edge.

См. также:

  • SmartScreen в разделе Данные и конфиденциальность в WebView2.
Настраиваемые отчеты о сбоях

Если какой-либо процесс WebView2 завершает работу, создается один или несколько файлов minidump и отправляются в Корпорацию Майкрософт для диагностики. Используйте этот API для настройки отчетов о сбоях при выполнении диагностика и выполнении анализа.

  • Чтобы предотвратить отправку аварийных дампов в Корпорацию Майкрософт, задайте для свойства значение IsCustomCrashReportingEnabledfalse.
  • Чтобы найти аварийные дампы и выполнить их настройку CrashDumpFolderPath , используйте свойство .

См. также:

Расширения браузера

Приложение может внедрить элемент управления WebView2, использующий расширения браузера (надстройки). Расширение Microsoft Edge — это небольшое приложение, которое разработчики используют для добавления или изменения функций Microsoft Edge, чтобы улучшить работу пользователя при просмотре.

См. также:

Управление процессами

Получите сведения о выполнении процессов WebView2, выходе из процессов и сбоях процессов, чтобы ваше приложение смогла принять соответствующие меры.

Подразделы ниже:

Сведения о процессе кадра

API сведений о кадрах, включая GetProcessExtendedInfos, предоставляет snapshot коллекцию всех кадров, которые активно выполняются в связанном процессе отрисовщика. Этот API позволяет приложению определять, какая часть WebView2 потребляет ресурсы, например память или ЦП.

Переход к страницам и управление загруженным содержимым

С помощью элемента управления WebView2 приложение может управлять переходом на веб-страницы и содержимым, загруженным на веб-страницах.

Подразделы ниже:

Управление содержимым, загруженным в WebView2

Эти API загружают, останавливают загрузку и перезагрузку содержимого в WebView2. Загружаемое содержимое может быть следующим:

  • Содержимое из URL-адреса.
  • Строка HTML.
  • Сопоставление локального содержимого через имя виртуального узла с локальной папкой.
  • Содержимое из созданного сетевого запроса.

См. также:

Методы журнала обеспечивают обратную и прямую навигацию в WebView2, а события журнала предоставляют сведения об изменениях в журнале и в текущем источнике WebView2.

NavigationKind получает тип навигации для каждой навигации, например "Назад/вперед", "Перезагрузка" или переход к новому документу.

Блокировка нежелательного перехода

Событие NavigationStarting позволяет приложению отменить переход по указанным URL-адресам в WebView2, в том числе для кадров.

С помощью NavigationStarting и других событий навигации приложение может быть проинформировано о состоянии навигации в WebView2. Навигация — это процесс загрузки нового URL-адреса.

См. также:

Управление сетевыми запросами в WebView2

Событие WebResourceRequested позволяет приложению перехватывать и переопределять все сетевые запросы в WebView2. Событие WebResourceResponseReceived позволяет приложению отслеживать отправленный запрос и ответ, полученный из сети.

См. также:

Регистрация пользовательской схемы

Позволяет CustomSchemeRegistration регистрировать пользовательские схемы в WebView2, чтобы приложение хозяйки WebResourceRequested обрабатывал события для запросов к этим URL-адресам пользовательских схем и переходить webView2 по таким URL-адресам.

Сертификаты клиента

В WebView2 можно использовать API сертификата клиента, чтобы выбрать сертификат клиента на уровне приложения. Этот API позволяет:

  • При необходимости отобразите пользователю пользовательский интерфейс.
  • Замените диалоговое окно сертификата клиента по умолчанию.
  • Программный запрос сертификатов.
  • Выберите сертификат из списка, чтобы ответить серверу, когда WebView2 выполняет запрос к HTTP-серверу, которому требуется сертификат клиента для проверки подлинности HTTP.

Сертификаты сервера

В WebView2 можно использовать API сертификата сервера, чтобы доверять TLS-сертификату сервера на уровне приложения. Таким образом, главное приложение может отрисовыть страницу, не запрашивая у пользователя ошибку TLS, или ведущее приложение может автоматически отменить запрос.

Запуск схемы внешнего URI

Запустите схему URI, зарегистрированную в ОС.

Iframes

Iframes позволяет внедрять другие веб-страницы в собственную веб-страницу. В WebView2 вы можете:

  • Узнайте, когда создаются iframes.
  • Узнайте, когда iframes переходят.
  • Разрешить обход параметров X-кадра.

См. также:

Проверка подлинности

Приложение может обрабатывать обычную проверку подлинности с помощью элемента управления WebView2. Обычная проверка подлинности — это особый подход к проверке подлинности, который является частью протокола HTTP.

См. также:

Отрисовка WebView2 в приложениях, отличных от платформы

Используйте эти API для настройки системы отрисовки WebView2, если в ведущем приложении не используется платформа пользовательского интерфейса. Эта настройка отрисовки определяет, как WebView2 отрисовывает выходные данные в хост-приложении и как WebView2 обрабатывает входные данные, фокус и специальные возможности.

Когда следует использовать эти API

  • Платформа пользовательского интерфейса . Если вы используете платформу пользовательского интерфейса для приложения, следует использовать элемент WebView2, предоставляемый этой платформой пользовательского интерфейса, а не эти API.

  • Нет платформы пользовательского интерфейса и не используется композиция . Если вы не используете платформу пользовательского интерфейса для приложения (например, если вы используете только Win32 напрямую) или если у вашей платформы пользовательского интерфейса нет элемента WebView2, необходимо создать CoreWebView2Controller и отобразить его в приложении, используя эти API в этом разделе.

  • Нет платформы пользовательского интерфейса и использование композиции . Если пользовательский интерфейс приложения создан с помощью DirectComposition или Windows.UI.Composition, следует использовать CoreWebView2CompositionController вместо этих API. См. раздел Отрисовка WebView2 с помощью композиции ниже.

Подразделы ниже:

Определение размера, позиционирование и видимость

CoreWebView2Controller принимает родительский HWNDобъект . Свойство Bounds размеров и позиционирует WebView2 относительно родительского HWNDобъекта . Видимость WebView2 можно переключить с помощью IsVisible.

Масштабирование

WebView2 ZoomFactor используется для масштабирования только веб-содержимого окна. Масштабирование пользовательского интерфейса также обновляется, когда пользователь масштабирует содержимое, нажимая клавиши CTRL при повороте колесика мыши.

Масштаб растеризации

API RasterizationScale масштабирует весь пользовательский интерфейс WebView2, включая контекстные меню, подсказки и всплывающие окна. Приложение может задать, должен ли WebView2 обнаруживать изменения масштаба монитора и автоматически обновлять RasterizationScale. BoundsMode используется для настройки того, интерпретируется ли свойство Bounds как необработанные пиксели или dips (которые необходимо масштабировать с помощью RasterizationScale).

Фокус и табуляция

Элемент управления WebView2 вызывает события, чтобы сообщить приложению, когда элемент управления получает фокус или теряет фокус. Для перехода на вкладки (нажатие клавиши TAB ) существует API для перемещения фокуса в WebView2 и событие для WebView2 для запроса приложения на возврат фокуса.

Родительское окно

WebView2 можно повторно иродовать в другой дескриптор родительского окна (HWND). WebView2 также необходимо уведомлять о том, что положение приложения на экране изменилось.

Ускорители клавиатуры

Когда WebView2 имеет фокус, он напрямую получает входные данные от пользователя. Приложение может захотеть перехватывать и обрабатывать определенные сочетания клавиш акселератора (сочетания клавиш) или отключать обычное поведение клавиш акселератора браузера.

См. также включение или отключение браузера, отвечающего на клавиши акселератора (сочетания клавиш) выше.

Цвет фона по умолчанию

WebView2 может указать цвет фона по умолчанию. Цвет может быть любым непрозрачным или прозрачным. Этот цвет будет использоваться, если HTML-страница не задает собственный цвет фона.

Отрисовка WebView2 с использованием композиции

Для отрисовки WebView2 на основе композиции используйте для CoreWebView2Environment создания CoreWebView2CompositionController. CoreWebView2CompositionController предоставляет те же API, что и CoreWebView2Controller, но также включает API для отрисовки на основе композиции.

Подразделы ниже:

Подключение к визуальному дереву

WebView2 может подключать свое дерево композиции к idCompositionVisual, IDCompositionTarget или Windows::UI::Composition::ContainerVisual.

Переадресация входных данных

Пространственные входные данные (мышь, сенсорный ввод, перо) принимаются приложением и должны быть отправлены в WebView2. WebView2 уведомляет приложение о том, когда курсор следует обновить в зависимости от положения мыши.

Перетаскивание

Перетаскивание из элемента управления WebView2 в другое приложение поддерживается по умолчанию. Однако для перетаскивания в элемент управления WebView2 требуется, чтобы, когда ведущее приложение получает событие из системы, ведущее приложение должно пересылать IDropTarget событие в элемент управления WebView2. Перетаскивание в элемент управления WebView2 включает операции перетаскивания, которые полностью находятся в элементе управления WebView2.

Используйте следующие API для пересылки IDropTarget событий из системы в элемент управления WebView2.

Специальные возможности

По умолчанию WebView2 будет отображаться в дереве специальных возможностей как дочерний элемент родительского HWND для приложений Win32/C++. WebView2 предоставляет API для лучшего расположения содержимого WebView2 по сравнению с другими элементами в приложении.

Не применимо.

Параметры среды

Подразделы ниже:

Данные пользователя

Управление папкой пользовательских данных (UDF), которая является папкой на компьютере пользователя. UDF содержит данные, связанные с ведущим приложением и WebView2. Приложения WebView2 используют папки данных пользователей для хранения данных браузера, таких как файлы cookie, разрешения и кэшированные ресурсы.

Подразделы ниже:

См. также:

Очистка данных браузера:

Несколько профилей

Управление несколькими профилями в одной папке данных пользователя.

См. также:

Create объект options, определяющий профиль:

Create элемент управления WebView2, использующий профиль:

Доступ к профилю и управление им:

Удаление профиля

Приложение может удалять профили пользователей для элемента управления веб-браузера WebView2.

См. также:

Выбор среды выполнения

Выбор среды выполнения поддерживает предварительное тестирование и самостоятельное размещение. При создании среды WebView2:

  • Чтобы указать порядок поиска для каналов предварительного просмотра браузера, используйте CoreWebView2EnvironmentOptions.ChannelSearchKind свойство .
  • Чтобы указать каналы предварительного просмотра браузера, используйте CoreWebView2EnvironmentOptions.ReleaseChannels свойство .

См. также:

Производительность и отладка

Анализ и отладка производительности, обработка событий, связанных с производительностью, а также управление использованием памяти для повышения скорости реагирования приложения.

Подразделы ниже:

Целевой объект использования памяти

Задает уровни потребления памяти, например low или normal.

Протокол Chrome DevTools (CDP)

Протокол Chrome DevTools (CDP) предоставляет API для инструментирования, проверки, отладки и профилирования Chromium браузеров. Протокол Chrome DevTools является основой для Microsoft Edge DevTools. Используйте протокол Chrome DevTools для функций, которые не реализованы на платформе WebView2.

См. также:

Открыть:

Вызова:

Приемник:

См. также