cWebView2Host 属性与方法使用时机参考

不同 API 在 WebView2 生命周期中的可用时机不同。本文将所有属性和方法按最早可用时机分类，帮助开发者避免在错误阶段调用导致失效或报错。

🔄 生命周期阶段说明

WebView2 的完整生命周期包含 初始化阶段 和 运行阶段，所有事件如下：

初始化阶段（一次性，按顺序触发）

用户调用 Initialize()
  ↓
① Create 事件 ─── 配置 EnvironmentOptions / Security（仅此事件可设置）
  ↓
② 内部创建 Environment（读取 EnvironmentOptions 配置）
  ↓
③ 内部创建 Controller + CoreWebView（读取 Settings 配置）
  ↓
④ Ready 事件 ─── 控件完全就绪，所有 API 开始可用
  ↓
⑤ 首次 Navigate（如果指定了 InitialURL）

运行阶段（每次导航循环触发）

Navigate / NavigateCustom / NavigateToString / GoBack / GoForward / Reload
  ↓
⑥ NavigationStarting ─── 可 Cancel 阻止导航
  ↓
⑦ SourceChanged ─── URL 变化（IsNewDocument 标识是否新页面）
  ↓  ┌─ ContentLoading（内部事件，未暴露）
     │
⑧ DOMContentLoaded ─── DOM 就绪，可 BindUI / BindData / 执行 JS
  ↓  │
⑨ DocumentTitleChanged ─── 标题变化
     │
⑩ NavigationComplete ─── 页面完全加载（含图片等资源）
     └────────────────────────────────────────┘

每次导航都会重新触发 ⑥→⑩

运行阶段（随时可能触发的交互事件）

┌─ 权限/对话框 ─────────────────────────────────┐
│  PermissionRequested    页面请求权限（地理/相机等）│
│  ScriptDialogOpening    JS 弹框（alert/confirm） │
│  NewWindowRequested     页面请求开新窗口          │
│  AcceleratorKeyPressed  快捷键按下               │
└────────────────────────────────────────────────┘

┌─ 资源/下载 ─────────────────────────────────────┐
│  WebResourceRequested  资源请求被拦截（需先注册） │
│  DownloadStarting      下载即将开始（可 Cancel）  │
│  ProcessFailed         浏览器进程崩溃             │
└────────────────────────────────────────────────┘

┌─ 脚本回调 ──────────────────────────────────────┐
│  JsAsyncResult         异步 JS 执行完成          │
│  JsMessage             JS postMessage 到宿主     │
│  DevToolsProtocolResponse  CDP 异步响应          │
└────────────────────────────────────────────────┘

┌─ 宿主交互 ──────────────────────────────────────┐
│  HostMouseDown/Up/DblClick/Move/Wheel/ContextMenu│
│  HostKeyDown/Up/Press   键盘事件                 │
│  HostFocus / HostBlur   焦点进出                 │
│  HostResize             宿主窗口大小变化           │
└────────────────────────────────────────────────┘

┌─ 内容区鼠标（需 EnableUserMouseEvents=True）────┐
│  UserMouseDown/Up/Move/Wheel/ContextMenu/DblClick│
└────────────────────────────────────────────────┘

┌─ 异步操作回调 ──────────────────────────────────┐
│  SuspendCompleted / SuspendFailed                │
│  PrintToPdfCompleted / PrintToPdfFailed          │
│  OnGetCookiesFull                                │
└────────────────────────────────────────────────┘

┌─ 错误 ─────────────────────────────────────────┐
│  Error                  创建/运行时错误           │
└────────────────────────────────────────────────┘

阶段与 API 可用性对照

阶段	时机	可做的事
Initialize 调用前	对象刚创建	仅可设置 EnvironmentOptions 的子属性
Create 事件	Environment 创建前	设置 EnvironmentOptions、Security 配置
Ready 事件	控件完全就绪	导航、注册绑定、注入脚本、设置运行时属性
DOMContentLoaded	DOM 就绪	BindUI、BindData、执行 JS（确保元素存在）
NavigationComplete	页面完全加载	所有运行时 API 无限制使用
运行时任意时刻	Ready 之后	所有 API 无限制使用

📋 属性使用时机总览

🔴 仅 Create 事件（创建前配置）

这些属性影响 WebView2 Environment 的创建参数，必须在 wv_Create 事件中设置，之后修改无效。

