Skip to content

webview2.md

Latest commit

 

History

History
88 lines (54 loc) · 8.03 KB

webview2.md

File metadata and controls

88 lines (54 loc) · 8.03 KB
Raw

WebView2 开发说明

构建

开发环境：Windows 10 或更高版本、支持 .NET 6/WPF 的 .NET SDK，以及已安装并至少启动过一次的希沃白板 5。本项目保持宿主要求的 net6.0-windows，不随意升级宿主依赖。已验证宿主版本为 5.2.4.11582；其他版本需要实机验证。

dotnet restore EasiPlugin.Webview2.sln
dotnet build EasiPlugin.Webview2.sln -c Release

SDK 和 WebView2 从 NuGet.org 还原，不需要仓库内的本地 SDK 安装包。构建会读取本机希沃安装信息，SDK 也可能注册本地调试插件。安装产物生成于 bin/Release，不提交到源码仓库；发布二进制时应作为 GitHub Release 附件上传。

可选调试配置：运行 powershell -NoProfile -File scripts/Configure-Debug.ps1，从本机注册表生成 launchSettings.json。该文件包含本机安装路径，已被 Git 忽略。

验证

powershell -NoProfile -File tests/Run-Smoke.ps1
powershell -NoProfile -File tests/Run-PluginLoadProbe.ps1
powershell -NoProfile -File scripts/Test-Publish.ps1

冒烟测试使用独立 WPF 进程验证真实浏览器、双指输入、离线资源、状态同步、取消和异常边界；原生属性面板检查使用与本机希沃一致的 x86 .NET 运行时。加载探针分别验证 x86/x64 Loader 及加载失败后的恢复。上述测试不自动关闭用户正在编辑的课件。

插件自己的事件和异步入口观察异常，文件扫描、打包、解包、截图处理和缓存清理在后台执行并传递取消令牌。WPF 与 WebView2 控件操作保留在 UI 线程。不支持取消的原生异步操作仍观察其最终异常，并检查过期结果。插件是进程内扩展，不能承诺隔离所有原生崩溃。

错误日志位于 %LOCALAPPDATA%/EasiPlugin.Webview2/errors.log；提交问题前请自行去除网址、路径等个人信息。不要上传浏览器 Profile、课件、离线网页缓存或用户数据。

结构

插件将 WebView2CompositionControl 放入希沃 Element 的 WPF 视觉树内。浏览器跟随元素移动、缩放，不创建外部浏览器窗口。SDK 为 Microsoft.Web.WebView2 1.0.4022.49，目标框架保持宿主需要的 .NET 6/WPF。

使用与设置

  • 备课页右键选择“插入 WebView2”，新元素直接打开内置设置页。
  • 内置页或右侧“属性 → WebView2”可配置网址、交互与静音，并保持状态同步。仅在已保存网址变化时覆盖地址框，不清除未提交的网址草稿。
  • 关闭交互后可用希沃选中、移动和缩放元素；开启后由网页承接鼠标、触控及键盘输入。
  • 网页取焦点时，Ctrl+V 等快捷键交给浏览器处理，阻止其触发画板的元素粘贴；内置设置页同样适用。
  • 授课时选中元素可使用重新加载、静音和交互开关。此元素的默认克隆按钮隐藏，普通编辑复制命令仍可使用。
  • 属性页可手动截图更新缩略图。未保存截图时使用默认占位图，静态预览不必启动浏览器。

生命周期与预加载

  • Shell 就绪后预建共享 CoreWebView2Environment 和一个空闲浏览器，不导航示例页面。浏览器控制器依赖画板的 AdornerLayer；无法挂载时仅预热环境。
  • 按宿主进程架构指定安装包中的 x86/x64/arm64 WebView2Loader.dll，不按操作系统位数选择。
  • 已初始化的合成浏览器只在同一原生窗口内复用。备课与放映使用不同窗口时重建浏览器，避免浏览器取焦点激活备课窗口；跨窗口会重新载入网页，不保留 JavaScript 内存状态。
  • 每个元素拥有独立浏览器会话，共享环境不代表共享网页状态。
  • 向后寻找两页包含网页的页面，最多保留三个额外预加载浏览器；备课当前页也可预备实例，供同一原生窗口内的模型接管。取消后的预加载不得处置已移交给元素的浏览器。
  • 隐藏或卸载时静音并尝试挂起；再次显示时恢复。挂起是否成功由 Runtime 决定，网页业务逻辑是否就绪不能仅靠导航完成判断。
  • 切换课件取消旧任务并逐个释放会话。文件检查、打包、解包、哈希和缩略图处理在后台执行；WPF 与浏览器控制器操作保留在 UI 线程。
  • 同步回调、async void 和 Dispatcher 调度建立局部异常观察边界。不使用会吞掉希沃自身错误的全局异常处理器。原生 SDK 不支持取消的操作仍观察最终异常并拒绝过期结果。

