EdgeView 浏览器模块

[🕒 预计 8 分钟] | 难度：入门

EdgeView 基于 Microsoft Edge WebView2，把完整的 Edge 浏览器嵌入你的 Win32 窗口，提供导航、网页消息、JavaScript 返回值、71 项浏览器事件和 271 条中文命令（235 条安全 API、36 条兼容命令），覆盖任务、导航、脚本、会话、下载、查找、打印、开发者工具等功能族。

项目	说明
模块 ID	lingbuilder.edgeview
设计器控件	Edge浏览器
SDK 依赖	无需下载大型 SDK（依赖系统 WebView2 Runtime，Windows 10/11 一般已内置）
平台	Windows（Win32 / x64，MSVC 工具链）

启用模块

打开活动栏「模块」页，在模块市场或本地模块中找到 EdgeView 浏览器模块，确认安装并加入当前项目；也可以在解决方案资源管理器项目节点下右键「模块」→「配置项目所使用模块」勾选。详细步骤见安装与管理模块。

设计器控件

在窗口设计器工具箱的模块分组中找到 Edge浏览器 控件，拖到窗口上即可。控件在运行时由模块创建并挂载到控件区域；也可以不拖控件，直接用 EdgeView_创建 在代码中创建。

快速上手

在窗口的「创建完毕」事件里绑定事件并导航（示例沿用官方示例工程的写法）：

包 EdgeView演示
使用 Win32窗口基础模块
使用 EdgeView浏览器模块

类 MainWindow : 窗口
公开
  事件 _MainWindow_创建完毕()
    局部 整数型 绑定结果 = 0
    绑定结果 = EdgeView_绑定控件事件(演示浏览器, "Web资源请求", &收到资源请求)
    EdgeView_导航("https://example.com")
  结束

  事件 收到资源请求()
    调试输出(EdgeView事件_取字段(演示浏览器, "uri"))
  结束
结束类

要点：

• 控件参数是裸 controlRef（如 演示浏览器），不要加引号；处理器参数用 &处理器名 引用。
• 设计器控件用 EdgeView_绑定控件事件(控件名, 事件名, &处理器名)；纯代码实例用 EdgeView_绑定事件(实例编号, 事件名, &处理器名)。
• EdgeView_执行JS("document.title") 执行 JavaScript 并返回 WebView2 的 JSON 编码结果。
• EdgeView_取事件数据控件 返回当前事件的 UTF-16 JSON 文本，EdgeView事件_取字段 按字段名读取单个字段。

完整示例（拦截请求并读取响应正文）见仓库 examples/edgeview-response-demos/。

常用命令参考

命令	说明
EdgeView_创建(父组件句柄, 地址)	在指定 HWND 组件客户区创建 EdgeView；传 0 嵌入当前窗口
EdgeView_创建实例(实例编号, 父组件句柄, 地址, 独立缓存目录)	创建具名实例；不同缓存目录拥有独立 Cookie、存储和会话
EdgeView_创建实例代理(实例编号, 父组件句柄, 地址, 缓存目录, 代理地址)	创建使用独立代理的实例（HTTP/HTTPS/SOCKS5）
EdgeView_导航(地址) / EdgeView_导航实例(实例编号, 地址)	导航到 HTTP/HTTPS 或本地文件地址
EdgeView_执行JS(脚本) / EdgeView_执行JS实例(实例编号, 脚本)	执行 JavaScript，返回 JSON 编码结果
EdgeView_后退() / EdgeView_前进()	历史记录导航
EdgeView_绑定控件事件(控件名, 事件名, &处理器名)	为设计器控件绑定浏览器事件
EdgeView_绑定事件(实例编号, 事件名, &处理器名)	为纯代码实例绑定浏览器事件
EdgeView_监听开发者工具事件(实例编号, 协议事件名)	监听 Chromium DevTools Protocol 事件
EdgeView_等待事件(实例编号, 事件名, 超时毫秒)	泵送消息并等待指定事件
EdgeView事件_取字段(控件名, "字段名")	读取当前事件的单个字段

完整命令清单在 IDE「模块详情 → 接口 → 模块公开信息」中查看。

模块详情中的接口清单是当前版本的完整命令来源；仓库内还提供一份可复制的完整演示清单：examples/module-demos/lingbuilder.edgeview/src/README.md。

多店铺独立弹窗与 Cookie 隔离（1.4.0 起）

需要「浏览器是独立顶层弹窗（不内嵌程序窗口）、多个店铺之间 Cookie/缓存互相隔离」的场景（如多账号登录态验证），走实例编号 API，不引用设计器控件名：

