通过

WebView2 的窗口化与可视托管

  • 项目

有三个选项可用于在应用中托管 Microsoft Edge WebView2 控件：

  • 窗口化托管模式。
  • 窗口到视觉对象托管模式。
  • 视觉对象托管模式。

如果在大多数情况下使用窗口托管，则无需阅读本文。 窗口托管是大多数应用的良好起点。 阅读本文：

  • 如果在不常见的方案中使用窗口托管，并且遇到 DPI 和缩放方面的持续问题。 在这种情况下，请考虑窗口到视觉对象托管。
  • 如果要 (UX) 提供更自定义的用户体验。 在这种情况下，请考虑视觉对象托管。

在应用中托管 WebView2 控件的不同方法在功能上相似，但它们根据应用要求满足不同的需求，如下所示：

方法 说明 针对
窗口托管 WebView2 控件从操作系统 (操作系统) 接收输入。 OS 会将输入发送到 WebView2。 快速轻松地显示 Web 内容，而无需包括输入、输出和辅助功能。
窗口到视觉对象托管 窗口化和视觉对象托管的组合。 与窗口托管类似，只不过 WebView2 内容输出到托管在窗口中的视觉对象，而不是将内容直接输出到窗口。 开发人员体验几乎与窗口化托管相同，但改进了 DPI/缩放处理，并注意不支持 Windows Shell 手写体验。
视觉对象托管 主机应用从用户获取空间输入 (，例如鼠标或触摸输入) 。 应用将此输入发送到 WebView2 控件。 对控件组合进行更精细的控制。 应用需要对窗口管理和呈现 API 执行特定处理。

这些方法具有不同的要求、约束和优势。

  • 与视觉对象托管相比，窗口化托管的实现更简单。
  • 视觉对象托管需要窗口化托管所需的所有 API 调用，并且有其他要求才能正确呈现。

支持的 API 列表在以下部分中链接到：

窗口托管：用于快速轻松地显示内容

窗口托管 是指在应用中，WebView2 内容直接托管在窗口中;即 HWND。 WebView2 HWND 从操作系统 (OS) 继承许多默认属性。 WebView2 控件从 OS 获取输入，操作系统将输入发送到 WebView2 控件。 应用中可以有多个 HWND，每个 HWND 将用作 WebView2 组件来访问 Web 内容。

这样做的好处是，某些输入/输出命令由操作系统或框架处理。 但是，仍需要处理窗口管理的某些方面。

有关窗口管理和 HWND 功能的常规信息，请参阅 关于 Windows。

优点

  • 窗口托管允许解决方案快速显示 Web 内容，而无需实现输入、输出和辅助功能。

  • 自有窗口和子窗口 (（如菜单和上下文菜单）) 自动缩放以匹配应用的父 HWND 缩放。

  • 窗口托管处理 WebView2 控件在按 Tab 到达最后一个元素时如何管理焦点和选项卡进入或退出自身。

  • 如果不想要，无需管理各种基于合成的呈现控件 (，例如输入、输出和辅助功能控件) 。

缺点

在某些情况下，窗口托管模式可能会遇到 DPI 问题，例如，在共享用户数据文件夹 (以及跨具有不同 DPI 感知的不同应用程序共享浏览器进程) 。

用于窗口托管的 API

有关在配置 WebView2 用于窗口托管 (或窗口到视觉对象托管) 时可以使用的 API 列表，请参阅 WebView2 功能和 API 概述中的在非框架应用中呈现 WebView2。

窗口到视觉对象托管：与窗口托管类似的体验，具有额外的优势和权衡

窗口到视觉对象托管 意味着将 WebView2 内容输出到托管在 HWND 中的视觉对象，而不是直接将内容输出到窗口或直接输出到视觉对象。 通过在 HWND 中托管内容，窗口到视觉对象托管与窗口托管方式相同，易于使用。 但是，通过使用视觉对象显示内容，窗口到视觉对象托管可避免使用窗口托管时可能导致的一些 DPI 和输入问题。

窗口到视觉对象托管不需要使用 WebView2 视觉对象托管 API。

若要启用窗口到视觉对象托管，必须在初始化 WebView2 之前将环境变量 COREWEBVIEW2_FORCED_HOSTING_MODE 设置为 值 COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL 。

