WebView2 功能和 API 概述

在应用中嵌入 WebView2 控件可让应用访问通过 WebView2 类或接口提供的各种方法和属性。 WebView2 拥有数百个 API,提供大量功能,从增强应用的本机平台功能到使应用能够修改浏览器体验。 本文提供 WebView2 API 的高级分组,以帮助你了解可以使用 WebView2 执行的不同操作。

托管 WebView2 控件时,应用有权访问以下功能和 API:

功能区域 用途
主类:环境、控制器和核心 CoreWebView2Controller``CoreWebView2 (CoreWebView2Environment或等效接口的类) 协同工作,以便应用可以托管 WebView2 浏览器控件并访问其浏览器功能。 这些大型类公开了主机应用可以访问的各种 API,为用户提供以下类别的浏览器相关功能。
Web/本机互操作 将 Web 内容嵌入本机应用程序。 使用简单消息、JavaScript 代码和本机对象在本机代码和 Web 代码之间进行通信。
浏览器功能 WebView2 控件允许应用访问许多浏览器功能。 可以修改这些浏览器功能并将其打开或关闭。
进程管理 获取有关运行 WebView2 进程、退出进程和失败进程的信息,以便应用可以相应地采取措施。
导航到页面并管理已加载的内容 管理网页导航和管理网页中加载的内容。
iFrames 将其他网页嵌入到自己的网页中。 检测何时创建嵌入的网页、检测嵌入网页导航的时间,以及选择性地绕过 x 帧选项。
身份验证 应用可以使用 WebView2 控件处理基本身份验证。 基本身份验证 是属于 HTTP 协议的特定身份验证方法。
在非框架应用中呈现 WebView2 如果主机应用不使用 UI 框架,请使用这些 API 设置 WebView2 呈现系统。 此呈现设置控制 WebView2 如何将输出呈现到主机应用,以及 WebView2 如何处理输入、焦点和辅助功能。
使用合成呈现 WebView2 对于基于合成的 WebView2 呈现,请使用 CoreWebView2Environment 它来创建一个 CoreWebView2CompositionControllerCoreWebView2CompositionController 提供与之相同的 API CoreWebView2Controller,但也包括用于基于合成的呈现的 API。
用户数据 管理用户数据文件夹 (UDF) (即用户计算机上的文件夹)。 UDF 包含与主机应用和 WebView2 相关的数据。 WebView2 应用使用用户数据文件夹来存储浏览器数据,例如 Cookie、权限和缓存资源。
性能和调试 分析和调试性能、处理与性能相关的事件,以及管理内存使用情况,以提高应用的响应能力。
Chrome 开发人员协议 (CDP) 检测、检查、调试和配置文件Chromium浏览器。 Chrome DevTools 协议是 Microsoft Edge DevTools 的基础。 对于未在 WebView2 平台中实现的功能,请使用 Chrome DevTools 协议。

主类:环境、控制器和核心

CoreWebView2Controller``CoreWebView2 (CoreWebView2Environment或等效接口的类) 协同工作,以便应用可以托管 WebView2 浏览器控件并访问其浏览器功能。 这三个大类公开了主机应用可以访问的各种 API,为用户提供许多类别的浏览器相关功能。

  • CoreWebView2Environment 类表示一组 WebView2 控件,这些控件共享相同的 WebView2 浏览器进程、用户数据文件夹和呈现器进程。 在此类 CoreWebView2Environment 中,你将创建对 CoreWebView2ControllerCoreWebView2 实例。
  • CoreWebView2Controller 类负责托管相关功能,例如窗口焦点、可见性、大小和输入,应用在其中托管 WebView2 控件。
  • CoreWebView2 类适用于 WebView2 控件的特定于 Web 的部分,包括网络、导航、脚本以及分析和呈现 HTML。

另请参阅:

Web/本机互操作

Microsoft Edge WebView2 控件允许你将 Web 内容嵌入本机应用程序。 可以使用简单的消息、JavaScript 代码和本机对象在本机代码和 Web 代码之间进行通信。

一些常见用例包括:

  • 导航到其他网站后,更新本机主机窗口标题。
  • 从 Web 应用发送本机相机对象并使用其方法。
  • 在应用程序的 Web 端运行专用 JavaScript 文件。

有关详细信息,请参阅:

以下是用于在 Web 和本机代码之间通信的主要 API。

主机/Web 对象共享

WebView2 允许在本机代码中定义的对象传递到应用的 Web 端代码。 主机对象 是在本机代码中定义的任何对象,你选择将这些对象传递给应用的 Web 端代码。

主机对象可以投影到 JavaScript 中,以便可以从应用的 Web 端代码调用本机对象方法 (或其他 API) 。 例如,应用可以调用此类 API,因为用户在应用的 Web 端进行交互。 这样,就不需要在 Web 端代码中重新实现本机对象的 API,例如方法或属性。

脚本执行

允许主机应用在 WebView2 控件的 Web 内容中添加 JavaScript。

Web 消息传送

