Размещение WebView2 с использованием окон и визуальных элементов

Существует три варианта размещения элемента управления Microsoft Edge WebView2 в приложении:

  • Режим размещения с окном.
  • Режим размещения из окна в визуальный элемент.
  • Режим визуального размещения.

Вам не нужно читать эту статью, если вы используете размещение Windowed в большинстве сценариев. Размещение в окнах — хорошая отправная точка для большинства приложений. Прочитайте эту статью:

  • Если вы используете размещение Windowed в редких сценариях и испытываете постоянные проблемы с DPI и масштабированием. В этом случае рассмотрите возможность размещения window to Visual.
  • Если вы хотите предоставить более пользовательский интерфейс. В этом случае рассмотрите возможность размещения визуальных элементов.

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

Способ Описание Оптимизировано для
Размещение в окнах Элемент управления WebView2 принимает входные данные из операционной системы (ОС). ОС отправляет входные данные в WebView2. Отображение веб-содержимого быстро и легко, без необходимости включать функции для входных, выходных данных и специальных возможностей.
Размещение из окна в визуальный элемент Сочетание размещения windowed и визуального размещения. Аналогично размещению Windowed, за исключением того, что содержимое WebView2 выводится в визуальный элемент, размещенный в окне, а не непосредственно в окно. Интерфейс разработчика почти идентичен размещению Windowed, но с улучшенной обработкой DPI и масштабированием и предупреждением о том, что интерфейс рукописного ввода оболочки Windows не поддерживается.
Размещение визуальных элементов Ведущее приложение принимает пространственные входные данные (например, с помощью мыши или сенсорного ввода) от пользователя. Приложение отправляет эти входные данные в элемент управления WebView2. Более детализированный контроль над составом элементов управления. Приложение должно выполнять определенную обработку API-интерфейсов управления окнами и отрисовки.

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

  • Размещение в окнах проще реализовать, чем визуальное размещение.
  • Для визуального размещения требуются все вызовы API, необходимые для размещения Windowed, и есть дополнительные требования для правильной отрисовки.

Поддерживаемые списки API связаны в следующих разделах:

Размещение в окнах: для быстрого и простого отображения содержимого

Размещение в окнах означает, что в приложении содержимое WebView2 размещается непосредственно в окне; то есть HWND. HWND WebView2 наследует многие свойства по умолчанию от операционной системы (ОС). Элемент управления WebView2 принимает входные данные из ОС, а ОС отправляет входные данные в элемент управления WebView2. В приложении может быть несколько HWND, каждый из которых будет использоваться в качестве компонента WebView2 для доступа к веб-содержимому.

Преимущество заключается в том, что некоторые команды input/output обрабатываются ос или платформой. Однако вам по-прежнему потребуется обработать некоторые аспекты управления окнами.

Общие сведения об управлении окнами и HWND функциональных возможностях см. в разделе Сведения о Windows.

Преимущества

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

  • Собственные и дочерние окна (например, меню и контекстные меню) автоматически масштабируются в соответствии с родительским HWND масштабированием приложения.

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

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

Недостатки

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

API-интерфейсы для размещения windowed

Список API-интерфейсов, которые можно использовать при настройке WebView2 для размещения Windowed (или размещения из Окна в visual), см. в разделе Отрисовка WebView2 в приложениях, отличных от платформы , в статье Обзор API WebView2.

Размещение из окна в визуальный интерфейс: для взаимодействия с размещением в windowsed с дополнительными преимуществами и компромиссами

Размещение из окна в визуальный элемент означает, что содержимое WebView2 выводится в визуальный элемент, размещенный в HWND, а не выводит содержимое в окно напрямую или непосредственно в визуальный элемент. Размещая содержимое в HWND, размещение из окна в визуальный элемент прост в использовании, так же, как и размещение Windowed. Но при отображении содержимого с помощью визуального элемента размещение из окна в визуальный элемент позволяет избежать некоторых проблем с DPI и вводом, которые могут возникнуть при использовании размещения Windowed.

