WebView2 5.7 帮助说明

WebView2 封装组件 API 参考文档

文档版本：V1.0
 
适配内核：Microsoft WebView2
 
最低运行版本：111.0.1661.44
 

目录

  1. 文档概述
  2. 基础异常与全局定义
  3. 枚举类型全集
  4. 结构体与集合类型
  5. 核心接口详细说明
  6. 核心控件 TWebView
  7. 全部事件参数详解
  8. 网络请求响应封装类
  9. 开发实用示例
  10. 错误码对照表

1 文档概述

1.1 组件简介

本组件为封装的 WebView2 浏览器内核控件，继承自TGraphicControl，可嵌入 Windows 窗体应用，实现网页加载、JS 双向交互、Cookie 管理、打印 PDF、网络拦截、证书认证、自定义菜单、权限管控等全套浏览器能力。

1.2 运行环境

  • 操作系统：Windows 10 / Windows 11
  • 依赖库：WebView2Loader.dll
  • 最低浏览器内核：111.0.1661.44

1.3 开发须知

所有接口基于原生 WebView2 COM 接口二次封装，兼容原生全部能力；事件支持回调与匿名委托两种写法；路径、中文、特殊字符自动适配处理。

2 基础异常与全局定义

2.1 自定义异常类

delphi
 
 
EWebViewError = class(Exception);
 
说明：组件内部所有运行错误统一抛出此异常，用于捕获浏览器内核、接口调用异常。

2.2 全局常量

delphi
 
 
RequiredBrowserVersion = '111.0.1661.44';
 
含义：组件强制要求的最低 WebView2 运行时版本。

2.3 全局变量

表格
 
变量名类型说明
LibraryName string 默认加载库文件名 WebView2Loader.dll
WebViewLibrary HMODULE WebView 库模块句柄

2.4 全局公共函数

  1. function Loaded: Boolean
     
    判断 WebView 库是否成功加载
  2. procedure LoadLibrary
     
    手动加载 WebView2 依赖库
  3. procedure UnloadLibrary
     
    释放已加载的内核库
  4. function GetBrowserVersion(const BrowserFolder: string = ''): string
     
    获取本地已安装 WebView 浏览器版本号
  5. function BrowserAvailable(const BrowserFolder: string = ''): Boolean
     
    检测当前环境是否满足组件运行条件

3 枚举类型全集

3.1 按键相关枚举

TKeyEventKind

按键事件类型
  • keKeyDown：按键按下
  • keKeyUp：按键抬起
  • keSystemKeyDown：系统按键按下
  • keSystemKeyUp：系统按键抬起

TBoundsMode

画布像素模式
  • bmRasterizationScale：缩放适配像素
  • bmRawPixels：原始物理像素

3.2 导航与错误枚举

TWebError

网页访问错误类型
 
weUnknown 未知错误、证书类错误、超时、连接中断、域名解析失败、代理认证错误等

TMoveFocusReason

焦点切换原因
  • frProgrammatic：代码主动切换
  • frNext：向后切换焦点
  • frPrevious：向前切换焦点

3.3 证书与权限枚举

TCertificateKind

客户端证书类型
  • ckSmartCard：智能卡证书
  • ckPin：密钥证书
  • ckOther：其他类型证书

TPermissionKind

网页权限申请类型
 
麦克风、摄像头、定位、通知、剪贴板、文件读写、自动播放、字体访问等

TPermissionState

权限授权状态
  • psDefault：系统默认处理
  • psAllow：允许权限
  • psDeny：拒绝权限

3.4 下载相关枚举

TDownloadState

下载任务状态
  • dsInProgress：下载进行中
  • dsInterrupted：下载中断暂停
  • dsCompleted：下载完成

TDownloadInterruptReason

下载中断原因
 
文件权限、磁盘空间、网络异常、服务器错误、用户取消、进程崩溃等

TDownloadDialogCornerAlignment

下载弹窗停靠位置
 
四角方位对齐模式

3.5 打印相关枚举

TPrintOrientation

打印方向
  • poPortrait：纵向打印
  • poLandscape：横向打印

