VB6 PRO DOCS

中文

English

中文

English

Appearance

cWebView2Host 事件参考 ​

📋 事件总览 ​

cWebView2Host 提供 40+ 个事件，覆盖 WebView2 全生命周期。使用事件需以 WithEvents 声明变量：

vb
Dim WithEvents wv As cWebView2Host

事件分类索引 ​

分类事件触发时机
生命周期CreateWebView2 控件创建完成
Ready首次导航完成，控件就绪
Error创建或运行时发生错误
导航NavigationStarting导航开始（可取消）
NavigationComplete导航完成
SourceChangedURL 发生变化
DocumentTitleChanged文档标题变化
DOMContentLoadedDOM 加载完成
权限/对话框PermissionRequested页面请求权限
ScriptDialogOpening脚本对话框弹出（alert/confirm/prompt）
AcceleratorKeyPressed快捷键按下
NewWindowRequested页面请求打开新窗口
资源WebResourceRequestedWeb 资源请求被拦截
ProcessFailed浏览器进程失败
DownloadStarting下载即将开始
脚本JsAsyncResult异步脚本执行完成
JsMessage收到 JS postMessage
DevToolsProtocolResponseCDP 异步响应
宿主鼠标HostMouseDown宿主区域鼠标按下
HostMouseUp宿主区域鼠标释放
HostMouseDblClick宿主区域鼠标双击
HostMouseMove宿主区域鼠标移动
HostMouseWheel宿主区域鼠标滚轮
HostContextMenu宿主区域右键菜单
宿主键盘HostKeyDown宿主区域按键按下
HostKeyUp宿主区域按键释放
HostKeyPress宿主区域按键输入
HostFocusWebView2 获得焦点
HostBlurWebView2 失去焦点
HostResize宿主窗口大小变化
用户鼠标UserMouseDown内容区域鼠标按下
UserMouseUp内容区域鼠标释放
UserMouseMove内容区域鼠标移动
UserMouseWheel内容区域鼠标滚轮
UserContextMenu内容区域右键菜单
UserDblClick内容区域鼠标双击
挂起SuspendCompleted挂起成功
SuspendFailed挂起失败
PDFPrintToPdfCompletedPDF 打印成功
PrintToPdfFailedPDF 打印失败
业务OnGetCookiesFull异步 Cookie 获取完成

🔄 生命周期事件 ​

Create ​

WebView2 控件创建完成，但尚未开始导航。

vb
Private Sub wv_Create()

触发时机: WebView2 Environment 和 Controller 创建成功后。

用途: 这是配置 EnvironmentOptions 和 Security 的正确时机，因为此时环境已创建但导航尚未开始。

示例:

vb
Private Sub wv_Create()
    ' 配置用户数据目录
    wv.EnvironmentOptions.UserDataFolder = App.Path & "\UserDir\account-001"
    ' 配置安全选项
    wv.Security.CertificateErrorAction = CEA_AlwaysAllow
End Sub

Ready ​

WebView2 首次导航完成，控件完全就绪。

vb
Private Sub wv_Ready()

触发时机: 首次导航完成后触发一次。后续导航不再触发此事件。

用途: 安全地执行初始化操作，如绑定事件、注册数据绑定、注入脚本等。

示例:

vb
Private Sub wv_Ready()
    Me.Caption = wv.DocumentTitle
    
    ' 设置数据绑定
    wv.BindData "name", "#name-input", "value"
    wv.BindUI Me, "OnNameInput", "#name-input", EventName:="input"
    wv.SetData "name", "默认值"
    
    ' 注入脚本
    wv.AddScriptToExecuteOnDocumentCreated "window.__appReady = true;"
End Sub

Error ​

创建或运行时发生错误。

vb
Private Sub wv_Error(ByVal Description As String)

参数:

  • Description - 错误描述信息

🧭 导航事件 ​

导航即将开始，可通过 Cancel 参数取消导航。

vb
Private Sub wv_NavigationStarting(ByVal Uri As String, ByVal IsUserInitiated As Boolean, ByRef Cancel As Boolean)

参数:

  • Uri - 目标 URL
  • IsUserInitiated - 是否由用户操作（点击链接等）触发
  • Cancel - 设为 True 可取消导航

示例:

vb
Private Sub wv_NavigationStarting(ByVal Uri As String, ByVal IsUserInitiated As Boolean, ByRef Cancel As Boolean)
    ' 阻止导航到特定域名
    If InStr(UCase(Uri), "ADS.EXAMPLE.COM") > 0 Then
        Cancel = True
    End If