你的应用可以将消息发送到 WebView2 控件内的 Web 内容,并从该 Web 内容接收消息。 消息以字符串或 JSON 对象形式发送。

脚本对话框

托管 WebView2 时,应用可以管理不同的 JavaScript 对话框、禁止使用这些对话或将其替换为自定义对话框。

浏览器功能

WebView2 控件允许应用访问许多浏览器功能。 可以修改这些浏览器功能并将其打开或关闭。

打印

可以配置自定义打印设置并打印到 PDF。

Cookie

可以在 WebView2 中使用 Cookie 来管理用户会话、存储用户个性化首选项和跟踪用户行为。

另请参阅:

图像捕获

通过托管 WebView2,你的应用可以捕获屏幕截图并指示用于保存图像的格式。

下载

你的应用可以在 WebView2 中管理下载体验。 你的应用可以:

  • 允许或阻止基于不同元数据的下载。
  • 更改下载位置。
  • 配置自定义下载 UI。
  • 自定义默认 UI。
  • .NET/C#
  • WinRT/C#
  • Win32/C++

一般:

修改默认体验:

自定义下载体验:

权限

不同的网页可能会要求你获得访问某些特权资源的权限,例如地理位置传感器、照相机和麦克风。 主机应用可以以编程方式响应权限请求,并可将默认权限 UI 替换为其自己的 UI。

上下文菜单

WebView2 控件提供默认上下文菜单 (右键单击菜单) 可以自定义或禁用,还可以创建自己的上下文菜单。

另请参阅:

状态栏

状态栏位于页面左下角,显示正在显示的网页的状态。 在 WebView2 中,可以启用/禁用状态栏,获取状态栏中的文本,并了解状态栏文本何时更改。

User Agent

用户代理是一个字符串,代表代表用户的程序标识,例如浏览器名称。 在 WebView2 中,可以设置用户代理。

另请参阅:

自动填充

应用可以独立控制浏览器的自动填充功能是针对常规信息还是密码启用。

音频

你的应用可以静音和取消所有音频,并找出音频播放时间。

轻扫手势导航

通过托管 WebView2 控件,应用可以在启用触摸输入的设备上启用或禁用轻扫手势导航。 此手势允许最终用户:

  • 向左/向右轻扫 (水平轻扫) 导航到导航历史记录中的上一页或下一页。
  • 拉取以刷新 () 当前页面垂直轻扫。

此功能当前在浏览器中默认禁用。 若要在 WebView2 中启用此功能,请设置 AdditionalBrowserArguments 属性,指定 --pull-to-refresh 开关。

全屏

在 WebView2 中,可以找出 HTML 元素何时进入或离开全屏视图。

PDF 工具栏

在浏览器 PDF 查看器中,顶部有一个特定于 PDF 的工具栏。 在 WebView2 中,可以隐藏 PDF 查看器工具栏中的某些项。

主题

在 WebView2 中,可以将颜色主题自定义为系统、浅色或深色。

语言

可以设置适用于浏览器 UI ((如上下文菜单和对话) )的 WebView2 的默认显示语言,以及设置 accept-language WebView2 发送到网站的 HTTP 标头。

“新建”窗口

WebView2 提供用于处理 JavaScript 函数 window.open()的功能。

关闭窗口

WebView2 提供用于处理 JavaScript 函数 window.close()的功能。

文档标题

应用可以检测当前顶级文档的标题何时更改。

Favicon

在 WebView2 中,可以为网站设置 Favicon ,也可以在网站更改时收到通知。

进程管理

获取有关运行 WebView2 进程、退出进程和失败进程的信息,以便应用可以相应地采取措施。

通过 WebView2 控件,应用可以管理网页导航和管理网页中加载的内容。

管理加载到 WebView2 中的内容

这些 API 加载、停止加载内容并将内容重新加载到 WebView2。 加载的内容可以是:

  • URL 中的内容。
  • HTML 字符串。
  • 通过虚拟主机名到本地文件夹映射的本地内容。
  • 来自构造网络请求的内容。

历史记录方法允许在 WebView2 中进行后退和向前导航,历史记录事件提供有关历史记录和 WebView2 当前源中更改的信息。

阻止不需要的导航

NavigationStarting 事件允许应用取消导航到 WebView2 中的指定 URL,包括帧。

对于 NavigationStarting 其他导航事件,可以通知应用 WebView2 中的导航状态。 _导航_是加载新 URL 的过程。

另请参阅:

  • .NET/C#
  • WinRT/C#
  • Win32/C++

在 WebView2 中管理网络请求

WebResourceRequested 事件允许应用截获并覆盖 WebView2 中的所有网络请求。 该 WebResourceResponseReceived 事件允许应用监视发送到的请求以及从网络接收的响应。

另请参阅:

客户端证书

在 WebView2 中,可以使用客户端证书 API 在应用程序级别选择客户端证书。 使用此 API 可以:

  • 根据需要向用户显示 UI。
  • 替换默认的客户端证书对话提示。
  • 以编程方式查询证书。
  • 当 WebView2 向需要客户端证书进行 HTTP 身份验证的 HTTP 服务器发出请求时,从列表中选择证书以响应服务器。

