WebView

WebView 2.0.0 文档，覆盖 Win64/Mac/Linux 桌面 CEF WebView、Android/iOS 原生 WebView、本地网页 UI、Unreal 桥接、配置变量和平台限制。

v2.0.2 UE 5.0 - UE 5.7 Win64 / Mac / Linux / Android / iOSDesktop CEF / Native Mobile WebViewWeb UI

文档介绍

Project Maintained Web UI

WebView for Unreal Engine

本文档说明插件能力、接入流程、蓝图使用方式、桥接模式和主要配置变量。

GIT dashixiong47/DocForge本文档使用 DocForge 构建 FAB Fab Marketplace插件可在这里查看或购买 DC Discord讨论反馈 / Discord DSX Forum讨论反馈 / Forum
支持引擎UE 5.0 - 5.7
平台Win64 / Mac / Linux / Android / iOS
推荐图形接口推荐 D3D12，D3D11 为兼容回退
本地网页目录Plugins/WebView/Content/WebView

适用场景

当前最适合以下类型的项目界面。

01HUD / 主界面 / 设置页

适合常驻或弹出的游戏 UI，把 HTML 页面作为可维护的菜单界面。

02任务面板 / 商店面板 / 活动页

适合快速迭代运营内容，用网页资源驱动活动、商店和任务页面。

03项目内本地网页 UI

适合打包本地页面，也支持远程页面在项目内统一呈现。

04与 Unreal 的双向通信页面

适合需要 UE 与网页双向通信的工具面板、交互页面和调试界面。

2.0.0 更新

WebView 2.0.0 补齐跨平台支持，并调整桌面 CEF Runtime 的交付方式：插件主体不再随包内置完整 CEF Runtime，而是通过下载器自动准备。

首次进入编辑器或首次创建 WebView 时，插件会自动检查当前平台的桌面 CEF Runtime；如果缺失，会启动下载与安装流程。你也可以从 WebView 工具栏手动打开下载器，用于重试、修复或提前准备 Runtime。

CEF Runtime 下载器

  • 主插件包不再包含完整桌面 CEF Runtime，FAB 下载包体更轻，项目集成也更干净。
  • 第一次进入编辑器 / 第一次创建 WebView 时会自动检查 Runtime，缺失时自动进入下载流程。
  • 工具栏提供手动下载 / 安装入口，适合离线准备、重新下载、修复损坏文件或切换平台后重新准备 Runtime。
  • Win64 / Mac / Linux 桌面端使用 CEF / Chromium Runtime；Android / iOS 使用系统原生 WebView，不下载 CEF。

移动端原生 WebView

  • 新增 Android 原生 WebView 支持，不引入移动端 CEF。
  • iOS 使用平台 WebView 路径加载插件内本地 Web 内容。
  • Android 会先把随包 Web 文件抽取到应用可读目录，再交给系统 WebView 加载，避免直接 file:// 读取包内/OBB 路径导致黑屏。
  • 移动端继续使用 WebView 页面与 Unreal 之间的桥接模式，适合本地 HTML UI 与轻量 Web 内容。

平台文件结构

  • Android 实现在 Source/WebView/Private/Platform/Android/WebViewUserWidgetAndroid.cpp。
  • iOS 实现在 Source/WebView/Private/Platform/IOS/WebViewUserWidgetIOS.mm。
  • 桌面 CEF 逻辑与 Android / iOS 原生实现拆分到独立平台文件，便于后续维护和排查。

打包与版本

  • 插件版本更新为 2.0.0。
  • Android 构建路径适配 UE 5.0 / NDK r21，避免 C++20 标准导致的编译问题。
  • 已使用 WebView 插件 Demo 地图完成 Android 打包与启动验证。