End Sub

导航完成。

vb
Private Sub wv_NavigationComplete(ByVal IsSuccess As Boolean, ByVal ErrorStatus As wv2ErrorStatus)

参数:

  • IsSuccess - 导航是否成功
  • ErrorStatus - 错误状态码（成功时为 0）

SourceChanged ​

URL 发生变化。

vb
Private Sub wv_SourceChanged(ByVal IsNewDocument As Boolean)

参数:

  • IsNewDocument - 是否为新文档（而非同页内导航）

DocumentTitleChanged ​

文档标题发生变化。

vb
Private Sub wv_DocumentTitleChanged()

示例:

vb
Private Sub wv_DocumentTitleChanged()
    Me.Caption = wv.DocumentTitle
End Sub

DOMContentLoaded ​

DOM 内容加载完成（早于 NavigationComplete）。

vb
Private Sub wv_DOMContentLoaded()

用途: 在 DOM 就绪但资源（图片等）尚未完全加载时执行操作。

🔐 权限/对话框事件 ​

PermissionRequested ​

页面请求权限（地理位置、相机、麦克风等）。

vb
Private Sub wv_PermissionRequested(ByVal Uri As String, ByVal PermissionKind As wv2PermissionKind, ByVal IsUserInitiated As Boolean, ByRef State As wv2PermissionState)

参数:

  • Uri - 请求权限的页面 URL
  • PermissionKind - 权限类型枚举
  • IsUserInitiated - 是否由用户操作触发
  • State - 权限状态，可设为 wv2PermissionState_Allow 或 wv2PermissionState_Deny

示例:

vb
Private Sub wv_PermissionRequested(ByVal Uri As String, ByVal PermissionKind As wv2PermissionKind, ByVal IsUserInitiated As Boolean, ByRef State As wv2PermissionState)
    ' 自动允许来自受信域名的地理位置权限
    If PermissionKind = wv2PermissionKind_Geolocation And InStr(Uri, "myapp.com") > 0 Then
        State = wv2PermissionState_Allow
    Else
        State = wv2PermissionState_Deny
    End If
End Sub

ScriptDialogOpening ​

JavaScript 对话框即将弹出（alert / confirm / prompt / beforeunload）。

vb
Private Sub wv_ScriptDialogOpening(ByVal Kind As wv2ScriptDialogKind, ByVal Message As String, ByRef Accept As Boolean)

参数:

  • Kind - 对话框类型
  • Message - 对话框消息内容
  • Accept - 设为 True 接受对话框（等效于点击确定），False 取消

说明: 可用于自定义对话框样式，替换浏览器默认的对话框。

AcceleratorKeyPressed ​

快捷键按下事件。

vb
Private Sub wv_AcceleratorKeyPressed(ByVal KeyEventKind As wv2KeyEventKind, ByVal VirtualKey As Long, ByRef Handled As Boolean)

参数:

  • KeyEventKind - 按键事件类型（KeyDown/Up/SystemKeyDown/Up）
  • VirtualKey - 虚拟键码
  • Handled - 设为 True 阻止 WebView2 处理此按键

示例:

vb
Private Sub wv_AcceleratorKeyPressed(ByVal KeyEventKind As wv2KeyEventKind, ByVal VirtualKey As Long, ByRef Handled As Boolean)
    ' 拦截 F5 刷新
    If VirtualKey = vbKeyF5 Then
        Handled = True
        ' 自定义刷新逻辑
    End If
End Sub

NewWindowRequested ​

页面请求打开新窗口（target="_blank" 或 window.open）。

vb
Private Sub wv_NewWindowRequested(ByVal Uri As String, ByVal IsUserInitiated As Boolean, ByRef Handled As Boolean)

参数:

  • Uri - 新窗口的目标 URL
  • IsUserInitiated - 是否由用户操作触发
  • Handled - 设为 True 阻止打开新窗口

示例:

vb
Private Sub wv_NewWindowRequested(ByVal Uri As String, ByVal IsUserInitiated As Boolean, ByRef Handled As Boolean)
    ' 在当前窗口中导航（阻止弹窗）
    Handled = True
    wv.Navigate Uri
End Sub

📦 资源事件 ​

WebResourceRequested ​

Web 资源请求被 AddWebResourceRequestedFilter 匹配拦截。

vb
Private Sub wv_WebResourceRequested(ByVal Request As WebView2Request, ByVal Response As WebView2Response)

