cWebView2Host 方法参考

📋 方法总览

分类	方法	说明
生命周期	Initialize	初始化 WebView2 控件
导航	Navigate	导航到指定 URL
	NavigateCustom	自定义请求导航（支持 POST/PUT）
	NavigateToString	加载 HTML 字符串
	GoBack	后退
	GoForward	前进
	Reload	重新加载
脚本	ExecuteScript	异步执行 JavaScript
	JsRun	同步调用 JS 函数
	JsRunAsync	异步调用 JS 函数（返回 token）
	JsProp	同步读取 JS 属性
消息	PostWebMessage	向 WebView 发送字符串消息
	PostWebMessageJSON	向 WebView 发送 JSON 消息
COM 对象	AddObject	注入 COM 宿主对象到 JS 全局
	RemoveObject	移除已注入的 COM 宿主对象
脚本注入	AddScriptToExecuteOnDocumentCreated	页面创建时自动执行脚本
资源过滤	AddWebResourceRequestedFilter	添加 Web 资源请求过滤器
	RemoveWebResourceRequestedFilter	移除 Web 资源请求过滤器
开发工具	OpenDevToolsWindow	打开 DevTools 窗口
	CallDevToolsProtocolMethod	异步调用 CDP 方法
	CallDevToolsProtocolMethodSync	同步调用 CDP 方法
虚拟主机	SetVirtualHostNameToFolderMapping	映射虚拟主机名到本地文件夹
	ClearVirtualHostNameToFolderMapping	清除虚拟主机名映射
PDF	PrintToPdf	将当前页面打印为 PDF
挂起/恢复	Suspend	挂起 WebView2 进程
	Resume	恢复挂起的 WebView2 进程
下载	OpenDefaultDownloadDialog	打开默认下载对话框
	CloseDefaultDownloadDialog	关闭默认下载对话框
窗口	Resize	调整 WebView2 控件大小
	SetFocus	设置焦点到 WebView2 控件
	OpenTaskManagerWindow	打开浏览器任务管理器
数据绑定	BindUI	声明式 DOM 事件 -> 宿主方法绑定
	UnbindUI	移除 DOM 事件绑定
	BindData	声明式宿主数据 -> DOM 属性绑定
	UnbindData	移除数据绑定
	SetData	推送单个数据值到 DOM
	SetDataBatch	批量推送数据到 DOM

🌐 生命周期方法

Initialize

初始化 WebView2 控件，创建环境、控制器并选择性地导航到指定 URL。

Public Function Initialize(HostOrHwnd As Variant, Optional HttpOrDir As String) As cWebView2Host

参数:

HostOrHwnd - 宿主窗口句柄（Long/LongPtr）或 VBA 对象（如 Form/Frame）。传入 Form 对象时自动获取 hWnd。
HttpOrDir - 可选。URL 地址（如 "https://vb6.pro"）或本地文件夹路径（如 App.Path & "\www"）。传入文件夹路径时自动映射为 http://vbman2.com/index.html。省略则不自动导航。

返回: 返回 Me 自身，支持链式调用。

说明:

自动检测宿主窗口类名，OForm 使用消息窗口适配器，其他使用子类化适配器
创建 Environment 时具有重试逻辑，最多 10 次尝试（自动递增 UserDataFolder 路径）
传入 Form 对象时等效于传入 Form.hWnd

示例:

' 最简两参数形式：窗口句柄 + URL
wv.Initialize Me.hWnd, "https://vb6.pro"

' 传入 Form 对象
wv.Initialize Me, "https://vb6.pro"

' 加载本地文件夹
wv.Initialize Me.hWnd, App.Path & "\www"

' 延迟导航（不传第二个参数）
wv.Initialize Me.hWnd
' 在 wv_Ready 事件中手动导航

🧭 导航方法

Navigate

导航到指定 URL。

Public Sub Navigate(ByVal Url As String)

参数:

Url - 目标 URL 地址

示例:

wv.Navigate "https://example.com"

NavigateCustom

使用自定义 HTTP 方法和请求体导航。

Public Sub NavigateCustom(ByVal Url As String, ByVal Method As String, ByVal Body As String, Optional ByVal Headers As String)

参数:

Url - 目标 URL 地址
Method - HTTP 方法（如 "POST", "PUT", "DELETE"）
Body - 请求体内容（UTF-8 编码）
Headers - 可选。自定义请求头，JSON 格式

示例:

' POST 请求
wv.NavigateCustom "https://api.example.com/data", "POST", "{""key"":""value""}", "{""Content-Type"":""application/json""}"

NavigateToString

将 HTML 字符串加载到 WebView2 中渲染。

Public Sub NavigateToString(ByVal HtmlContent As String)

参数:

HtmlContent - 完整的 HTML 字符串

示例:

wv.NavigateToString "<html><body><h1>Hello WebView2</h1></body></html>"

' 从 VB6 资源文件加载
wv.NavigateToString VBMAN2.Res(LoadResData("INDEX.HTML", "WWW")).ReturnString()

GoBack / GoForward / Reload

浏览器导航控制。

Public Sub GoBack()
Public Sub GoForward()
Public Sub Reload()

示例:

If wv.CanGoBack Then wv.GoBack
If wv.CanGoForward Then wv.GoForward
wv.Reload

⚡ 脚本方法

ExecuteScript

异步执行 JavaScript 代码，结果通过 JsAsyncResult 事件返回。

Public Sub ExecuteScript(ByVal JavaScript As String, Optional ByVal Token As Long = 0)

参数:

JavaScript - 要执行的 JavaScript 代码
Token - 可选。自定义令牌，用于在 JsAsyncResult 事件中标识调用

说明: 异步执行，不阻塞 VB6 线程。执行结果在 JsAsyncResult 事件中获取。

示例:

wv.ExecuteScript "document.title", 1001

Private Sub wv_JsAsyncResult(ByVal Token As Long, ByVal Result As String, ByVal ErrorCode As Long)
    If Token = 1001 Then
        Debug.Print "页面标题: " & Result
    End If
End Sub

JsRun

同步调用 JavaScript 函数并返回结果。阻塞当前线程直到 JS 执行完成。

Public Function JsRun(ByVal Expression As String, Optional ByVal TimeoutMs As Long = 5000) As String

参数:

Expression - JavaScript 表达式或函数调用
TimeoutMs - 可选。超时时间（毫秒），默认 5000

返回: JS 执行结果的 JSON 字符串

说明: 内部使用 Sleep + DoEvents 实现同步等待，不影响 VB6 窗体消息循环。

示例:

Dim title As String
title = wv.JsRun("document.title")

Dim result As String
result = wv.JsRun("JSON.stringify({name:'test', value:42})")

JsRunAsync

异步调用 JavaScript 函数，返回令牌用于在事件中追踪结果。

Public Function JsRunAsync(ByVal Expression As String) As Long

参数:

Expression - JavaScript 表达式

返回: 令牌（Token），在 JsAsyncResult 事件中用于匹配对应调用

示例:

Dim token As Long
token = wv.JsRunAsync("fetch('https://api.example.com/data').then(r=>r.json())")

Private Sub wv_JsAsyncResult(ByVal Token As Long, ByVal Result As String, ByVal ErrorCode As Long)
    Debug.Print "Async result token=" & Token & ": " & Result
End Sub

JsProp

同步读取 JavaScript 属性值。

Public Function JsProp(ByVal Expression As String, Optional ByVal TimeoutMs As Long = 5000) As String

参数:

Expression - JavaScript 属性表达式
TimeoutMs - 可选。超时时间（毫秒），默认 5000

返回: 属性值的 JSON 字符串

示例:

Dim url As String
url = wv.JsProp("location.href")

Dim userAgent As String
userAgent = wv.JsProp("navigator.userAgent")

📨 消息方法

PostWebMessage

向 WebView2 页面发送字符串消息，页面通过 window.chrome.webview.addEventListener('message', ...) 接收。

Public Sub PostWebMessage(ByVal Message As String)

参数:

Message - 要发送的消息字符串

示例:

wv.PostWebMessage "Hello from VB6"

PostWebMessageJSON

向 WebView2 页面发送 JSON 格式消息。

Public Sub PostWebMessageJSON(ByVal JsonMessage As String)

参数:

JsonMessage - JSON 格式的消息字符串

示例:

wv.PostWebMessageJSON "{""type"":""update"",""data"":{""name"":""test""}}"

🔗 COM 对象方法

AddObject