TPrintColorMode

色彩模式
  • cmDefault：默认
  • cmColor：彩色
  • cmGrayscale：灰度打印

TPrintDuplex

双面打印模式
 
单面、长边双面、短边双面

TPrintCollation

分页整理模式

TPrintMediaSize

纸张尺寸类型

TPrintStatus

打印结果状态

3.6 菜单与页面枚举

TContextMenuItemKind

右键菜单项类型
 
命令、复选框、单选框、分隔线、子菜单

TContextMenuTargetKind

右键点击目标类型
 
页面、图片、选中文本、音频、视频

3.7 进程与行为枚举

TProcessKind

浏览器子进程类型
 
主进程、渲染进程、GPU 进程、插件进程等

TProcessFailedKind

进程异常退出类型

TProcessFailedReason

进程崩溃终止原因

TBrowsingDataKind

浏览数据清理类型
 
缓存、Cookie、历史记录、本地存储、密码记录等

TColorScheme

页面主题配色
  • csAuto：跟随系统
  • csLight：浅色模式
  • csDark：深色模式

TTrackingPreventionLevel

隐私防护等级
 
关闭、基础、均衡、严格防护

TResourceAccess

资源访问控制策略
 
允许、拒绝、拒绝跨域

TSameSite

Cookie 跨站策略
 
None、Lax、Strict

TDialogKind

JS 弹窗类型
 
警告框、确认框、输入框、页面卸载提示

TWebResource

网页资源请求类型
 
文档、样式、图片、脚本、音视频、接口请求、WebSocket 等

TFaviconFormat

图标格式：PNG、JPEG

TCapturePreviewFormat

页面截图格式：PNG、JPEG

4 结构体与集合类型

4.1 TKeyStatus 按键状态信息

表格
 
成员类型说明
RepeatCount Cardinal 按键重复次数
ScanCode Cardinal 键盘扫描码
ExtendedKey Boolean 是否扩展按键
MenuKeyDown Boolean 菜单键按下标记
KeyDown Boolean 按键按下状态
KeyReleased Boolean 按键抬起状态

4.2 THeader / THeaders HTTP 请求头

delphi
 
 
THeader = record
  Name: string;
  Value: string;
end;
THeaders = array of THeader;
 

4.3 TProcessInfo 进程信息

记录子进程 ID 与进程类型

4.4 数组集合定义

  • IContextMenuItems = array of IContextMenuItem
  • TCookies = array of ICookie
  • TClientCertificates = array of IClientCertificate

5 核心接口详细说明

5.1 ICertificate 服务器证书接口

只读获取服务器证书全部信息
表格
 
属性访问权限说明
Certificate 只读 原生 WebView 证书对象
DisplayName 只读 证书显示名称
Issuer 只读 证书颁发机构
IssuerChain 只读 完整证书颁发链
Pem 只读 PEM 格式证书文本
SerialNumber 只读 证书序列号
Subject 只读 证书主体信息
ValidFrom 只读 证书生效时间
ValidTo 只读 证书过期时间

5.2 IClientCertificate 客户端证书接口

客户端证书选择使用，继承基础证书字段，扩展证书类型标识

5.3 IContextMenuItem 右键菜单项

属性

勾选状态、子菜单集合、命令 ID、启用状态、图标数据、菜单类型、显示文本、名称、快捷键

事件

OnSelected：菜单项点击触发事件

5.4 IContextMenuItemCollection 菜单集合

方法：插入菜单项、删除菜单项
 
属性：菜单总数、索引读取菜单项

5.5 IContextMenuTarget 右键点击目标

获取点击位置所属页面、链接、图片、选中文本、框架地址、是否可编辑等信息

5.6 ICookie Cookie 操作接口

可读可修改 Cookie 名称、值、域名、路径、过期时间、HttpOnly、Secure、跨站策略、会话标记

5.7 IDownload 下载任务接口

方法

Cancel 取消下载、Pause 暂停、Resume 恢复下载

属性

可恢复状态、文件路径、文件类型、已下载大小、总大小、下载状态、中断原因

事件

进度变更、状态变更、预估完成时间变更