离线资源与保存

HTML 导入会扫描并打包入口所在文件夹，经用户确认后纳入课件资源。上限为 20000 个文件、256 MB，检查路径越界、链接及不安全 ZIP 条目。网页资源必须位于入口目录及子目录，外部 CDN 和在线接口不会自动下载。

离线文件映射到独立虚拟 HTTPS 来源，可使用相对 CSS、图片、JavaScript、ES 模块及 fetch JSON，不启动 HTTP 服务。手动输入 file URI 是本机路径引用，不等于离线打包。

自定义 SaveInfo 经希沃原生保存机制记录位置、大小、地址、交互、静音、资源包和截图引用。资源使用宿主 Uri 随 ENBX 保存并在换机时解析。存储契约 ID EasiPlugin.WebView2.Canvas 保持稳定，不能因为修改产品名称而更改它。

元素设置进入宿主撤销流程；状态刷新不创建额外撤销记录。再次打开课件会重新加载网页，不会自动还原 JavaScript 内存状态。没有安装插件的设备对自定义元素的降级行为尚未完成验证。

缓存与用户数据

缓存位于 %LOCALAPPDATA%/EasiPlugin.Webview2/Offline，浏览器资料位于同级 Profile，错误写入 errors.log。

清理只处理可识别的插件自有闲置缓存，保留运行中、撤销可能使用的资源和近期导入包；不删除课件、原始 HTML、宿主资源或浏览器 Profile。跨进程互斥和租约防止另一个希沃进程仍在使用时误删。删除元素不立即销毁撤销仍需引用的离线资源。

Cookie、网站登录及本地存储不随课件迁移，也不按希沃账号隔离。同一 Windows 用户切换希沃账号时，这些资料仍可能共享。

内置设置 API 与安全边界

内置页提供 window.easiWebview2.getState()、setAddress()、setInteraction()、setMuted() 和 importHtml()。通信使用 WebView2 消息接口，不暴露任意 .NET 对象或文件系统 API。

只在备课模式且明确打开内置设置页时接受命令，同时验证消息来源及当前顶层网页为固定内置地址，检查协议版本、参数类型、命令和消息长度。普通网页、导入 HTML 和其他来源的消息不会获得元素修改权限。内置页 CSP 禁止外部连接、iframe 和第三方脚本。

当前禁止设备权限、网页下载和不支持的外部协议；新窗口请求转为当前浏览器内导航。支持 HTTP(S) 和通过原生入口选择的本地 HTML，不执行 javascript 或系统协议。

性能与验证边界

合成控件支持 WPF 选框、工具和遮罩覆盖浏览器，但其 GraphicsCaptureSession 路径可能比普通 HWND WebView2 帧率低，DRM 内容也受限。这不是 Unity GPU 纹理零拷贝方案，不承诺稳定 60/120 FPS。插件不持续逐帧截图。

在目标大板上应验证实际呈现帧率、首次展示延迟、缩放帧时间、输入延迟、多屏 DPI、GPU/CPU 和多个实例的内存占用。自动测试中的双指事件不等于真实触摸屏验收。已验证宿主为 5.2.4.11582，其他宿主版本需要实机验证。

构建、测试、发布候选扫描命令和许可说明见根目录 README。构建会自动从当前引用的 WebView2 NuGet 包复制 LICENSE.txt 和 NOTICE.txt 到安装包，无需在源码仓库维护副本。

参考：微软 WPF WebView2 说明、本地内容、安全建议。