将 COM 对象注入到 WebView2 的 JavaScript 全局命名空间中。

Public Sub AddObject(ByVal Name As String, ByVal Object As Object)

参数:

Name - JavaScript 中的全局对象名称
Object - COM 对象实例

说明: 注入后，JS 中可通过 window.chrome.webview.hostObjects.<Name> 访问该对象的方法和属性。JS 调用 COM 方法默认是异步的（返回 Promise），需使用 hostObjects.sync.<Name> 进行同步调用。

示例:

Dim myObj As New MyComClass
wv.AddObject "myApi", myObj

' JS 中调用：
' const result = await window.chrome.webview.hostObjects.myApi.DoSomething("param");
' const result = window.chrome.webview.hostObjects.sync.myApi.DoSomething("param");

RemoveObject

移除已注入的 COM 宿主对象。

Public Sub RemoveObject(ByVal Name As String)

参数:

Name - 之前注入的对象名称

💉 脚本注入方法

AddScriptToExecuteOnDocumentCreated

在页面文档创建时自动执行的脚本，适用于所有后续导航的页面。

Public Sub AddScriptToExecuteOnDocumentCreated(ByVal JavaScript As String)

参数:

JavaScript - 要注入的 JavaScript 代码

说明: 脚本在 DOM 尚未完成加载时执行，适合注入全局变量、覆盖原生方法等。必须在 WebView2 创建后调用。

示例:

' 注入全局调试函数
wv.AddScriptToExecuteOnDocumentCreated "window.__vb6Debug = true;"

' 拦截 console.log
wv.AddScriptToExecuteOnDocumentCreated _
    "window.console.log = function(msg) { window.chrome.webview.postMessage('[LOG] ' + msg); };"

🔍 资源过滤方法

AddWebResourceRequestedFilter

添加 Web 资源请求过滤器，匹配的请求会触发 WebResourceRequested 事件。

Public Sub AddWebResourceRequestedFilter(ByVal Uri As String, ByVal ResourceContext As wv2WebResourceContext)

参数:

Uri - URI 匹配模式（支持通配符）
ResourceContext - 资源上下文类型（如 wv2WebResourceContext_Document）

示例:

' 拦截所有图片请求
wv.AddWebResourceRequestedFilter "*", wv2WebResourceContext_Image

' 拦截特定域名的脚本
wv.AddWebResourceRequestedFilter "https://ads.example.com/*", wv2WebResourceContext_Script

RemoveWebResourceRequestedFilter

移除之前添加的资源请求过滤器。

Public Sub RemoveWebResourceRequestedFilter(ByVal Uri As String, ByVal ResourceContext As wv2WebResourceContext)

🔧 开发工具方法

OpenDevToolsWindow

打开 WebView2 的开发者工具窗口。

Public Sub OpenDevToolsWindow()

CallDevToolsProtocolMethod

异步调用 Chrome DevTools Protocol 方法。

Public Sub CallDevToolsProtocolMethod(ByVal MethodName As String, ByVal ParametersAsJson As String, ByVal CustomEventId As String)

参数:

MethodName - CDP 方法名（如 "Runtime.evaluate", "Network.getCookies"）
ParametersAsJson - 方法参数的 JSON 字符串
CustomEventId - 自定义事件 ID，在 DevToolsProtocolResponse 事件中用于匹配

说明: 结果通过 DevToolsProtocolResponse 事件异步返回。

示例:

wv.CallDevToolsProtocolMethod "Runtime.evaluate", _
    "{""expression"":""document.title""}", "getTitle"

Private Sub wv_DevToolsProtocolResponse(ByVal CustomEventId As Variant, ByVal JsonResponse As String)
    If CustomEventId = "getTitle" Then
        Debug.Print "CDP Title: " & JsonResponse
    End If
End Sub

CallDevToolsProtocolMethodSync

同步调用 Chrome DevTools Protocol 方法，阻塞等待结果。

Public Function CallDevToolsProtocolMethodSync(ByVal MethodName As String, ByVal ParametersAsJson As String) As String

参数:

MethodName - CDP 方法名
ParametersAsJson - 方法参数的 JSON 字符串

返回: CDP 响应的 JSON 字符串

说明: 使用 Sleep + DoEvents 实现同步等待，不影响 VB6 窗体消息循环。