5.8 IFrame 网页框架接口

框架内注入宿主对象、发送网页消息、二进制数据传递、移除注入对象；读取框架名称、销毁状态

5.9 IPrintSettings 打印配置接口

份数、色彩、双面打印、纸张边距、纸张尺寸、横竖方向、页眉页脚、背景打印、缩放比例、页码范围、打印机名称等全量打印参数

5.10 ISharedBuffer 共享内存缓冲区

高效二进制数据交互，支持关闭缓冲区、获取大小、内存指针

5.11 IWindowFeatures 新窗口特性

读取新窗口尺寸、坐标、菜单栏、滚动条、状态栏、工具栏显示状态

6 核心控件 TWebView

继承关系：TWebView = class(TGraphicControl)
 
窗体可视浏览器核心控件

6.1 公共方法分类

页面导航

Navigate 跳转地址、ShowHtml 加载源码、Back 后退、Forward 前进、Refresh 刷新、Stop 停止加载

脚本交互

ExecuteScript 执行 JS、AddScript 注入全局脚本、PostWebMessage 双向消息通信、共享数据传递

Cookie 管理

创建、新增、删除、清空、查询站点 Cookie

打印导出

普通打印、弹出打印对话框、导出 PDF 文件、创建打印配置实例

菜单与截图

创建自定义右键菜单、页面截图保存

网络与权限

自定义协议、资源请求拦截、授权状态设置、主机目录映射

调试工具

打开开发者工具、调用 DevTools 协议接口

生命周期

进程暂停、恢复、关闭下载弹窗、窗口焦点控制

6.2 运行时属性

页面地址、页面标题、缩放比例、UA 标识、主题模式、导航前进后退可用性、静音状态、全屏状态、脚本开关、右键菜单开关、下载目录、内核版本、进程信息等

6.3 设计期发布属性

设计器可直接配置：激活状态、数据存储目录、隐私无痕模式、浏览器程序路径、语言、缩放、跟踪防护、启动参数等

7 全部事件参数详解

7.1 TAcceleratorKeyPressedEvent 快捷键按下

delphi
 
 
procedure(Sender: TObject; Kind: TKeyEventKind; VirtualKey: Cardinal; LParam: Integer; const Status: TKeyStatus; var Handled: Boolean)
 
  • Sender：触发控件实例
  • Kind：按键事件类型
  • VirtualKey：系统虚拟键码
  • LParam：窗口消息原始参数
  • Status：按键详细状态结构体
  • Handled：赋值 True 拦截按键，内核不再处理

7.2 TAddScriptCompletion 脚本注入完成

  • Sender：控件
  • ScriptID：注入脚本唯一标识

7.3 TBasicAuthenticationRequestedEvent 基础账号认证

  • Uri：认证请求地址
  • Challenge：认证质询信息
  • Cancel：是否取消访问
  • UserName、Password：自定义填入账号密码

7.4 TBrowserProcessExitedEvent 浏览器进程退出

  • Process：退出进程 ID
  • FailedExit：True = 异常退出，False = 正常关闭

7.5 TClientCertificateRequestedEvent 客户端证书请求

  • Host、Port：目标服务器地址端口
  • IsProxy：是否代理认证
  • Cancel：取消证书请求
  • Handled：自定义处理标记
  • Authorities：可信证书颁发机构列表
  • Certificates：本地可用证书数组
  • SelectedCertificate：最终选定提交证书

7.6 TContentLoadingEvent 内容开始加载

  • IsErrorPage：是否错误页面
  • NavigationId：本次导航唯一 ID

7.7 TContextMenuRequestedEvent 右键菜单弹出

  • MenuItems：可编辑菜单集合
  • Location：鼠标点击坐标
  • Target：点击页面目标对象
  • SelectedCommand：菜单执行命令 ID
  • Handled：True 屏蔽系统默认右键菜单

7.8 TDomContentLoadedEvent DOM 加载完成

  • NavigationId：所属导航编号，页面 DOM 树构建完毕触发

7.9 TExceptionEvent 组件异常捕获

  • Exception：捕获到的异常实例