在窗口到视觉对象托管和视觉对象托管中， 视觉对象 是一个基本的图形单元，可用于在 Windows 上构成图形体验。 公开此功能且与 WebView2 相关的 Windows 图形 API 是 DirectComposition 和 Windows.UI.Composition。 “视觉对象托管”中的“视觉对象”可以是 、 IDCompositionTarget或 中的任何一个IDCompositionVisual，这些视觉对象是通过 DirectComposition 和 Windows.UI.Composition API 公开Windows.UI.Composition.Visual的。 (窗口到视觉对象托管专门使用 IDCompositionVisual 。) 请参阅：

优点

  • 共享 WebView2 用户数据文件夹的不同应用可以具有不同的 DPI 感知。

  • 共享 WebView2 用户数据文件夹的不同应用可以具有不同的完整性级别。

  • 共享 WebView2 用户数据文件夹的不同应用不会因为附加的窗口输入队列而导致彼此挂起。

  • 在 VSTO 外接程序中托管 WebView2 时，更改监视器规模不会导致应用挂起。 请参阅 Office 解决方案开发概述中的 VSTO 外接程序 (VSTO) 。

缺点

启用窗口到视觉对象托管模式会删除对 WebView2 中 Windows Shell 手写的支持。

另请参阅：

窗口到视觉对象托管的 API

有关在将 WebView2 窗口配置为视觉对象托管 (或窗口托管) 时可以使用的 API 列表，请参阅 WebView2 功能和 API 概述中的在非框架应用中呈现 WebView2。

视觉对象托管：更精细地控制布局

使用 视觉对象托管时，主机应用从用户接收空间输入 (，例如鼠标或触摸输入) ，并将此输入转发到 WebView2 控件。 可视化托管要求应用执行与窗口托管相同的窗口管理，但对以下方面有其他窗口管理要求：

  • 缩放内容。
  • 路由空间输入 (，例如鼠标、触摸或笔) 。

缩放内容的要求

根据基于合成的呈现，WebView2 控件是可视化树的一部分，因此默认情况下，它以基于其所有上级视觉对象的缩放比例呈现。 例如，如果 WebView2 的上级视觉对象缩放 (缩放) 2 倍，则 WebView2 的内容也会以 2 倍的比例呈现。 如果 WebView2 的父视觉对象缩放了 2 倍，并且该视觉对象的父视觉对象也缩放了 2 倍，则 WebView2 将缩放 4 倍。 但是，由于 WebView2 不缩放自己的内容，因此它们模糊不明确。

若要解决此问题，应用可以撤消 WebView2 的默认视觉缩放，并改用光栅化缩放 API 来应用预期的视觉缩放。 这会导致 WebView2 的内容以正确的比例呈现。 请参阅 WebView2 功能和 API 概述中的光栅化比例。

(鼠标、触摸或笔) 路由空间输入的要求

如果 WebView2 应用使用视觉对象托管，除非应用管理此类输入，否则不会将鼠标、触摸或笔) 等空间输入 (发送到 WebView2 控件。 输入将发送到应用的 HWND，如果输入的位置位于 WebView2 上，则应用负责将此空间输入转发到 WebView2。

应用还负责将输入位置转换为 WebView2 的坐标空间的任何必要转换。

另请参阅：

优缺点

可视化托管允许 (，并且需要) 更精细的布局控制。 使用此方法时，应用需要对窗口管理和呈现 API 进行特定处理。

例如，如果用户操作导致 WebView2 的可视化树缩放，则应用必须调整 WebView2 的比例，以便相对于其父视觉对象正确呈现。

视觉对象托管的 API

有关在视觉对象托管环境中配置 WebView2 时可以使用的 API 列表，请参阅 WebView2 功能和 API 概述中的使用合成呈现 WebView2。

兼容性和约束

主要兼容性限制包括操作系统以及框架和非框架应用中的呈现。

操作系统

支持 WebView2 的任何托管模式;即，Windows 10及更高版本，以及某些 Windows Server 版本。 不再支持 Windows 7、8 和 8.1;Windows 7 和 Windows 8 仅支持窗口托管，不支持视觉对象托管。

另请参阅：

框架约束

CreateCoreWebView2CompositionController不支持 WinAppSDK 视觉对象;即命名空间中的Microsoft.UI.Composition视觉对象，如使用视觉层增强 UI (Windows 应用 SDK/WinUI 3) 中所述。

另请参阅

外部：