Размещение из окна в visual не требует использования API-интерфейсов размещения Visual WebView2.

Чтобы включить размещение windows в visual, переменная COREWEBVIEW2_FORCED_HOSTING_MODE среды должна иметь значение COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL перед инициализацией WebView2.

При размещении между окнами и визуальными элементами визуальный элемент — это базовый графический блок, который можно использовать для создания графических интерфейсов в Windows. Графические API Windows, которые предоставляют эту функцию и относятся к WebView2: DirectComposition и Windows.UI.Composition. "Visual" в "Визуальном размещении" может быть любым из IDCompositionVisual, IDCompositionTargetили Windows.UI.Composition.Visual, которые являются визуальными элементами, которые предоставляются через DirectComposition API и Windows.UI.Composition . (В частности, используется IDCompositionVisual размещение из окна в визуальный элемент.) Видеть:

Преимущества

  • Различные приложения, которые совместно используют папку данных пользователя WebView2, могут иметь разную осведомленность о DPI.

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

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

  • При размещении WebView2 в надстройке VSTO изменение масштаба монитора потенциально не приведет к зависающему приложению. См. статью Общие сведения о надстройках VSTO в разработке решений Office (VSTO).

Недостатки

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

См. также:

API для размещения из окна в визуальный элемент

Список API-интерфейсов, которые можно использовать при настройке WebView2 Window для визуального размещения (или для размещения с windowsed), см. в разделе Отрисовка WebView2 в приложениях, отличных от платформы , в статье Обзор API WebView2.

Визуальное размещение: для более детального управления макетом

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

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

Требования к масштабированию содержимого

Для отрисовки на основе композиции элемент управления WebView2 является частью визуального дерева, поэтому по умолчанию он отображается в масштабе, основанном на масштабах всех его предков Visuals. Например, если визуальный элемент-предок WebView2 масштабируется (масштабируется) 2x, то содержимое WebView2 также отображается в 2-кратном масштабе. Если родительский визуальный элемент WebView2 масштабируется 2x, а родительский элемент этого визуального элемента также масштабируется 2x, то WebView2 масштабируется в 4x. Но так как WebView2 не масштабирует собственное содержимое, оно размыто.

Чтобы устранить эту проблему, приложение может отменить визуальное масштабирование WebView2 по умолчанию и вместо этого использовать API масштабирования растеризации для применения предполагаемого визуального масштабирования. Это приводит к отрисовке содержимого WebView2 в правильном масштабе. См. раздел Масштабирование растеризации в обзоре API WebView2.

Требования к маршрутизации пространственных входных данных (мышь, сенсорный ввод или перо)

Если приложение WebView2 использует визуальное размещение, в элемент управления WebView2 не отправляются пространственные входные данные (например, мышь, сенсорный ввод или перо), если только приложение не управляет такими входными данными. Входные данные отправляются в приложение HWND, и приложение отвечает за пересылку этих пространственных входных данных в WebView2, если входные данные расположены над WebView2.

Приложение также отвечает за любое необходимое преобразование входных позиций в пространство координат WebView2.

См. также:

Преимущества и недостатки

Визуальное размещение позволяет (и требует) более детализированного управления макетом. При использовании этого подхода приложению требуется конкретная обработка API управления окнами и отрисовки.

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

API для размещения визуальных элементов

Список API-интерфейсов, которые можно использовать при настройке WebView2 в среде размещения visual, см. в разделе Отрисовка WebView2 с помощью композициистатьи Обзор API WebView2.

Совместимость и ограничения

Основные ограничения совместимости включают операционную систему и отрисовку в приложениях, отличных от платформы.

Операционные системы

Все режимы размещения поддерживаются везде, где поддерживается WebView2.

См. также:

Ограничения платформы

CreateCoreWebView2CompositionControllerне поддерживает визуальные элементы WinAppSDK; то есть визуальные объекты в Microsoft.UI.Composition пространстве имен, описанные в разделе Улучшение пользовательского интерфейса с помощью визуального слоя (Windows App SDK или WinUI 3).

См. также

Внешний:

  • Last updated on