命令	说明
EdgeView_创建弹窗浏览器(实例编号, 窗口标题, 宽, 高, 地址, 独立缓存目录, 用户代理)	凭空创建独立顶层浏览器弹窗（任务栏可见、可拖动缩放、页面随窗口自适应），独立缓存目录 逐店不同即完成 Cookie/存储隔离，用户代理 在首次导航前生效
EdgeView会话_批量置Cookie实例(实例编号, Cookie列表JSON)	按实例编号批量注入 Cookie，支持 HttpOnly / Secure / sameSite（返回成功条数）；注入 HttpOnly 只能走这条，禁止用 JS document.cookie
EdgeView会话_取Cookie实例异步(实例编号, 地址, &完成处理器)	按实例编号异步读回 Cookie（结果含 httpOnly/secure/expires/sameSite），用于校验登录态
EdgeView设置_置用户代理实例(实例编号, 用户代理)	按实例编号改 UA（建议仍用创建弹窗的参数在首次导航前设好）
EdgeView_关闭全部实例()	一次性关闭全部实例并返回数量；关闭主窗口也会连带关闭全部弹窗，不留 msedgewebview2.exe 残留
EdgeView_枚举实例JSON()	返回 [{实例编号,窗口标题,地址,缓存目录,代理,是否弹窗,是否有效}]，用于「已开店铺不重复开、只切前后台」
EdgeView_置实例可见 / 置实例大小 / 取实例大小JSON / 置实例标题	按实例编号控制弹窗显隐、尺寸、标题

典型写法：连续 创建弹窗浏览器(1, "店铺A", …, ".edgeview/a", UA)、创建弹窗浏览器(2, "店铺B", …, ".edgeview/b", UA)，再对各实例 批量置Cookie实例 灌入该店铺导出的 HttpOnly Cookie，然后 导航实例 到目标域。Cookie 列表 JSON 键名用 WebView2 驼峰 name/value/domain/path + 可选 expires（UTC 秒，会话 Cookie 用 -1 或省略）/secure/httpOnly/sameSite（0 None、1 Lax、2 Strict，None 必须同时 secure）；过去的过期时间会被 WebView2 拒绝写入。

内嵌站点：把网页打包成单个 exe（零释放）

「内嵌站点」可以把一个纯前端项目的构建产物（Vite / React / Vue 打包出的静态文件）直接编进 EXE：浏览器对页面的所有请求都在进程内从内存应答，运行期不会向磁盘（包括 %TEMP%）释放任何 HTML/JS/CSS 文件。配合 WebView2 Loader 静态链接，最终交付物就是一个 exe 文件，双击即可运行（无需安装任何东西，目标机保留系统自带的 WebView2 Runtime 即可）。

TIP

「内嵌站点」不是内嵌文件进 EXE 的唯一方式：携带 DLL、图片、数据包等附件请用内嵌资源。两者怎么选见内嵌站点 vs 内嵌资源（选型指南）。

操作步骤

1. 构建 your web 项目（如 npm run build 得到 dist/），把产物复制到项目内某个目录（例如 www/）；
2. 窗口设计器中取消选中任何控件（点击画布空白或按 Esc），右侧属性面板切到窗口属性；
3. 在「当前窗口 / 内嵌站点」分组勾选内嵌站点；
4. 「扫描目录」填 www，点击扫描目录——设计器递归列出目录内全部文件回填清单，并自动推断入口文件；
5. 确认主机名（缺省 embedded.local）与入口文件（如 www/index.html）；
6. 把 EdgeBrowser 控件的「打开地址」设为 https://<主机名>/index.html，构建运行即可。

清单也可以直接在多行文本框里手工编辑（每行一个工作区相对路径）；面板会即时给出中文校验（入口不在清单、文件越出入口目录、数量超限、主机名非法等），与构建时门禁完全同口径。

规则与注意事项

• 内嵌内容以文件清单为准（勾选只是启用，不自动扫描；新增/改名文件后需重新点一次「扫描目录」）。清单内文件内容的修改会随下次构建自动生效（构建时按清单实时读盘）。
• 上限：最多 64 个文件、单个不超过 32MB；全部文件必须位于入口文件所在目录内。
• 页面按 https://<主机名>/<路径> 访问；清单中没有的路径返回 404。页面里全部资源请使用相对/根路径引用（Vite 默认产物即可）。
• 运行期 exe 同目录会创建 .edgeview/<应用> 目录存放 WebView2 用户数据（缓存/Cookie）——这是浏览器运行数据，不是释放的网页文件；目录需可写。
• 交付单文件时直接复制 exe 即可：WebView2 Loader 已静态链接进 EXE、应用清单已内嵌，不再需要 WebView2Loader.dll 或外置 .manifest。
• 需要项目启用 EdgeView 浏览器模块，且窗口上有一个全幅 EdgeBrowser 控件；未满足时构建会给出中文阻断诊断。

无边框网页应用壳

配合窗口属性「边框 = 无边框」，让网页绘制全部界面（含标题栏和最小化/最大化/关闭按钮），原生只保留一个全屏无边的窗口壳：

1. 窗口属性设置「边框 = 无边框」，EdgeBrowser 控件铺满整个窗口（0,0 起，与窗口同宽高），「打开地址」填内嵌站点入口；
2. 网页标题栏空白处 mousedown 时，经 WebView2 postMessage 发送 {"reqId":N,"action":"win.drag"}；右上角按钮分别发送 win.min / win.max / win.close；四边四角热区发送 win.resize（附 edge 命中码 10–17）；标题栏双击可发送 win.max 切换最大化；
3. .lcpp 侧在「创建完毕」里 EdgeView设置_置网页消息(浏览器控件, 真) + EdgeView_绑定控件事件(浏览器控件, "网页消息", &收到网页消息)，收到消息后调用「Win32窗口操作模块」命令：

