WebView

文档介绍

适用场景

2.1.1 更新

WebView 2.1.1 重点改进本地页面启动稳定性、显式字体缓存和跨平台键盘输入准确性。

Windows 媒体支持

• 支持 H.264 视频播放，包括 H.264 编码的 MP4 文件。
• 新增 WebRTC 支持，可用于网页中的实时通信场景。
• 新版 Windows Runtime 通过下载器安装；旧 Runtime 不会自动获得 H.264 或 WebRTC 能力。

本地网页目录与自动打包

• Local Web Root 现在是目录选择器，支持项目内相对路径和项目外绝对路径。
• 选择目录后，插件自动维护 DirectoriesToAlwaysStageAsNonUFS，无需再手动填写 Packaging Settings。
• Windows 编辑器对项目外目录使用 NTFS junction，切换目录时只更新文件系统链接，不复制网页文件；真正的复制发生在 UAT 打包阶段。
• Packaged File Extensions 控制项目外目录在打包时允许复制的后缀；清空数组表示不过滤。

启动字体缓存

• Preload Local Fonts On Startup 现在使用字体文件数组，支持在一个文件对话框中多选 woff/woff2/ttf/otf/eot 字体。
• 所选字体必须位于当前 Local Web Root 下；目录外的文件会被拒绝并提示。
• UE 启动时会在创建第一个 WebView 页面前读取配置字体到进程缓存，减少本地页面切换时的字体回退闪烁。

更准确的键盘输入 SDK

• Windows 保留原生键盘消息所需的物理按键数据，可更准确地区分小键盘、扩展键以及左右修饰键；Mac/Linux 使用 UE 平台按键事件进行统一映射。
• 网页侧可通过 WebView.setKeyboardBindingCaptureEnabled(true) 开启通用按键绑定捕获，并监听 WebView.on("NativeKeyDown", callback)。
• 捕获数据包含 code、key、keyCode、location、修饰键状态和 repeat，便于网页实现可靠的按键绑定页面。

功能概览

插件定位是项目侧可维护的网页界面方案，而不是依赖引擎内置 WebBrowser 的黑盒包装。

• 支持本地页面、远程页面和 JS 双向通信。
• 支持在 UMG 中直接放置控件，不要求你先写自己的 Slate 包装。
• 支持反射调用、委托调用、Unreal -> JS 调用。
• 支持基础输入、拖拽测试、透明点击透传、IME 输入法链路。
• 桌面端 Win64 / Mac / Linux 使用插件管理的 CEF / Chromium Runtime；Android / iOS 使用系统原生 WebView。
• Windows CEF Runtime 从 2.1.0 开始支持 H.264 视频播放和 WebRTC。
• 主插件包不再内置完整桌面 CEF Runtime；桌面端首次使用时由插件下载器准备对应平台 Runtime。

视频预览

下面这段视频展示了插件内 index.html 示例页面的真实运行效果，包括本地页面内容、交互区块与媒体播放表现。

接入方式

通常只需要把插件放进项目；桌面端 CEF Runtime 会在首次进入编辑器或首次创建 WebView 时自动检查并下载，也可以通过工具栏手动准备。

1. 将插件目录放到 Plugins/WebView。
2. 桌面端 Win64 / Mac / Linux 使用插件管理的 CEF Runtime；Android / iOS 使用系统原生 WebView，不在移动端打包 CEF。
3. 首次使用时让插件完成 Runtime 下载；也可以从 WebView 工具栏手动下载、重试或修复当前平台 Runtime。
4. Windows 推荐使用 D3D12 获得更好的页面渲染性能与视频表现；D3D11 保留为兼容回退。Windows 的 H.264 和 WebRTC 使用 2.1.1 对应的 Runtime 包。
5. Android 会先把随包网页文件抽取到应用可读目录，再交给系统 WebView 加载；如果真机出现黑屏，请先检查 logcat 中的 WebView、chromium、AndroidRuntime 和 LogWebViewUserWidget 相关日志。

如何使用

你可以直接在 UMG 中使用包装控件，也可以继承底层用户控件做更细的扩展。

拖动专用低延迟模式

为了避免普通 hover / 鼠标移动把网页动画帧率抬高到超出配置上限，插件当前把“额外加帧 + 催帧”限制为网页主动通知的拖动阶段专用优化。

• 普通鼠标移动、hover、滚轮和点击，默认按正常浏览器节奏执行，不会仅因为移动鼠标就进入高帧率模式。
• 只有网页明确告诉引擎“现在进入拖动阶段”时，插件才会启用低延迟 boost 和后续催帧。
• 示例页面 index.html 已经在两个拖动区域内接好了这套逻辑，可直接作为接入参考。

// drag begin
window.WebView.send("SetDragLowLatency", {
  active: true,
  sources: ["free-drag"]
});

// drag end
window.WebView.send("SetDragLowLatency", {
  active: false,
  sources: []
});

桥接方式

当前支持三种主要调用模式。

插件配置变量说明

这部分是插件级配置，主要影响本地网页目录映射和项目打包时的资源组织方式。

蓝图 API

变量配置说明

第三方声明

以下为当前插件内直接使用或随插件分发的第三方内容说明。

• CEF / Chromium Runtime
  来源：cef_binary_146.0.12+g6214c8e+chromium-146.0.7680.179
  桌面 CEF Runtime 不再作为主插件包的一部分分发，而是通过插件下载器 / 安装器准备。安装后的 Runtime 保留 LICENSE.txt 与 CREDITS.html，用于第三方说明。
• MDN flower video sample
  文件：Plugins/WebView/Content/WebView/Web/media/flower.mp4 与 flower.webm
  来源：MDN interactive examples 示例媒体
  授权：CC0 示例资源，用于演示本地视频播放能力。

已知限制

这些限制建议在文档和商店页面里直接说明。

• 桌面端支持 Win64 / Mac / Linux，移动端支持 Android / iOS；移动端使用系统原生 WebView，能力边界由平台实现决定。
• D3D11 是 Win64 兼容回退路径，复杂页面和高分辨率场景下性能不如 D3D12。
• H.264 视频播放和 WebRTC 当前仅在 Windows CEF Runtime 提供。其他平台的媒体格式和实时通信能力以系统或平台 CEF 支持为准。
• 项目外网页目录在打包时会按 Packaged File Extensions 过滤；需要发布其他文件类型时请显式加入后缀，或清空过滤数组。
• 视频网站兼容性不应默认承诺，尤其是依赖专有编解码器的站点。