Skip to content

03 Widget Configuration

Jump to bottom
starTechnology1994 edited this page Aug 7, 2026 · 1 revision

03 WebNativeWidget 参数配置

本章完整列出 WebNative Browser 控件（UMG Widget）的全部公开参数、事件与函数，并说明推荐的配置组合。

1. Details 面板总览

Widget Details 参数总览
图 3-1 WebNative Browser 控件 Details 参数总览

所有参数按 WebNative | Page / Rendering / Input / Message 分类组织，以下逐项说明。

2. 页面参数（WebNative | Page）

参数 类型 默认值 说明
InitialURL FString https://www.bilibili.com 初始加载 URL，可为 http(s) 地址、本地资源路径或file://
ViewSize FIntPoint (1280, 720) 固定分辨率模式下 CEF 浏览器视图尺寸（≥1）
bAutoResizeToWidget bool true 自动跟随 Widget 屏幕尺寸调整视图分辨率

说明：

  • bAutoResizeToWidget = true 时，浏览器分辨率跟随控件实际大小，适合大多数 UI 场景。
  • 需要固定渲染分辨率（如保证 4K 截图质量或控制开销）时：关闭自动缩放，设置 ViewSize，运行期可用 SetViewResolution(FIntPoint) 动态修改。

3. 渲染参数（WebNative | Rendering）

参数 类型 默认值 说明
FrameRate int32 60 帧率上限（1~120）
bUseGpuAcceleratedRendering bool true 是否启用 GPU 加速渲染
bAllowCpuRenderFallback bool true GPU 失败时是否回退 CPU 软渲染（仅 GPU 开启时生效）

说明：

  • FrameRate 与智能帧率调节配合：页面静止时自动暂停渲染，动画/视频按需唤醒，实际开销远低于"固定 60 帧"。
  • 国产 GPU 或虚拟机等环境若出现渲染异常，可关闭 GPU 加速（或通过 06-CEF 参数配置 的 offgpu 全局关闭）。
  • bAllowCpuRenderFallback 建议保持 true，保证极端环境下页面仍可显示。

4. 输入参数（WebNative | Input）

参数 类型 默认值 说明
bAcceptsInput bool true 是否接收键盘焦点
bAutoFocusOnMouseDown bool true 鼠标点击时自动聚焦网页
bEnableMouseTransparency bool true 启用鼠标穿透（按页面 alpha 命中测试）
MouseTransparencyAlphaThreshold int32 0 透明像素判定阈值（0~255），像素 alpha 低于该值视为透明，鼠标点击穿透到 UE
MouseTransparencyMaskBlockSize int32 1 alpha 命中测试的像素块大小（1~8）
bForwardUEKeyEvents bool false 开启后，即使焦点在 UE 场景中，键盘事件也会转发给 CEF（用于撤销/重做等需要双重处理的场景）

说明：

  • 鼠标穿透：当页面存在透明区域（如镂空控件、透明 PNG）时，开启 bEnableMouseTransparency 可让鼠标事件穿透到 UE 场景；阈值默认 0 表示仅完全透明处穿透。
  • bForwardUEKeyEvents 典型场景：网页内文本编辑器与 UE 场景同时需要处理 Ctrl+Z/Ctrl+C 等快捷键。

5. 消息参数（WebNative | Message）

参数 类型 默认值 说明
MessageDispatchBudgetPerFrame int32 5000 每帧 JS → UE 消息派发预算（条数，1~100000）

说明：

  • 该参数防止网页高频消息（如每秒千条状态流）压垮游戏线程。
  • 消息超过预算的部分会在后续帧继续派发，不会丢失；业务仍应遵循 02-双向通讯 的"发送变化量"建议。

6. 事件（BlueprintAssignable）

事件 签名 触发时机
OnMessageReceived (FString FunctionName, FString MessageBody) 网页WebNative.send() 调用时
OnLoadStateChanged (bool bIsLoading, bool bCanGoBack, bool bCanGoForward) 页面加载状态变化时
OnUrlChanged (FString URL) 当前 URL 变化时
OnBeforePopup (FString TargetURL, FString TargetFrameName) 页面请求打开新窗口时（可在此拦截并改为当前页加载）
OnLoadEnd (FString URL, int32 HttpStatusCode) 页面加载结束时（含 HTTP 状态码）

7. 公开函数（BlueprintCallable）

函数 参数 说明
LoadURL FString URL 加载指定 URL
GoBack / GoForward — 后退 / 前进
Reload bool bIgnoreCache = false 刷新页面，可选忽略缓存
ExecuteJavaScript FString Script 在页面执行任意 JS 代码
SendMessageToJS FString FunctionName, FString MessageBody 向网页发送消息（网页侧 WebNative.on 接收）
SetFocusToGameViewport — 将输入焦点从页面切回 UE 游戏视口WebNative原生实现（拖拽放置场景用）
GetRawPlatformCursorPos out FVector2D OutScreenPos 获取平台光标的屏幕坐标，能拿到最顶层的鼠标位置,不受界面影响,返回是否有效
DeprojectCursorToWorld FVector2D ScreenPos, out FVector OutWorldPos, out FVector OutWorldDir 屏幕坐标反投影为世界空间射线,建议优先使用这个进行坐标转化操作
SetViewResolution FIntPoint NewSize 设置固定分辨率模式下的视图尺寸
SetAutoResizeToWidget bool bEnabled 动态切换自动缩放
SetForwardUEKeyEvents bool bEnabled 动态切换键盘事件转发
GetViewSize — 返回当前视图尺寸（BlueprintPure）
ShowDevTools / CloseDevTools / ToggleDevTools — 打开 / 关闭 / 切换 DevTools 调试窗口

下一步

Clone this wiki locally