WebView 文档

文档介绍

本文档使用 DocForge 构建： dashixiong47/DocForge

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

支持引擎UE 5.0 - 5.7

平台Win64

推荐图形接口推荐 D3D12，D3D11 为兼容回退

本地网页目录Plugins/WebView/Content/WebView

适用场景

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

HUD / 主界面 / 设置页

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

项目内本地网页 UI

与 Unreal 的双向通信页面

功能概览

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

支持本地页面、远程页面和 JS 双向通信。
支持在 UMG 中直接放置控件，不要求你先写自己的 Slate 包装。
支持反射调用、委托调用、Unreal -> JS 调用。
支持基础输入、拖拽测试、透明点击透传、IME 输入法链路。
插件自带 CEF 运行时，不依赖宿主引擎内置版本。

如果你需要网页侧桥接库，可以下载 WebSDK。压缩包内提供网页桥接脚本，适用于 TypeScript、JavaScript 模块和单 HTML 直接引入三种接法。

如果你想直接查看打包后的测试页面效果，可以打开测试例子。

视频预览

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

插件内 Demo 页面实录

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

打开视频直链

接入方式

通常只需要把插件放进项目，然后确认运行时文件完整即可。

将插件目录放到 Plugins/WebView。
确认插件目录内存在完整的 Source/ThirdParty/CEF 运行时，尤其是 libcef.dll。本地开发如果需要运行 CEF 子进程，请使用随源码提供的 Source/Programs/WebViewHelper 构建辅助程序。
项目在 Windows 下使用 D3D11 或 D3D12。
推荐在 D3D12 下运行，以获得更好的页面渲染性能与视频表现。

如果你想修改本地网页根目录，可在 Project Settings -> Game -> WebView 中调整 本地网页根目录 与 本地域名。默认目录是 Plugins/WebView/Content/WebView/Web，默认域名是 webview.local。

如何使用

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

方式 A：直接拖入 UMG

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

方式 B：继承底层控件

继承 UWebViewUserWidget。适合需要自定义事件处理、桥接回复和页面行为的项目。

插件内已附带演示内容。你可以直接打开 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。

变量配置说明

以下配置项控制 WebView 的页面加载、窗口行为、渲染分辨率、帧率与输入透传。

地址Text

网页地址。支持远程地址、普通域名，以及 /index.html 这类本地路径。

启动时打开开发者工具Bool

在编辑器环境下创建浏览器后自动打开开发者工具。

在当前视图打开新窗口链接Bool

把 target=_blank 或 window.open 直接改成当前视图内打开，而不是创建新窗口。

允许创建网页弹窗Bool

允许创建网页弹窗。通常建议关闭，除非你的页面明确依赖独立弹窗。

同步帧Bool

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

分辨率模式Enum

设置浏览器实际渲染分辨率的来源。Auto 跟随当前控件尺寸，Manual 使用固定宽高。

手动渲染宽度 / 手动渲染高度Int

手动分辨率模式下的固定渲染尺寸。适合用来做高分辨率界面的性能控制。

最大帧率Int

浏览器离屏渲染的最大帧率上限。复杂页面建议按项目需要设置，而不是盲目拉高。

透明区域点击透传Bool

在点击透明区域时把输入透传给底层游戏，用于非矩形 UI 或透明网页区域。

透明透传目标颜色 / 透明透传颜色容差Color + Int

设置透明点击透传的目标颜色与容差。默认以完全透明为判断标准。

第三方声明

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

CEF / Chromium Runtime
来源：cef_binary_146.0.12+g6214c8e+chromium-146.0.7680.179
运行时目录中保留了 LICENSE.txt 与 CREDITS.html，用于随包分发时的第三方说明。
MDN flower video sample
文件：Plugins/WebView/Content/WebView/Web/media/flower.mp4 与 flower.webm
来源：MDN interactive examples 示例媒体
授权：CC0 示例资源，用于演示本地视频播放能力。

已知限制

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

当前仅实现 Win64。
D3D11 是兼容回退路径，复杂页面和高分辨率场景下性能不如 D3D12。
视频网站兼容性不应默认承诺，尤其是依赖专有编解码器的站点。