网页动作	原生命令
win.drag	窗口_开始拖拽(句柄)（阻塞至松手）
win.min	窗口_显示(句柄, 6)
win.max	窗口_是否最大化 判定后 窗口_显示(句柄, 3) 最大化 / 窗口_显示(句柄, 9) 还原
win.resize	窗口_开始边缘缩放(句柄, 边缘代码)
win.close	延迟约 200ms 后 结束()（让应答先送达页面，避免在回调栈里直接销毁窗口）

4. 原生应答统一用 EdgeView脚本_发送JSON消息(控件, 应答) 回 {reqId, ok, maximized}，页面按 reqId 派发回调（postMessage 是单向通道，reqId 回显是页面关联应答的方式）。

NOTE

主窗句柄可用 窗口_按标题查找("窗口标题") 获取（标题即窗口属性里的窗口标题）。拖拽/缩放的模态循环期间网页收不到松开事件属正常现象，页面不应依赖拖拽的应答。

完整可运行的参考工程：仓库 examples/aruile-toolsbox/（网页工具箱：内嵌站点 + 无边框窗口壳 + 圆角 + 网页桥打开网址/窗口控制，仓库内可直接复制打开）；AI 视频自主生产/进阶方案/ 下的 AI智能助手-EdgeView/、Cat小助手-EdgeView/、抖音助手-EdgeView/（三个单文件 exe 样例，不入仓库）。

事件

EdgeView 通过统一事件目录公开 71 项普通 HWND 可达事件（如 导航开始、导航完成、标题改变、网页消息、下载开始、权限请求、Web资源请求 等），事件名使用中文，底层 WebView2 标识、分类和字段说明以模块详情内置文档《EdgeView 事件与接口参考》为准。

两类需要注意的事件：

• 同步决策事件（如 Web资源请求）只在处理器执行期间允许调用对应的 EdgeView事件_* / EdgeView资源_* 决策接口；未设置动作时保留 WebView2 默认行为。
• 部分资源、对象和创建选项接口需要 WebView2 Runtime 150 或更高版本，不满足时模块会给出中文诊断。

完整 API 与异步任务

完整的 271 条命令按任务、导航、脚本、设置、创建选项、会话、下载、查找、打印、媒体、开发者工具、资源、事件、对象、框架、工作线程、扩展、权限、通知、缓冲和安全分组列在 EdgeView 完整 API 参考（electron/docs/modules/edgeview/API.md）中。每条命令均包含签名、参数类型、返回类型、Runtime 要求和说明。

异步命令返回任务 ID，并通过完成处理器交付结果：

```text 任务ID = EdgeView脚本_执行详情异步(演示浏览器, "document.title", &脚本完成)

事件 脚本完成() 任务ID = EdgeView任务_取当前任务ID() 如果 (EdgeView任务_取状态(任务ID) == 1) 调试输出(EdgeView任务_取结果(任务ID)) 否则 调试输出(EdgeView任务_取错误(任务ID)) 结束 EdgeView任务_释放(任务ID) 结束 ```

常见故障排查

• 创建失败或页面空白：确认目标机已安装 WebView2 Runtime，并检查构建输出中的中文诊断和 HRESULT。
• 修改创建选项不生效：独占用户目录、扩展、Runtime 通道、脚本区域等创建期选项修改后必须调用 `EdgeView创建选项_重建控件` 或重新创建控件。
• 控件参数报类型错误：`controlRef` 必须写裸控件名，例如 `演示浏览器`，不能写成 `"演示浏览器"`。
• 事件处理器未触发：处理器参数必须使用 `&处理器名`；确认事件名来自 71 项统一事件目录。
• 资源正文读取失败：`EdgeView资源_读响应正文异步` 需要 Runtime 150，并且响应句柄必须在事件上下文有效期内交给任务。

安全边界

EdgeView 不向 `.lcpp` 暴露 COM、IStream、IUnknown、裸 HWND/HANDLE 或任意 Host Object；文件、网络响应和脚本结果通过受管句柄、文本、JSON、十六进制或明确文件路径传递。代理地址、虚拟主机、自定义协议和权限设置均经过模块校验，不能借助命令注入额外 Chromium 参数。

依赖与平台限制

• 仅支持 Windows（Win32 / x64，MSVC 工具链）。
• 依赖系统 WebView2 Runtime（Evergreen）；基础事件最低基线为 SDK 1.0.3537.50 / Runtime 141。
• 导出的 exe 与 F5 构建产物需要 WebView2 Runtime 存在于目标机器。

相关页面

• CEF3 浏览器模块 / FBro 指纹浏览器模块 —— 三种浏览器内核怎么选
• 窗口设计器 —— 控件拖放与事件绑定
• 构建与运行 —— F5 编译运行