属性	子属性	说明
EnvironmentOptions	`UserDataFolder`	用户数据目录，创建 Environment 时读取，之后改了也不生效
	`BrowserExecutableFolder`	浏览器可执行文件目录
	`AdditionalBrowserArguments`	附加命令行参数（如 `--ignore-certificate-errors`）
	`Language`	浏览器默认语言
	`TargetCompatibleBrowserVersion`	目标兼容版本
	`AllowSingleSignOnUsingOSPrimaryAccount`	SSO 配置
	`ExclusiveUserDataFolderAccess`	独占数据目录
	`EnableTrackingPrevention`	跟踪防护
Security	`CertificateErrorAction`	证书错误处理策略，必须在 Create 前设置

示例：

Private Sub wv_Create()
    ' ★ 这些只能在 Create 事件中设置！
    wv.EnvironmentOptions.UserDataFolder = App.Path & "\UserDir\account-001"
    wv.EnvironmentOptions.AdditionalBrowserArguments = "--ignore-certificate-errors"
    wv.Security.CertificateErrorAction = CEA_AlwaysAllow
End Sub

🟡 Ready 事件起可用（运行时设置）

这些属性需要 CoreWebView2 Controller/Settings 对象已创建，从 wv_Ready 事件起可设置。在 Create 事件中设置可能无效（底层 Settings 对象尚未创建）。

属性	说明	注意
IsPasswordAutoSaveEnabled	密码自动保存	默认 False，需在 Ready 后设置才生效
IsGeneralAutoFillEnabled	表单自动填充	默认 False，需在 Ready 后设置才生效
IsScriptEnabled	JS 执行开关	默认 True
AreDevToolsEnabled	DevTools 开关	默认 True，生产建议关闭
IsStatusBarEnabled	状态栏显示	默认 False
IsZoomControlEnabled	用户缩放控制	默认 True
AreDefaultContextMenusEnabled	右键菜单	默认 True
UserAgent	自定义 UA	设置后后续请求生效
IsPinchZoomEnabled	捏合缩放	默认 True
IsSwipeNavigationEnabled	滑动导航	默认 True
AreBrowserAcceleratorKeysEnabled	浏览器快捷键	默认 True
ZoomFactor	缩放因子	默认 1.0，需要页面已加载
EnableUserMouseEvents	内容区鼠标事件	默认 False，Ready 后设置并自动注入代理
EnableUserMouseMove	内容区 mousemove	需 EnableUserMouseEvents 为 True
EnableMouseMoveEvents	宿主 mousemove	默认 False

示例：

Private Sub wv_Ready()
    ' ★ 运行时设置属性
    wv.IsPasswordAutoSaveEnabled = True
    wv.IsGeneralAutoFillEnabled = True
    wv.AreDevToolsEnabled = False      ' 生产环境关闭 DevTools
    wv.UserAgent = "Mozilla/5.0 (MyApp)"
    
    ' 启用鼠标事件代理
    wv.EnableUserMouseEvents = True
End Sub

🟢 任意时间可用（只读状态）

这些属性是只读的，随时可读取，但需要 Ready 后才有有效值。

属性	说明	Ready 前值
IsReady	是否就绪	False → True
hWnd	子窗口句柄	0 → 有效句柄
BrowserProcessId	进程 ID	0 → 有效 ID
CanGoBack	可后退	False
CanGoForward	可前进	False
IsSuspended	是否挂起	False
IsMuted	是否静音	False
IsDocumentPlayingAudio	播放音频	False
IsDefaultDownloadDialogOpen	下载对话框	False
DocumentURL	当前 URL	"" → 有效 URL
DocumentTitle	当前标题	"" → 有效标题
SupportsWebView2~9	功能检测	Ready 后才有准确值
Cookies	Cookie 对象	Ready 后可用
Script	脚本对象	Ready 后可用
HostAdapterName	适配器名称	Initialize 时即有值

📋 方法使用时机总览

🔴 仅 Create 事件

方法	说明
—	目前没有方法仅限 Create 事件使用

注意：Create 事件中虽然可以调用某些方法，但底层 CoreWebView 对象尚未创建，大部分方法会静默失败（被 If m_Core Is Nothing Then Exit Sub 保护）。Create 事件的唯一用途是配置 EnvironmentOptions 和 Security。

🟡 Ready 事件起可用

这些方法需要 CoreWebView 对象已创建，从 wv_Ready 事件起才可调用：