注意事项

  • 桌面端首次使用时需要准备对应平台的 CEF Runtime；通常会自动检查并下载，也可以从 WebView 工具栏手动处理。
  • Android 与 iOS 使用系统/平台原生 WebView，不走桌面 CEF 渲染路径。
  • 如果真机仍出现黑屏，请优先提供 logcat 中的 WebView、chromium、AndroidRuntime 和 LogWebViewUserWidget 相关日志。

功能概览

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

  • 支持本地页面、远程页面和 JS 双向通信。
  • 支持在 UMG 中直接放置控件，不要求你先写自己的 Slate 包装。
  • 支持反射调用、委托调用、Unreal -> JS 调用。
  • 支持基础输入、拖拽测试、透明点击透传、IME 输入法链路。
  • 桌面端使用 CEF / Chromium 后端，但完整 CEF Runtime 不再随主插件包内置；首次进入或首次创建 WebView 时会自动检查并下载，也可通过工具栏手动准备。
如果你需要网页侧桥接库，可以下载 WebSDK。压缩包内提供网页桥接脚本，适用于 TypeScript、JavaScript 模块和单 HTML 直接引入三种接法。
如果你想直接查看打包后的测试页面效果，可以打开 测试例子。

视频预览

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

插件内 Demo 页面实录

该视频对应插件内网页示例 Plugins/WebView/Content/WebView/Web/index.html 的实际展示内容，可用于快速判断界面风格、交互流畅度和视频播放效果。

PC:打开视频直链

IOS:打开视频直链

接入方式

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

  1. 将插件目录放到 Plugins/WebView。
  2. 桌面端不再要求主插件包内预置完整 Source/ThirdParty/CEF；首次进入编辑器或首次创建 WebView 时会自动检查 Runtime，缺失时自动下载并安装。
  3. 也可以从 WebView 工具栏手动打开下载器 / 安装器，用于离线准备、重新下载或修复 Runtime。
  4. Win64 推荐使用 D3D12 获得更好的页面渲染性能与视频表现；D3D11 保留为兼容回退。Android / iOS 使用系统原生 WebView。
如果你想修改本地网页根目录，可在 Project Settings -> Game -> WebView 中调整 本地网页根目录 与 本地域名。默认目录是 Plugins/WebView/Content/WebView/Web，默认域名是 webview.local。

如何使用

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

方式 A：直接拖入 UMG

在 UMG 中使用 UWebViewWidget。适合大多数项目快速接入。

方式 B：继承底层控件

在内容浏览器右键菜单里的用户界面里选择WebViewUserWidget即可

插件内已附带演示内容。你可以直接打开 Plugins/WebView/Content/WebView 下的资源，并进入 Demo 关卡查看交互示例、桥接示例、视频播放和拖拽吸附测试。
本地页面默认放在 Plugins/WebView/Content/WebView。例如设置地址为 /index.html 时，插件会映射到本地网页目录并通过 http://webview.local/index.html 访问。

拖动专用低延迟模式

为了避免普通 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: []
});
建议只在真正持续拖动的交互里打开这个模式，例如背包拖拽、节点拖拽、时间轴拖拽或大型面板拖动，不要对普通 hover 或任意 mousemove 常开。

桥接方式

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

1. 反射调用

网页侧使用 WebView.call("Foo") 或 WebView.send("Bar")，Unreal 侧分别映射到 Call_Foo 与 Send_Bar。

2. 委托调用

如果你不想直接依赖反射函数名，可以在蓝图里监听 JS 事件 与 JS 函数调用 两个委托，然后手动回复结果。

3. Unreal 调 JS

使用 CallWeb、CallWebJSON 等入口从 Unreal 调网页，网页侧通过 WebView.on(...) 注册回调。

插件配置变量说明

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

本地网页根目录String

对应 Project Settings -> Game -> WebView -> 本地网页根目录。默认值为 Plugins/WebView/Content/WebView/Web。如果改成项目中的其他目录，例如 Doc/WebUI/dist，还需要把同一路径加入项目打包设置。

本地域名String