服务器证书

在 WebView2 中,可以使用服务器证书 API 在应用程序级别信任服务器的 TLS 证书。 这样,主机应用就可以呈现页面,而无需提示用户出现 TLS 错误,或者主机应用可以自动取消请求。

iFrames

通过 iFrame,可以将其他网页嵌入到自己的网页中。 在 WebView2 中,可以:

  • 了解何时创建 iFrame。
  • 了解 iFrame 导航的时间。
  • 允许绕过 x 帧选项。

身份验证

应用可以使用 WebView2 控件处理基本身份验证。 基本身份验证 是属于 HTTP 协议的特定身份验证方法。

另请参阅:

在非框架应用中呈现 WebView2

如果主机应用不使用 UI 框架,请使用这些 API 设置 WebView2 呈现系统。 此呈现设置控制 WebView2 如何将输出呈现到主机应用,以及 WebView2 如何处理输入、焦点和辅助功能。

  • UI 框架 - 如果使用的是应用的 UI 框架,则应使用该 UI 框架提供的 WebView2 元素,而不是使用这些 API。

  • 没有 UI 框架,也不使用 Composition - 例如,如果你未对应用使用 UI 框架 (例如,如果使用纯 Win32 直接) ,或者 UI 框架没有 WebView2 元素,则需要使用本部分中的这些 API 创建 CoreWebView2Controller 并将其呈现到应用中。

  • 没有 UI 框架,并且使用合成 - 如果应用 UI 是使用 DirectCompositionWindows.UI.Composition 生成的,则应使用 CoreWebView2CompositionController 而不是使用这些 API;请参阅下面 的“使用合成呈现 WebView2”。

调整大小、定位和可见性

CoreWebView2Controller 采用父 HWND级。 相对 Bounds 于父 HWND级的属性大小和位置 WebView2。 可以使用 IsVisibleWebView2 的可见性进行切换。

缩放

WebView2 ZoomFactor 用于仅缩放窗口的 Web 内容。 当用户通过在旋转鼠标滚轮时按 Ctrl 下缩放内容时,UI 缩放也会更新。

光栅化规模

RasterizationScale API 缩放所有 WebView2 UI,包括上下文菜单、工具提示和弹出窗口。 应用可以设置 WebView2 是否应检测监视规模更改并自动更新 RasterizationScale。 BoundsMode 用于配置 Bounds 属性是解释为原始像素,还是将需要由 RasterizationScale) 缩放的 DIP (。

焦点和制表

WebView2 控件会引发事件,让应用知道控件何时获得焦点或失去焦点。 对于制表 (按 Tab 键) ,有一个 API 要将焦点移到 WebView2 中,还有一个 WebView2 事件用于请求应用重新获取焦点。

父窗口

WebView2 可以重新向不同的父窗口句柄 () HWND 。 当应用在屏幕上的位置发生更改时,还需要通知 WebView2。

键盘加速键

当 WebView2 具有焦点时,它会直接接收来自用户的输入。 应用可能想要截获和处理某些加速器键组合,或禁用正常的浏览器加速器键行为。

默认背景色

WebView2 可以指定默认背景色。 颜色可以是任何不透明的颜色,也可以是透明的。 如果 HTML 页面未设置其自己的背景色,则将使用此颜色。

使用合成呈现 WebView2

对于基于合成的 WebView2 呈现,请使用 CoreWebView2Environment 它来创建一个 CoreWebView2CompositionControllerCoreWebView2CompositionController 提供与之相同的 API CoreWebView2Controller,但也包括用于基于合成的呈现的 API。

连接到可视化树

WebView2 可以将其合成树连接到 IDCompositionVisualIDCompositionTargetWindows::UI::Composition::ContainerVisual

转发输入

应用程序接收 (鼠标、触摸、笔) 的空间输入,必须发送到 WebView2。 当光标应基于鼠标位置进行更新时,WebView2 会通知应用。

辅助功能

默认情况下,对于 Win32/C++ 应用,WebView2 将作为父 HWND 的子级显示在辅助功能树中。 WebView2 提供 API,以便更好地定位相对于应用程序中其他元素的 WebView2 内容。

用户数据

管理用户数据文件夹 (UDF) (即用户计算机上的文件夹)。 UDF 包含与主机应用和 WebView2 相关的数据。 WebView2 应用使用用户数据文件夹来存储浏览器数据,例如 Cookie、权限和缓存资源。

另请参阅:

性能和调试

分析和调试性能、处理与性能相关的事件,以及管理内存使用情况,以提高应用的响应能力。

Chrome 开发人员协议 (CDP)

Chrome DevTools 协议提供用于检测、检查、调试和配置文件Chromium浏览器的 API。 Chrome DevTools 协议是 Microsoft Edge DevTools 的基础。 对于未在 WebView2 平台中实现的功能,请使用 Chrome DevTools 协议。

另请参阅:

另请参阅