方法	说明	注意
Navigate	导航到 URL	Ready 后调用，Create 中调用无效
NavigateCustom	自定义请求导航	同上
NavigateToString	加载 HTML 字符串	同上
GoBack / GoForward / Reload	导航控制	需有导航历史
ExecuteScript	异步执行 JS	需页面已加载
JsRun	同步调用 JS	需页面已加载
JsRunAsync	异步调用 JS	需页面已加载
JsProp	读取 JS 属性	需页面已加载
PostWebMessage	发送字符串消息	需页面已加载
PostWebMessageJSON	发送 JSON 消息	需页面已加载
AddObject	注入 COM 对象	Ready 后注入，页面 JS 才能访问
RemoveObject	移除 COM 对象
AddScriptToExecuteOnDocumentCreated	注入脚本	Ready 后注入，后续页面才执行
AddWebResourceRequestedFilter	添加资源过滤器	Ready 后注册才生效
RemoveWebResourceRequestedFilter	移除过滤器
SetVirtualHostNameToFolderMapping	虚拟主机映射	Ready 后设置，然后 Navigate
ClearVirtualHostNameToFolderMapping	清除映射
PrintToPdf	打印 PDF	需页面已加载
Suspend / Resume	挂起/恢复
OpenDevToolsWindow	打开 DevTools
CallDevToolsProtocolMethod	异步 CDP
CallDevToolsProtocolMethodSync	同步 CDP
OpenDefaultDownloadDialog	打开下载对话框
CloseDefaultDownloadDialog	关闭下载对话框
OpenTaskManagerWindow	任务管理器
Resize	调整大小
SetFocus	设置焦点
BindUI	DOM 事件绑定	需页面 DOM 存在
UnbindUI	移除事件绑定
BindData	数据绑定	需页面 DOM 存在
UnbindData	移除数据绑定
SetData	推送数据	需已 BindData
SetDataBatch	批量推送	需已 BindData

🟢 任意时间可用（但建议 Ready 后）

方法	说明
Initialize	初始化控件，是起点
Cleanup	清理资源，随时可调用

🔵 建议在 DOMContentLoaded 后使用

以下方法依赖页面 DOM 已渲染，建议在 wv_DOMContentLoaded 或 wv_NavigationComplete 事件之后调用：

方法	说明	原因
BindUI	DOM 事件绑定	需元素已存在于 DOM
BindData	数据绑定	需元素已存在于 DOM
SetData / SetDataBatch	推送数据	需已完成 BindData
JsRun / JsProp	同步 JS 调用	需 JS 环境就绪
Script.Eval	同步执行 JS	需页面 JS 可执行

最佳实践：

Private Sub wv_DOMContentLoaded()
    ' ★ DOM 就绪后绑定 UI 和数据
    wv.BindData "name", "#name-input", "value"
    wv.BindData "name", "#name-preview", "textContent"
    wv.BindUI Me, "OnNameInput", "#name-input", EventName:="input"
    wv.SetData "name", "初始值"
End Sub

⚠️ 常见错误场景

错误做法	问题	正确做法
在 Form_Load 设置 `EnvironmentOptions.UserDataFolder`	Initialize 内部会覆盖默认值，但用户在 Create 之前的设置会被保留	在 `wv_Create` 事件中设置
在 Create 事件中 `Navigate`	CoreWebView 尚未创建，静默失败	在 `wv_Ready` 事件中 Navigate
在 Ready 事件前 `AddObject`	底层 CoreWebView 为 Nothing	在 `wv_Ready` 事件中 AddObject
在 NavigationStarting 中 `BindData`	DOM 可能尚未加载	在 `wv_DOMContentLoaded` 中 BindData
在 Create 中设置 `IsPasswordAutoSaveEnabled`	Settings4 对象尚未创建，可能无效	在 `wv_Ready` 后设置

🗺️ 快速决策流程图

需要配置 EnvironmentOptions 或 Security？
  → ★ wv_Create 事件

需要设置运行时属性（IsPasswordAutoSaveEnabled 等）？
  → ★ wv_Ready 事件起

需要导航、注入脚本、注册过滤器？
  → ★ wv_Ready 事件起

需要绑定 UI/数据、执行 JS？
  → ★ wv_DOMContentLoaded 事件起（确保 DOM 就绪）

需要读取状态（URL、标题等）？
  → ★ 任意时间（但 Ready 后才有有效值）

最后更新: 2026-06-26

cWebView2Host 属性与方法使用时机参考 ​

🔄 生命周期阶段说明 ​

初始化阶段（一次性，按顺序触发） ​

运行阶段（每次导航循环触发） ​

运行阶段（随时可能触发的交互事件） ​

阶段与 API 可用性对照 ​

📋 属性使用时机总览 ​

🔴 仅 Create 事件（创建前配置） ​

🟡 Ready 事件起可用（运行时设置） ​

🟢 任意时间可用（只读状态） ​

📋 方法使用时机总览 ​

🔴 仅 Create 事件 ​

🟡 Ready 事件起可用 ​

🟢 任意时间可用（但建议 Ready 后） ​

🔵 建议在 DOMContentLoaded 后使用 ​

⚠️ 常见错误场景 ​

🗺️ 快速决策流程图 ​