WebView2 触发事件说明
WebView2 封装组件 事件详解
包含触发时机、触发原因、事件内可执行操作、业务应用场景，按功能分类整理
一、按键与焦点类事件
1. OnAcceleratorKeyPressed 快捷键按键按下
触发原因
按下键盘快捷键、普通按键、系统按键时实时触发，包含按键按下、抬起两类动作。
可执行操作
- 判定按键类型、虚拟键码，自定义快捷键逻辑
- 赋值
Handled=True拦截按键，屏蔽浏览器默认按键行为 - 读取按键状态、重复次数，处理长按按键
适用场景自定义全局快捷键、禁用 F5 刷新、拦截全屏按键、自定义页面操作热键
2. OnMoveFocusRequested 焦点切换请求
触发原因
代码、Tab 键、方向键触发控件焦点跳转时触发。
可执行操作
- 判断焦点切换来源，拦截非法焦点跳转
- 自定义焦点跳转顺序与目标控件
- 赋值
Handled=True取消本次焦点切换适用场景表单焦点管控、禁止页面抢占窗体焦点、自定义 Tab 切换逻辑
3. OnGotFocus / OnLostFocus 获得 / 失去焦点
触发原因
WebView 控件被选中激活、鼠标点击其他区域失去激活状态。
可执行操作
- 控件激活时刷新页面、恢复音频播放
- 失去焦点暂停音视频、保存页面临时数据
适用场景窗口激活状态监听、后台暂停播放、前台恢复交互
二、页面导航与加载类事件
1. OnNavigationStarting 导航开始
触发原因
点击链接、地址跳转、JS 跳转、重定向、手动刷新，即将加载新页面。
可执行操作
- 读取目标访问地址、请求头、判断是否用户手动跳转
- 设置
Cancel=True拦截本次跳转，禁止访问指定网址 - 获取框架溯源地址，拦截嵌套恶意页面
适用场景网址黑白名单、拦截广告跳转、跳转前权限校验
2. OnNavigationCompleted 导航完成
触发原因
页面加载结束，成功打开或访问失败均会触发。
可执行操作
- 判断导航成功状态，捕获证书、网络、域名解析错误
- 获取 HTTP 状态码，处理 404、500 异常页面
- 页面加载完毕后自动执行 JS、填充初始数据
适用场景页面初始化、错误页面兜底提示、加载结果日志记录
3. OnContentLoading 内容开始加载
触发原因
页面资源开始解析渲染，页面骨架开始加载。
可执行操作
- 判断是否错误页面，提前展示加载占位界面
- 记录导航编号，区分多页面并发加载
适用场景加载动画展示、页面加载状态标识
4. OnDomContentLoaded DOM 树加载完成
触发原因
页面 HTML 结构解析完毕，图片、样式等资源未完全加载。
可执行操作
- DOM 就绪后立即执行交互脚本、读取页面元素
- 注入全局 JS 函数、初始化页面交互逻辑
适用场景早期页面元素操作、JS 前置交互
5. OnSourceChanged 页面源码变更
触发原因
页面刷新、AJAX 局部刷新、文档替换导致页面源码变动。
可执行操作
- 监听页面内容篡改、局部数据更新
- 重新读取页面最新源码与元素信息
适用场景页面内容监控、局部刷新数据捕获
6. OnHistoryChanged 浏览历史变更
触发原因
前进、后退、新页面跳转，浏览器历史记录栈发生变化。
可执行操作
- 监听历史步数，自定义前进后退按钮状态
- 拦截非法历史跳转、记录浏览轨迹
适用场景自定义导航栏按钮、浏览历史统计
三、脚本与弹窗消息类事件
1. OnWebMessageReceived 接收网页消息
触发原因
网页 JS 调用
可执行操作
postMessage向 Delphi 端推送文本、JSON 数据。
- 解析文本 / JSON 消息，执行业务逻辑
- 接收页面指令，调用本地窗体、文件、硬件接口
- 回复消息给网页，实现双向通信
适用场景前后端交互、页面调用本地功能、数据双向传输
2. OnScriptDialogOpening JS 弹窗弹出
触发原因
网页调用 alert、confirm、prompt、页面卸载弹窗。
可执行操作
- 拦截原生弹窗，替换为自定义窗体弹窗
- 修改弹窗提示内容、预设输入默认值
- 自定义确认 / 取消结果，控制页面逻辑
适用场景弹窗样式美化、恶意弹窗屏蔽、输入数据拦截
3. OnException 组件内部异常
触发原因
接口调用失败、内核报错、脚本错误、内存异常。
可执行操作
- 捕获异常信息，记录错误日志
- 异常兜底处理，避免程序崩溃
- 异常后重置 WebView 状态
适用场景程序容错、错误上报、故障恢复
四、菜单与窗口类事件
1. OnContextMenuRequested 右键菜单弹出
触发原因
鼠标右键点击页面空白、图片、文本、链接等区域。
可执行操作
- 清空默认菜单，自定义新增、删除、修改菜单项
- 判断点击目标类型，差异化展示菜单
- 设置
Handled=True彻底屏蔽右键菜单 - 监听菜单点击命令，执行对应功能
适用场景自定义右键功能、禁止复制截图、按需展示菜单
2. OnNewWindowRequested 新建窗口请求
触发原因
页面点击新开标签、弹窗 JS、target=_blank 跳转新窗口。
可执行操作
- 拦截默认弹窗，禁止恶意广告弹窗
- 接管新窗口请求，在本控件内加载新页面
- 创建自定义 WebView 实例承载新窗口
- 获取窗口尺寸属性，控制弹窗大小位置
适用场景弹窗管控、单页面内打开新链接、多窗口管理
3. OnWindowCloseRequested 窗口关闭请求
触发原因
网页 JS 调用关闭窗口指令、页面主动关闭。
可执行操作
- 拦截关闭动作，弹窗二次确认
- 关闭前保存页面数据、释放资源
适用场景关闭校验、数据留存、资源释放
4. OnFullScreenChanged 全屏状态变更
触发原因
页面进入全屏、退出全屏模式切换。
可执行操作
- 同步窗体全屏状态，适配界面布局
- 全屏时隐藏工具栏，退出恢复界面
适用场景视频全屏适配、界面布局动态调整
5. OnDocumentTitleChanged 页面标题变更
触发原因
页面加载完成、JS 修改标题、跳转页面更新标题。
可执行操作
- 同步窗体标题为网页标题
- 监控标题关键字，识别指定页面
适用场景窗体标题同步、页面识别标记
6. OnFaviconChanged 网站图标变更
触发原因
页面加载完毕、切换页面后站点图标更新。
可执行操作
- 提取图标数据，设置窗体图标
适用场景窗体图标同步站点 logo
7. OnStatusBarTextChanged 状态栏文本变更
触发原因
鼠标悬浮链接、页面加载进度，状态栏提示文字刷新。
可执行操作
- 读取状态文本，自定义状态栏展示内容
适用场景自定义底部状态提示栏
8. OnMutedChanged / OnPlayingAudioChanged 音频状态变更
触发原因
页面播放 / 暂停音视频、静音开关切换。
可执行操作
- 同步静音状态、音频播放状态
- 全局管控页面音频播放，批量静音
适用场景多媒体状态监控、静音快捷控制
9. OnZoomChanged 页面缩放变更
触发原因
手动缩放页面、代码修改缩放比例。
可执行操作
- 记录缩放比例，同步缩放控件界面
- 限制最大最小缩放范围
适用场景缩放状态同步、缩放权限管控
五、安全认证与证书类事件
1. OnServerCertificateError 服务器证书错误
触发原因
证书过期、域名不匹配、证书吊销、无效证书等安全异常。
可执行操作
- 读取证书详细信息，校验证书合法性
- 选择允许访问、拒绝访问、系统默认处理
- 拦截危险证书站点，规避网络风险
适用场景内网证书兼容、危险网站拦截、证书异常兜底
2. OnClientCertificateRequested 客户端证书请求
触发原因
网站要求客户端上传数字证书完成身份认证。
可执行操作
- 遍历本地可用证书，筛选合法证书
- 手动指定提交证书、取消证书认证
- 自定义证书选择弹窗，替代系统选择框
适用场景政务 / 网银证书登录、自动证书匹配认证
3. OnBasicAuthenticationRequested 基础账号认证
触发原因
网站弹出账号密码认证框，HTTP 基础认证。
可执行操作
- 自动填充预设账号密码，免手动登录
- 取消认证拒绝访问，弹窗手动录入账号
适用场景内网密码站点自动登录、认证拦截管控
4. OnPermissionRequested 权限申请请求
触发原因
网页申请摄像头、麦克风、定位、剪贴板、文件读写等权限。
可执行操作
- 判断权限类型与访问网址，批量允许 / 拒绝权限
- 统一权限策略，禁止隐私权限非法调用
适用场景隐私权限管控、摄像头定位权限拦截
六、网络资源拦截类事件
1. OnWebResourceRequested 资源请求发起
触发原因
页面加载图片、脚本、样式、接口、视频、WebSocket 等所有网络资源。
可执行操作
- 拦截指定格式资源，屏蔽广告图片、恶意脚本
- 修改请求地址、请求头、请求参数，篡改网络请求
- 本地构造自定义响应，替换远程资源内容
适用场景广告屏蔽、接口抓包篡改、本地资源代理
2. OnWebResourceReceived 资源接收完成
触发原因
网络资源请求响应结束，数据返回页面。
可执行操作
- 读取响应状态码、响应头、返回内容
- 统计资源加载耗时，排查网络异常
适用场景网络日志统计、异常资源检测
七、进程与崩溃类事件
1. OnBrowserProcessExited 浏览器进程退出
触发原因
浏览器主进程正常关闭、异常终止。
可执行操作
- 判断退出是否异常，记录崩溃进程 ID
- 进程退出后释放占用资源、重置控件
适用场景进程生命周期监控、异常退出重启恢复
2. OnProcessFailed 子进程异常崩溃
触发原因
渲染进程、GPU 进程、插件进程卡死、崩溃、内存溢出。
可执行操作
- 识别崩溃进程类型与崩溃原因
- 捕获退出错误码，上报崩溃日志
- 执行页面重载、控件重启恢复服务
适用场景程序稳定性保障、崩溃故障修复、异常上报
3. OnProcessInfosChanged 进程列表变更
触发原因
浏览器新建子进程、销毁子进程。
可执行操作
- 实时监控进程数量与类型
- 管控进程资源占用，避免内存溢出
适用场景进程资源监控、内存优化
4. OnNewVersionAvailable 内核新版本可用
触发原因
检测到本地存在更高版本 WebView2 运行时。
可执行操作
- 弹窗提示用户升级内核版本
- 静默切换高版本内核运行
适用场景版本升级提醒、内核版本兼容适配
八、下载相关事件
OnDownloadStarting 下载任务开始
触发原因
点击文件下载链接，触发下载任务初始化。
可执行操作
- 拦截非法文件下载、限制危险格式文件
- 修改文件默认保存路径、重命名下载文件
- 自定义下载弹窗，替换系统下载界面
适用场景下载权限管控、文件自动归类、恶意下载拦截
OnDownloadDialogOpenChanged 下载弹窗状态变更
触发原因
下载弹窗打开、关闭状态切换。
可执行操作
- 弹窗弹出时调整位置、样式
- 关闭弹窗后清理下载临时数据
浙公网安备 33010602011771号