对应 Project Settings -> Game -> WebView -> 本地域名。默认值为 webview.local，用于把 /index.html 这类本地路径解析成可访问地址。

如果你把网页资源放到项目其他目录，例如 Doc/WebUI/dist，除了修改 本地网页根目录 外，还应把同一路径加入项目打包设置。若希望进入包体容器可使用 DirectoriesToAlwaysStageAsUFS，若希望以散文件形式发布可使用 DirectoriesToAlwaysStageAsNonUFS。

蓝图 API

Blueprint API

蓝图 API

以下节点覆盖 WebView User Widget 的页面控制、输入穿透、帧率设置和 JavaScript Bridge。节点预览按 Unreal Blueprint 风格渲染，便于对照蓝图实现。

设置 URL

C++URL property 返回值void 参数URL 用途设置 WebView 页面地址。 场景运行时切换本地 /index.html、远程 https 页面或普通域名后，再调用 Restart Browser。

重启浏览器

C++RestartBrowser 返回值void 参数None 用途关闭并重新创建当前浏览器实例。 场景URL、窗口行为或关键设置变更后重新加载页面。

打开 DevTools

C++OpenDevTools 返回值void 参数None 用途打开 Chromium DevTools。 场景调试 HTML、CSS、JavaScript、网络请求和控制台错误。

设置最大帧率

C++SetMaxFPS 返回值void 参数Max FPS 用途调整浏览器离屏渲染最大帧率。 场景按 UI 动画、视频和项目性能预算控制渲染开销。

获取当前 FPS

C++GetFPS 返回值int32 参数None 用途返回最近一秒测得的 WebView 刷新帧率。 场景确认页面是否正在渲染、是否达到预期帧率。

允许游戏同时接收键盘输入

C++bAllowGameInputWhileFocused 返回值void 参数Allow Game Input While WebView Focused 用途WebView 获得焦点时仍让 Unreal 侧收到键盘快捷键。 场景HTML 菜单获得焦点后，仍可用 Shift / Escape 关闭菜单。

调用网页方法

C++CallWeb 返回值void 参数Method 用途调用网页侧注册的方法，不传参数。 场景UE 主动通知 HTML 执行显示、隐藏、刷新等动作。

调用网页方法 String

C++CallWebString 返回值void 参数Method, Value 用途调用网页侧方法并传入字符串。 场景向 HTML 传递语言、玩家名、状态文本或简单参数。

调用网页方法 JSON

C++CallWebJSON 返回值void 参数Method, JsonObjectWrapper 用途调用网页侧方法并传入结构化 JSON。 场景传递背包、商店、任务列表、设置页等复杂数据。

JS 事件

C++OnJSEvent 返回值Event 参数Method, Data 用途网页调用 WebView.send(name, data) 时触发。 场景HTML 按钮通知 UE 执行不需要返回值的逻辑。

JS 函数调用

C++OnJSFunction 返回值Event 参数Method, Data, Request Id 用途网页调用可等待回复的函数时触发。 场景HTML 请求 UE 查询数据，稍后用 Request Id 回复。

回复 JS 函数 JSON

C++ReplyJSFunctionJSON 返回值bool 参数Request Id, Data 用途向网页侧函数调用返回 JSON 数据。 场景处理 JS Function Call 后，把 UE 查询结果返回给 HTML。

变量配置说明

变量配置说明

这些配置控制页面加载、窗口行为、渲染分辨率、帧率和输入透传。常规项目只需要设置 URL；菜单覆盖层和高频动画页面再按场景调整输入与渲染选项。

01页面加载

URLText/index.html

网页地址。支持 http(s) 远程地址、普通域名，以及 /index.html 这类本地路径。本地路径会根据 Project Settings 中的本地域名和网页根目录解析。

建议： 运行时修改 URL 后，当前版本请调用 Restart Browser 让页面重新加载。
Open DevTools on StartupBoolfalse

