cWebView2Host 类开发文档

🚀 cWebView2Host - 基于 Microsoft Edge WebView2 的 VB6/twinBASIC 嵌入式浏览器控件封装，由 woeoio@qq.com 基于 WebView2 Win32 C API 开发

📖 目录

概述
核心亮点
快速开始
架构设计
文档索引

概述

cWebView2Host 是一个 COM 可创建类，为 VB6/VBA/twinBASIC 应用提供 Microsoft Edge WebView2 嵌入式浏览器能力。它封装了 WebView2 Win32 C API 的全部复杂性，提供了简洁的 VB 风格 API、完整的事件模型和声明式数据绑定系统。

✨ 主要特性

🌐 零配置嵌入 - 两行代码即可在窗体中嵌入完整的 Chromium 浏览器
📡 40+ 事件 - 覆盖导航、脚本、鼠标、键盘、下载、PDF 打印等全场景
🔗 声明式数据绑定 - BindUI/BindData 双向绑定，VB6 与 DOM 零胶水代码联动
⚡ 同步 JS 调用 - JsRun/JsProp 同步执行 JavaScript，告别异步回调地狱
🔧 CDP 全能力 - 同步/异步调用 Chrome DevTools Protocol，深度控制浏览器
🛡️ 安全控制 - 证书错误绕过、HTTPS 过滤、脚本开关一站式配置
🍪 Cookie 管理 - 简易/完整双模式获取 Cookie，含 HttpOnly 支持
📦 本地资源映射 - 文件夹/资源文件/虚拟主机三种本地页面加载方式
🖥️ 多宿主适配 - VB6/Excel 子类化 + Access 消息窗口双策略自动适配
📑 会话隔离 - 多实例独立 UserDataFolder，支持多账号并行

核心亮点

1️⃣ 两行代码嵌入浏览器 🌐

无需任何配置文件或初始化步骤，最小使用只需两个调用：

Dim wv As New cWebView2Host

Private Sub Form_Load()
    wv.Initialize Me.hWnd, "https://vb6.pro"
End Sub

一行声明、一行初始化，窗体中即刻拥有完整的 Edge 浏览器内核。

2️⃣ 声明式双向数据绑定 🔗

VB6 与 Web UI 之间零胶水代码双向绑定，用声明代替命令：

' 宿主 -> UI：将 key 绑定到 DOM 属性
wv.BindData "name", "#name-input", "value"
wv.BindData "name", "#name-preview", "textContent"

' UI -> 宿主：将 DOM 事件绑定到 VB6 方法
wv.BindUI Me, "OnNameInput", "#name-input", EventName:="input"

' 推送数据到 UI
wv.SetData "name", "张伟"

3️⃣ 同步 JavaScript 执行 ⚡

无需回调，直接在 VB6 中同步获取 JS 返回值：

' 同步调用 JS 函数并获取返回值
Dim title As String
title = wv.JsRun("document.title")

' 同步读取 JS 属性
Dim url As String
url = wv.JsProp("location.href")

' 同步执行 CDP 命令
Dim cookies As String
cookies = wv.CallDevToolsProtocolMethodSync("Network.getCookies", "{}")

4️⃣ 完整的事件驱动模型 📡

覆盖 WebView2 全生命周期事件，从创建到销毁，从导航到交互：

Dim WithEvents wv As cWebView2Host

' 生命周期
Private Sub wv_Create(): ...
Private Sub wv_Ready(): ...

' 导航控制
Private Sub wv_NavigationStarting(ByVal Uri As String, ByRef Cancel As Boolean): ...
Private Sub wv_NavigationComplete(ByVal IsSuccess As Boolean): ...

' 宿主鼠标/键盘
Private Sub wv_HostMouseDown(ByVal Button As Long, ByVal Shift As Long, ByVal X As Long, ByVal Y As Long): ...

' JS 消息
Private Sub wv_JsMessage(ByVal Message As String): ...

5️⃣ 多宿主自动适配 🖥️