7.10 TMoveFocusRequestedEvent 焦点切换请求

  • Reason：焦点切换原因
  • Handled：拦截焦点跳转

7.11 TNavigationCompletedEvent 导航结束

  • Success：导航成功与否
  • WebError：错误类型枚举
  • NavigationId：导航编号
  • HttpStatusCode：HTTP 响应状态码

7.12 TNavigationStartingEvent 开始导航

  • Uri：目标跳转地址
  • UserInitiated：是否用户手动点击
  • Redirected：是否重定向请求
  • RequestHeaders：请求头集合
  • Cancel：True 终止本次跳转
  • FrameAncestors：嵌套框架溯源地址

7.13 TNewWindowRequestedEvent 新建弹窗请求

  • Uri：新窗口地址
  • Name：窗口名称
  • NewWindow：自定义内核实例承载弹窗
  • Features：窗口样式尺寸属性
  • Handled：拦截默认弹窗

7.14 TPermissionRequestedEvent 权限申请

  • Uri：申请权限页面
  • PermissionType：权限类型
  • UserInitiated：用户主动申请标记
  • State：设置允许 / 拒绝 / 默认

7.15 TProcessFailedEvent 进程崩溃异常

  • Kind：异常进程类型
  • Reason：崩溃原因
  • ExitCode：进程退出错误码
  • ProcessDescription：进程描述

7.16 TScriptDialogOpeningEvent JS 弹窗弹出

  • Uri：弹窗所属页面
  • Kind：弹窗类型
  • Message：弹窗提示文字
  • DefaultText：输入框默认内容
  • ResultText：自定义返回输入内容
  • Accept：确认 / 取消弹窗

7.17 TServerCertificateErrorEvent 服务器证书错误

  • Status：证书错误类型
  • RequestUri：访问地址
  • Certificate：错误证书信息
  • Action：允许访问 / 拒绝 / 默认处理

7.18 TWebMessageReceivedEvent 网页消息接收

  • Source：消息来源
  • Message：普通文本消息
  • Json：JSON 结构化消息

7.19 TWebResourceRequestedEvent 资源请求拦截

  • Request：请求对象，可修改地址、请求头、请求体
  • Response：自定义返回响应数据
  • Deferred：延迟处理请求标记

7.20 TWebResourceReceivedEvent 资源接收完成

  • Request：原始请求信息
  • Response：页面最终响应数据
其余状态变更类事件（标题、图标、全屏、音频、缩放、窗口关闭）仅携带触发控件实例，无额外业务参数。

8 网络请求响应封装类

8.1 TWebResourceRequest 网络请求构造类

方法：判断请求头、移除请求头
 
属性：请求地址、请求方法、请求头、请求体、原生请求对象

8.2 TWebResourceResponse 自定义响应构造

方法：追加响应头、判断头部存在
 
属性：状态码、原因短语、响应头、响应数据流

8.3 TWebResourceResponseView 只读响应读取

仅读取页面返回数据、头部、状态码，支持异步获取二进制内容

9 开发实用示例

  1. 基础网页加载：赋值 Uri 或调用 Navigate 访问网址
  2. Delphi 与 JS 双向通信：PostWebMessage 发送，OnWebMessageReceived 接收
  3. Cookie 操作：增删查改站点 Cookie，适配登录态保存
  4. 自定义右键菜单：拦截菜单事件，增删自定义菜单项
  5. 网页打印 & 导出 PDF：调用打印方法，配置打印参数生成 PDF 文件
  6. 网络拦截篡改：拦截请求，修改请求头、替换响应内容
  7. 客户端证书适配：监听证书请求事件，自动选择本地证书
  8. 权限管控：拦截权限申请，统一授权策略

10 错误码对照表

  1. 网页错误枚举释义：证书错误、网络超时、连接失败、域名解析失败等对应中文说明
  2. 下载中断原因：文件、网络、服务器、用户操作、进程异常分类解读
  3. 进程失败原因：各类子进程崩溃、退出场景说明
posted @ 2026-05-22 10:19  sensorwu  阅读(28)  评论(0)    收藏  举报