参数:

  • Request - 请求对象，可读取 Method、Uri、Headers、Content
  • Response - 响应对象，设值后 WebView2 使用此响应替代实际网络请求

说明: 必须先调用 AddWebResourceRequestedFilter 注册过滤器，此事件才会触发。

ProcessFailed ​

浏览器进程失败。

vb
Private Sub wv_ProcessFailed(ByVal FailedKind As wv2ProcessFailedKind)

参数:

  • FailedKind - 进程失败类型枚举

DownloadStarting ​

下载即将开始。

vb
Private Sub wv_DownloadStarting(ByVal ResultFilePath As String, ByRef Cancel As Boolean, ByRef Handled As Boolean)

参数:

  • ResultFilePath - 下载文件路径
  • Cancel - 设为 True 取消下载
  • Handled - 设为 True 表示已处理

⚡ 脚本事件 ​

JsAsyncResult ​

异步脚本执行完成（ExecuteScript / JsRunAsync 的回调）。

vb
Private Sub wv_JsAsyncResult(ByVal Token As Long, ByVal Result As String, ByVal ErrorCode As Long)

参数:

  • Token - 调用时指定的令牌
  • Result - JS 执行结果的 JSON 字符串
  • ErrorCode - 错误码，0 表示成功

示例:

vb
wv.ExecuteScript "document.title", 1001
wv.JsRunAsync "fetch('/api').then(r=>r.json())"  ' 返回自动 token

Private Sub wv_JsAsyncResult(ByVal Token As Long, ByVal Result As String, ByVal ErrorCode As Long)
    If ErrorCode = 0 Then
        Debug.Print "Token " & Token & " => " & Result
    End If
End Sub

JsMessage ​

收到 JS 通过 window.chrome.webview.postMessage() 发送的消息。

vb
Private Sub wv_JsMessage(ByVal Message As String)

参数:

  • Message - JS 发送的消息字符串

示例:

vb
' VB6 侧
Private Sub wv_JsMessage(ByVal Message As String)
    Debug.Print "JS消息: " & Message
End Sub

' JS 侧
window.chrome.webview.postMessage("Hello from JS");

DevToolsProtocolResponse ​

CDP 异步调用响应。

vb
Private Sub wv_DevToolsProtocolResponse(ByVal CustomEventId As Variant, ByVal JsonResponse As String)

参数:

  • CustomEventId - 调用时指定的自定义事件 ID
  • JsonResponse - CDP 响应的 JSON 字符串

示例:

vb
wv.CallDevToolsProtocolMethod "Page.captureScreenshot", "{}", "screenshot"

Private Sub wv_DevToolsProtocolResponse(ByVal CustomEventId As Variant, ByVal JsonResponse As String)
    If CustomEventId = "screenshot" Then
        ' 处理截图数据
    End If
End Sub

🖱️ 宿主鼠标事件 ​

宿主鼠标事件由宿主窗口子类化捕获，反映宿主窗口区域（非 WebView2 内容区域）的鼠标操作。

HostMouseDown ​

vb
Private Sub wv_HostMouseDown(ByVal Button As wv2MouseButton, ByVal Shift As wv2ShiftState, ByVal X As Long, ByVal Y As Long)

参数:

  • Button - 鼠标按钮（1=左键, 2=右键, 4=中键，位掩码）
  • Shift - 修饰键状态（1=Shift, 2=Ctrl, 4=Alt，位掩码）
  • X, Y - 鼠标坐标（客户端区域像素）

HostMouseUp ​

vb
Private Sub wv_HostMouseUp(ByVal Button As wv2MouseButton, ByVal Shift As wv2ShiftState, ByVal X As Long, ByVal Y As Long)

HostMouseDblClick ​

vb
Private Sub wv_HostMouseDblClick(ByVal Button As wv2MouseButton, ByVal Shift As wv2ShiftState, ByVal X As Long, ByVal Y As Long)

HostMouseMove ​

vb
Private Sub wv_HostMouseMove(ByVal Button As wv2MouseButton, ByVal Shift As wv2ShiftState, ByVal X As Long, ByVal Y As Long)

说明: 需启用 EnableMouseMoveEvents = True 才会触发，默认关闭避免性能问题。

HostMouseWheel ​

vb
Private Sub wv_HostMouseWheel(ByVal Delta As Long, ByVal Shift As wv2ShiftState, ByVal X As Long, ByVal Y As Long)

参数:

  • Delta - 滚轮增量，正值向上滚动，负值向下

HostContextMenu ​

vb
Private Sub wv_HostContextMenu(ByVal X As Long, ByVal Y As Long)