示例:

Dim cookies As String
cookies = wv.CallDevToolsProtocolMethodSync("Network.getCookies", "{}")

Dim version As String
version = wv.CallDevToolsProtocolMethodSync("Browser.getVersion", "{}")

🗂️ 虚拟主机方法

SetVirtualHostNameToFolderMapping

将虚拟主机名映射到本地文件夹，使 WebView2 可以通过 https:// 访问本地文件。

Public Sub SetVirtualHostNameToFolderMapping(ByVal HostName As String, ByVal FolderPath As String, Optional ByVal AccessKind As wv2HostResourceAccessKind = wv2HostResourceAccessKind_Allow)

参数:

HostName - 虚拟主机名（如 "myapp.local"）
FolderPath - 本地文件夹的绝对路径
AccessKind - 可选。访问权限，默认为 Allow

示例:

wv.SetVirtualHostNameToFolderMapping "myapp.local", App.Path & "\www"
wv.Navigate "https://myapp.local/index.html"

ClearVirtualHostNameToFolderMapping

清除虚拟主机名映射。

Public Sub ClearVirtualHostNameToFolderMapping(ByVal HostName As String)

📑 PDF 方法

PrintToPdf

将当前页面打印为 PDF 文件。

Public Sub PrintToPdf(ByVal ResultFilePath As String, _
    Optional ByVal Orientation As wv2PrintOrientation = wv2PrintOrientation_Portrait, _
    Optional ByVal ScaleFactor As Single = 1.0, _
    Optional ByVal PageWidth As Single = 0, _
    Optional ByVal PageHeight As Single = 0, _
    Optional ByVal MarginTop As Single = 0, _
    Optional ByVal MarginBottom As Single = 0, _
    Optional ByVal MarginLeft As Single = 0, _
    Optional ByVal MarginRight As Single = 0, _
    Optional ByVal ShouldPrintHeader As Boolean = False, _
    Optional ByVal ShouldPrintFooter As Boolean = False)

参数:

ResultFilePath - PDF 输出文件路径
Orientation - 可选。打印方向，默认纵向
ScaleFactor - 可选。缩放因子，默认 1.0
其余参数为页面尺寸和边距设置

说明: 完成后触发 PrintToPdfCompleted 事件，失败触发 PrintToPdfFailed 事件。

🔌 挂起/恢复方法

Suspend

挂起 WebView2 渲染进程以节省资源。

Public Sub Suspend()

说明: 完成后触发 SuspendCompleted 或 SuspendFailed 事件。

Resume

恢复挂起的 WebView2 进程。

Public Sub Resume()

📥 下载方法

OpenDefaultDownloadDialog / CloseDefaultDownloadDialog

打开/关闭默认下载对话框。

Public Sub OpenDefaultDownloadDialog()
Public Sub CloseDefaultDownloadDialog()

🪟 窗口方法

Resize

调整 WebView2 控件大小以适应宿主窗口。

Public Sub Resize()

说明: 宿主窗口大小变化时调用，内部会自动读取宿主窗口客户区尺寸。

SetFocus

将焦点设置到 WebView2 控件。

Public Sub SetFocus()

OpenTaskManagerWindow

打开浏览器内置任务管理器窗口。

Public Sub OpenTaskManagerWindow()

🔗 数据绑定方法

BindUI

声明式绑定 DOM 事件到宿主 VB 方法。当指定元素触发事件时，自动调用宿主对象的指定方法。

Public Function BindUI(ByVal HostInst As Object, ByVal HostFunction As String, ByVal QuerySelector As String, Optional ByVal IsOverWrite As Boolean = False, Optional ByVal EventName As String = "click") As String

参数:

HostInst - 宿主对象实例（通常传 Me，即 Form 自身）
HostFunction - 宿主对象上的 Public 方法名
QuerySelector - CSS 选择器，定位 DOM 元素
IsOverWrite - 可选。是否覆盖同名绑定，默认 False
EventName - 可选。DOM 事件名，默认 "click"

返回: BindId，用于标识此绑定

说明: 宿主方法签名必须为 Public Sub MethodName(ByVal EventName As String, ByVal Detail As String)，其中 Detail 是 JSON 格式的事件详情。

示例:

Dim bindId As String
bindId = wv.BindUI(Me, "OnButtonClick", "#submit-btn")

' 带自定义事件名
wv.BindUI Me, "OnNameInput", "#name-input", EventName:="input"

' 回调方法
Public Sub OnButtonClick(ByVal EventName As String, ByVal Detail As String)
    Debug.Print "Button clicked! Detail: " & Detail
End Sub

UnbindUI

移除 DOM 事件绑定。

Public Sub UnbindUI(ByVal QuerySelector As String, Optional ByVal EventName As String = "")

参数:

QuerySelector - 之前绑定时的 CSS 选择器
EventName - 可选。指定移除某个事件，空则移除该元素所有绑定

BindData

声明式绑定数据键到 DOM 属性。当 SetData 更新该键时，所有绑定的 DOM 属性自动更新。

Public Sub BindData(ByVal Key As String, ByVal QuerySelector As String, Optional ByVal Attr As String = "textContent")

参数:

Key - 数据键名（自定义标识符）
QuerySelector - CSS 选择器，定位 DOM 元素
Attr - 可选。DOM 属性名，默认 "textContent"。支持 value, textContent, innerHTML, src, class, checked, visible（自定义）等

说明: 同一个 Key 可以绑定到多个元素和不同属性。

示例:

' 同一数据绑定到输入框值和预览文本
wv.BindData "name", "#name-input", "value"
wv.BindData "name", "#name-preview", "textContent"

' 绑定到 checkbox 的 checked 属性
wv.BindData "enabled", "#toggle-enabled", "checked"

' 绑定到自定义 visible 属性（控制显示/隐藏）
wv.BindData "enabled", "#settings-panel", "visible"

' 绑定到图片 src
wv.BindData "avatar", "#avatar-img", "src"

' 绑定到 CSS class
wv.BindData "statusOnline", "#status-dot", "class"

UnbindData

移除数据绑定。

Public Sub UnbindData(ByVal Key As String)

参数:

Key - 要移除的数据键名

SetData

推送单个数据值到所有绑定的 DOM 元素。

Public Sub SetData(ByVal Key As String, ByVal Value As Variant)

参数:

Key - 数据键名
Value - 数据值，支持 String、Boolean、Number

示例:

wv.SetData "name", "张伟"
wv.SetData "enabled", True
wv.SetData "count", 42
wv.SetData "avatar", "https://example.com/img.png"

SetDataBatch

批量推送数据到 DOM，参数为 JSON 对象字符串。

Public Sub SetDataBatch(ByVal Json As String)

参数:

Json - JSON 对象字符串，键为数据键名，值为数据值

示例:

wv.SetDataBatch "{""name"":""张伟"",""enabled"":true,""count"":42}"

最后更新: 2026-06-24

cWebView2Host 方法参考 ​

📋 方法总览 ​

🌐 生命周期方法 ​

Initialize ​

🧭 导航方法 ​

Navigate ​

NavigateCustom ​

NavigateToString ​

GoBack / GoForward / Reload ​

⚡ 脚本方法 ​

ExecuteScript ​

JsRun ​

JsRunAsync ​

JsProp ​

📨 消息方法 ​

PostWebMessage ​

PostWebMessageJSON ​

🔗 COM 对象方法 ​

AddObject ​

RemoveObject ​

💉 脚本注入方法 ​

AddScriptToExecuteOnDocumentCreated ​

🔍 资源过滤方法 ​

AddWebResourceRequestedFilter ​

RemoveWebResourceRequestedFilter ​

🔧 开发工具方法 ​

OpenDevToolsWindow ​

CallDevToolsProtocolMethod ​

CallDevToolsProtocolMethodSync ​

🗂️ 虚拟主机方法 ​

SetVirtualHostNameToFolderMapping ​

ClearVirtualHostNameToFolderMapping ​

📑 PDF 方法 ​

PrintToPdf ​

🔌 挂起/恢复方法 ​

Suspend ​

Resume ​

📥 下载方法 ​

OpenDefaultDownloadDialog / CloseDefaultDownloadDialog ​

🪟 窗口方法 ​

Resize ​

SetFocus ​

OpenTaskManagerWindow ​

🔗 数据绑定方法 ​

BindUI ​

UnbindUI ​

BindData ​

UnbindData ​

SetData ​

SetDataBatch ​