同一套 API 自动适配 VB6、Excel UserForm 和 Access OForm 三种宿主环境：

' 三种宿主使用完全相同的 API
wv.Initialize Me.hWnd, "https://vb6.pro"        ' VB6 / Excel UserForm
wv.Initialize Me, "https://vb6.pro"              ' 传入 Form 对象（自动检测）
' Access 窗体自动检测 OForm 类名，切换为 MessageWindowAdapter

内部自动检测宿主窗口类名，VB6/Excel 使用子类化适配器，Access 使用消息窗口适配器。

快速开始

最小示例

Dim wv As New cWebView2Host

Private Sub Form_Load()
    wv.Initialize Me.hWnd, "https://vb6.pro"
End Sub

带事件处理的示例

Dim WithEvents wv As cWebView2Host

Private Sub Form_Load()
    Set wv = New cWebView2Host
    wv.Initialize Me.hWnd, "https://vb6.pro"
End Sub

Private Sub wv_Ready()
    Me.Caption = wv.DocumentTitle
    Debug.Print "浏览器已就绪"
End Sub

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

加载本地 HTML 文件

' 方式1：文件夹路径自动映射
wv.Initialize Me.hWnd, App.Path & "\www"

' 方式2：虚拟主机名映射
wv.Initialize Me.hWnd
wv.SetVirtualHostNameToFolderMapping "myapp.local", App.Path & "\www"
wv.Navigate "https://myapp.local/index.html"

' 方式3：从 VB6 资源文件加载
wv.Initialize Me.hWnd
' 在 wv_Ready 事件中：
wv.NavigateToString VBMAN2.Res(LoadResData("INDEX.HTML", "WWW")).ReturnString()

架构设计

类层次结构

cWebView2Host (公开 COM 类，用户直接交互)
├── m_Core: WebView2Core (核心引擎，实现 21 个 COM 回调接口)
│   ├── ICoreWebView2 ~ ICoreWebView2_9 (版本化接口缓存)
│   ├── ICoreWebView2Settings ~ Settings6
│   ├── ICoreWebView2Environment ~ _8
│   └── 所有事件委托 Token 管理
│
├── m_Cookies: cWebView2Cookies (Cookie 管理业务对象)
│   └── GetCookies / GetCookiesFull / GetCookiesFullAsync
│
├── m_Script: cWebView2Script (脚本执行业务对象)
│   └── Eval (同步 JS 表达式求值)
│
├── m_Security: cWebView2Security (安全/证书管理业务对象)
│   └── CertificateErrorAction / AdditionalBrowserArguments
│
├── m_MouseProxy: WebView2MouseProxy (JS->宿主鼠标事件 COM 代理)
│   └── 暴露为 JS 全局对象 mouseProxy
│
├── m_BindUIProxy: WebView2BindUIProxy (声明式绑定 COM 代理)
│   ├── 暴露为 JS 全局对象 bindUIProxy
│   ├── BindUI 事件绑定管理
│   ├── BindData 数据绑定管理
│   └── 导航后自动重建绑定
│
└── Adapter: IHostAdapter (宿主适配抽象层)
    ├── HostSubclassAdapter (VB6/Excel，子类化宿主窗口)
    └── MessageWindowAdapter (Access，消息窗口 + 轮询)

对象关系图

用户代码
  │
  ▼
cWebView2Host ──────── 事件转发 ──────── WebView2Core (WithEvents)
  │                                         │
  ├── Cookies ──────────────────────────────┤ CDP / document.cookie
  ├── Script ───────────────────────────────┤ ExecuteScript / JsRun
  ├── Security ─────────────────────────────┤ AdditionalBrowserArguments
  │                                         │
  ├── BindUIProxy ◄── AddObject ────────────┤ JS 全局对象 bindUIProxy
  └── MouseProxy  ◄── AddObject ────────────┤ JS 全局对象 mouseProxy
                    ──────────────────────────┘
                              │
                    IHostAdapter (适配层)
                    ┌─────────┴─────────┐
              HostSubclassAdapter  MessageWindowAdapter
              (VB6/Excel 子类化)   (Access 消息窗口)