⌨️ 宿主键盘事件 ​

HostKeyDown / HostKeyUp / HostKeyPress ​

vb
Private Sub wv_HostKeyDown(ByVal KeyCode As Long, ByVal Shift As wv2ShiftState)
Private Sub wv_HostKeyUp(ByVal KeyCode As Long, ByVal Shift As wv2ShiftState)
Private Sub wv_HostKeyPress(ByVal KeyAscii As Long)

HostFocus / HostBlur ​

vb
Private Sub wv_HostFocus()
Private Sub wv_HostBlur()

HostResize ​

vb
Private Sub wv_HostResize()

说明: 宿主窗口大小变化时触发，可在此处调用 wv.Resize() 手动调整 WebView2 大小（如使用 MessageWindowAdapter 时）。

🎯 用户鼠标事件 ​

用户鼠标事件通过 mouseProxy COM 代理从 WebView2 内容区域同步回调到宿主。需启用 EnableUserMouseEvents = True。

UserMouseDown / UserMouseUp ​

vb
Private Sub wv_UserMouseDown(ByVal Button As Long, ByVal X As Long, ByVal Y As Long, ByVal Shift As Long, ByRef Handled As Boolean)
Private Sub wv_UserMouseUp(ByVal Button As Long, ByVal X As Long, ByVal Y As Long, ByVal Shift As Long, ByRef Handled As Boolean)

参数:

  • Button - 鼠标按钮（1=左键, 2=右键, 4=中键）
  • X, Y - 内容区域内的像素坐标
  • Shift - 修饰键状态
  • Handled - 设为 True 阻止事件继续传播到 WebView2

UserMouseMove ​

vb
Private Sub wv_UserMouseMove(ByVal X As Long, ByVal Y As Long, ByVal Shift As Long, ByRef Handled As Boolean)

说明: 需额外启用 EnableUserMouseMove = True，默认关闭以避免性能问题。

UserMouseWheel ​

vb
Private Sub wv_UserMouseWheel(ByVal Delta As Long, ByVal X As Long, ByVal Y As Long, ByVal Shift As Long, ByRef Handled As Boolean)

UserContextMenu ​

vb
Private Sub wv_UserContextMenu(ByVal X As Long, ByVal Y As Long, ByRef Handled As Boolean)

UserDblClick ​

vb
Private Sub wv_UserDblClick(ByVal Button As Long, ByVal X As Long, ByVal Y As Long, ByVal Shift As Long, ByRef Handled As Boolean)

🔌 挂起/PDF/业务事件 ​

SuspendCompleted / SuspendFailed ​

vb
Private Sub wv_SuspendCompleted()
Private Sub wv_SuspendFailed(ByVal ErrorCode As Long)

PrintToPdfCompleted / PrintToPdfFailed ​

vb
Private Sub wv_PrintToPdfCompleted(ByVal ResultFilePath As String)
Private Sub wv_PrintToPdfFailed(ByVal ErrorCode As Long)

OnGetCookiesFull ​

异步获取完整 Cookie 完成。

vb
Private Sub wv_OnGetCookiesFull(ByVal CookiesJson As String)

触发时机: 调用 wv.Cookies.GetCookiesFullAsync() 后异步返回时。

📐 枚举参考 ​

wv2MouseButton ​

常量值说明
左键1鼠标左键
右键2鼠标右键
中键4鼠标中键

位掩码组合，可同时包含多个值。

wv2ShiftState ​

常量值说明
Shift1Shift 键
Ctrl2Ctrl 键
Alt4Alt 键

位掩码组合，检测方式：If Shift And 2 Then ' Ctrl 按下

wv2ScriptDialogKind ​

常量说明
Alertalert() 对话框
Confirmconfirm() 对话框
Promptprompt() 对话框
BeforeUnloadbeforeunload 对话框

wv2PermissionKind ​

常量说明
Unknown未知权限
Microphone麦克风
Camera摄像头
Geolocation地理位置
Notifications通知
OtherSensors其他传感器
ClipboardRead剪贴板读取

wv2PermissionState ​

常量说明
Default默认（由浏览器决定）
Allow允许
Deny拒绝

EnumCertificateErrorAction ​

常量值说明
CEA_Default0默认行为（拒绝）
CEA_Cancel1取消请求
CEA_AlwaysAllow2始终允许（注入命令行参数）

最后更新: 2026-06-24

VB6及其LOGO版权为微软公司所有

VBMAN 版权所有 © 2019-2026 邓伟