创建浏览器后自动打开开发者工具。只建议在编辑器调试网页时启用。

建议： 排查 CSS、JavaScript、网络请求或 Bridge 消息时开启，发布内容中保持关闭。

02窗口行为

Open New Window Links in Current ViewBooltrue

把 target=_blank 和 window.open 链接直接放到当前 WebView 里打开，而不是创建新的浏览器弹窗。

建议： 菜单、活动页、商店页通常建议开启，避免网页弹出额外窗口。
Allow Web PopupsBoolfalse

允许网页创建独立弹窗。只有当你的页面确实依赖独立 popup 时才需要。

建议： 大多数游戏 UI 保持关闭；需要 OAuth、支付或外部弹窗流程时再评估。

03渲染与性能

Sync FramesBoolfalse

开启后由控件主动驱动浏览器同步刷新；关闭后浏览器按自身节奏刷新，通常更适合动画、视频和半透明效果。

建议： 普通网页保持默认关闭；需要严格跟随 UE 帧节奏时再开启。
Resolution ModeEnumAuto

控制浏览器实际渲染分辨率。Auto 跟随控件尺寸；Manual 使用固定宽高。

建议： 响应式 UMG 使用 Auto；需要固定网页画布或稳定性能预算时使用 Manual。
Manual Render Width / HeightInt1920 x 1080

Manual 模式下的固定渲染尺寸。数值越高越清晰，也会增加浏览器渲染和纹理拷贝成本。

建议： 高分辨率 UI 可以从 1280x720 或 1920x1080 开始测试，再根据清晰度和性能调整。
Max FPSInt120

离屏浏览器渲染最大帧率上限。复杂网页不建议盲目拉高。

建议： 静态菜单可降低；视频、拖拽或连续动画页面可以按实际体验提高。

04输入透传

Allow Game Input While WebView FocusedBoolfalse

WebView 获得焦点后，键盘事件仍发送给浏览器，同时对 Slate 返回 Unhandled，让 Unreal 也能收到 Shift、Escape 等热键。

建议： 适合游戏内菜单覆盖层，让 HTML UI 保持焦点，同时游戏仍可响应关闭菜单等快捷键。
Transparent Click PassthroughDeprecatedfalse

旧版基于透明像素/颜色采样的点击透传。该方案已标记废弃，后续版本会移除。

建议： 新项目不要再依赖它；请优先使用网页 CSS 的 pointer-events。
Passthrough Target Color / ToleranceDeprecatedrgba(0,0,0,0) / 8

旧版透明点击透传的目标颜色和容差。默认以完全透明作为判断标准。

建议： 仅用于兼容旧项目；新页面使用 pointer-events: none 和 pointer-events: auto 控制命中区域。
推荐做法：让不需要接收鼠标的网页区域使用 CSS pointer-events: none;，并在按钮、输入框、面板等需要交互的元素上恢复 pointer-events: auto;。pointer-events 的默认值就是 auto。

05JS Bridge 委托

JS EventDelegate

网页侧调用 WebView.send(...) 时触发，参数包含方法名和 JsonObjectWrapper 数据。

建议： 适合打开面板、播放音效、请求关闭 UI 这类不需要返回值的事件。
JS Function CallDelegate

网页侧调用 WebView.call(...) 时触发，除了方法名和数据外，还会提供 RequestId 用于回传结果。

建议： 适合查询玩家信息、读取设置、请求服务端数据等需要 Promise 返回值的流程。

第三方声明

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

  • 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 示例资源，用于演示本地视频播放能力。

已知限制

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

  • 桌面端通过插件下载器 / 安装器准备 CEF / Chromium Runtime，支持 Win64 / Mac / Linux；Android 与 iOS 使用系统原生 WebView 路径。
  • D3D11 是兼容回退路径，复杂页面和高分辨率场景下性能不如 D3D12。
  • 视频网站兼容性不应默认承诺，尤其是依赖专有编解码器的站点。