初始化流程

1. cWebView2Host.Initialize(HostOrHwnd, HttpOrDir)
2. 自动检测宿主窗口类名
   ├── "OForm" → 创建 MessageWindowAdapter
   └── 其他    → 创建 HostSubclassAdapter
3. Adapter.Attach() → 子类化宿主窗口 / 创建消息窗口
4. 创建 WebView2 Environment（含重试逻辑，最多 10 次）
5. 创建 WebView2 Controller
6. CacheWebViewObjects() → QI 缓存 ICoreWebView2_1~9
7. CacheSettingsObjects() → QI 缓存 Settings_1~6
8. 注入 MouseProxy / BindUIProxy COM 对象
9. 触发 Create 事件
10. 若指定了 URL → 自动导航
11. 导航完成 → 触发 Ready 事件

三阶段初始化模式

对于需要在导航前配置环境参数的场景，使用三阶段模式：

阶段1: Initialize (无 URL)     → 创建 WebView2 控件
阶段2: wv_Create 事件          → 配置 EnvironmentOptions / Security
阶段3: wv_Ready 事件           → 执行 Navigate / NavigateToString

Private Sub Form_Load()
    Set wv = New cWebView2Host
    wv.Initialize Me.hWnd              ' 阶段1：不传 URL
End Sub

Private Sub wv_Create()
    wv.EnvironmentOptions.UserDataFolder = App.Path & "\UserDir\account-001"
    wv.Security.CertificateErrorAction = CEA_AlwaysAllow   ' 阶段2：配置
End Sub

Private Sub wv_Ready()
    wv.Navigate "https://example.com"  ' 阶段3：导航
End Sub

文档索引

文档	描述
方法参考	cWebView2Host 全部公开方法 API 参考
属性参考	cWebView2Host 全部公开属性 API 参考
事件参考	cWebView2Host 全部事件详细说明
数据绑定专题	BindUI/BindData/SetData 双向绑定系统
CDP 专题	Chrome DevTools Protocol 调用指南
宿主适配专题	VB6/Excel/Access 多宿主集成指南
常见问题	开发中常见问题与解决方案

依赖关系

组件	描述
Microsoft Edge WebView2 Runtime	运行时依赖，需在目标机器安装
vbman2_win32.dll	VBMAN2 类型库，提供 COM 注册
WebView2 Win32 C API	底层 COM 接口，由 Abstract/ 目录下的接口定义封装

兼容性

VB6 - 完全兼容，支持子类化适配器
VBA (Excel) - 完全兼容，UserForm 中使用子类化适配器
VBA (Access) - 完全兼容，自动使用消息窗口适配器
twinBASIC - 完全兼容，原生开发语言
Windows - Windows 10 及以上版本（WebView2 Runtime 要求）
WebView2 Runtime - 86.0.616.0 及以上版本

许可证

基于 Microsoft WebView2 SDK 开发

作者

cWebView2Host: woeoio@qq.com

最后更新: 2026-06-24

cWebView2Host 类开发文档 ​

📖 目录 ​

概述 ​

✨ 主要特性 ​

核心亮点 ​

1️⃣ 两行代码嵌入浏览器 🌐 ​

2️⃣ 声明式双向数据绑定 🔗 ​

3️⃣ 同步 JavaScript 执行 ⚡ ​

4️⃣ 完整的事件驱动模型 📡 ​

5️⃣ 多宿主自动适配 🖥️ ​

快速开始 ​

最小示例 ​

带事件处理的示例 ​

加载本地 HTML 文件 ​

架构设计 ​

类层次结构 ​

对象关系图 ​

初始化流程 ​

三阶段初始化模式 ​

文档索引 ​

依赖关系 ​

兼容性 ​

许可证 ​

作者 ​