Skip to content

12 API Reference

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

12 API 参考

面向开发者的完整 API 参考：UMG Widget 蓝图 API、window.WebNative JS 桥接 API、C++ 高级接口。配置类说明与推荐组合见 03-WebNativeWidget 参数配置 与 06-CEF 参数配置。

1. API 总览

WebNativeBrowser 提供三个层次的 API：

层次 使用方 入口
Widget 蓝图 API 蓝图 / C++ UWebNativeBrowserWidget（UMG 控件），本节 2–4
JS 桥接 API 网页前端 window.WebNative 对象（页面内直接使用），本节 5
C++ 高级接口 C++ 插件开发 IWebNativeBrowserCoreModule / IWebNativeBrowserView，本节 6

2. Widget 属性（BlueprintReadWrite）

控件位于 UMG 面板 WebNative Browser，属性按 WebNative | Page / Rendering / Input / Message 分类。默认值与详细说明见 03-WebNativeWidget 参数配置 第 2–5 节，此处仅列完整清单。

分类 属性 类型 默认值 说明摘要
Page InitialURL FString https://www.bilibili.com 初始加载 URL
Page ViewSize FIntPoint (1280, 720) 固定分辨率模式下视图尺寸（≥1）
Page bAutoResizeToWidget bool true 自动跟随控件尺寸调整分辨率
Rendering FrameRate int32 60 帧率上限（1~120）
Rendering bUseGpuAcceleratedRendering bool true 启用 GPU 加速渲染
Rendering bAllowCpuRenderFallback bool true GPU 失败时回退 CPU 软渲染（仅 GPU 开启时生效）
Input bAcceptsInput bool true 是否接收键盘焦点
Input bAutoFocusOnMouseDown bool true 鼠标点击时自动聚焦网页
Input bEnableMouseTransparency bool true 启用鼠标穿透（按页面 alpha 命中测试）
Input MouseTransparencyAlphaThreshold int32 0 透明像素判定阈值（0~255）
Input MouseTransparencyMaskBlockSize int32 1 alpha 命中测试像素块大小（1~16）
Input bForwardUEKeyEvents bool false 焦点在 UE 时仍把键盘事件转发给 CEF
Message MessageDispatchBudgetPerFrame int32 5000 每帧 JS → UE 消息派发预算（条数，1~100000）

3. Widget 事件（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 状态码）

4. Widget 函数（BlueprintCallable）

函数 签名 说明
LoadURL void LoadURL(FString URL) 加载指定 URL
GoBack void GoBack() 后退到上一页（bCanGoBack 为 true 时生效）
GoForward void GoForward() 前进到下一页
Reload void Reload(bool bIgnoreCache = false) 刷新当前页，可选忽略缓存
ExecuteJavaScript void ExecuteJavaScript(FString Script) 在页面执行任意 JS 代码
SendMessageToJS void SendMessageToJS(FString FunctionName, FString MessageBody) 向网页发送消息（网页侧 WebNative.on 接收）
SetFocusToGameViewport void SetFocusToGameViewport() 将输入焦点从页面切回 UE 游戏视口，并释放 Slate 鼠标捕获（拖拽放置场景用）
ShowDevTools void ShowDevTools() 打开 DevTools
CloseDevTools void CloseDevTools() 关闭 DevTools
ToggleDevTools void ToggleDevTools() 切换 DevTools 显示状态
SetViewResolution void SetViewResolution(FIntPoint NewSize) 设置固定分辨率模式下的视图尺寸（需 bAutoResizeToWidget=false）
SetAutoResizeToWidget void SetAutoResizeToWidget(bool bEnabled) 动态开关自动缩放
SetForwardUEKeyEvents void SetForwardUEKeyEvents(bool bEnabled) 动态开关键盘事件转发
GetRawPlatformCursorPos bool GetRawPlatformCursorPos(FVector2D& OutScreenPos) const 从平台层直接获取光标屏幕坐标（绕过 Slate/CEF 管道，零延迟）
DeprojectCursorToWorld bool DeprojectCursorToWorld(FVector2D ScreenPos, FVector& OutWorldPos, FVector& OutWorldDir) const 屏幕坐标反投影为世界空间射线，自动适配 PIE/窗口/全屏
GetViewSize FIntPoint GetViewSize() const 返回当前视图尺寸（BlueprintPure）

另有 C++ 公开方法 FlushMessagesToJS()（非 BlueprintCallable），用于立即刷出队列中的 UE → JS 消息。

5. JS 桥接 API（window.WebNative）

页面加载完成后，脚本中自动注入 window.WebNative 对象（就绪标志 window.WebNativeReady === true）。

5.1 WebNative.send(functionName, messageBody)

向 UE 发送消息。messageBody 传对象时自动 JSON.stringify，UE 侧收到原始 JSON 字符串。

// 发送结构化数据（自动序列化为 JSON 字符串）
WebNative.send("Device.Toggle", { deviceId: "dev-001", power: true });

// 发送纯字符串
WebNative.send("Hello", "world");

// 返回 true 表示已进入发送队列；对象序列化失败返回 false
const ok = WebNative.send("Notify", { a: 1 });

5.2 WebNative.on(functionName, callback)

注册消息监听，同名事件支持多播（多个回调都会收到，按注册顺序执行；单个回调抛错不影响其他回调）。

WebNative.on("HelloResult", function (raw) {
  const data = JSON.parse(raw); // messageBody 为原始字符串，JSON 需自行解析
  console.log(data.text);
});

5.3 WebNative.off(functionName, callback)

移除监听，必须传入注册时的同一个函数引用（匿名函数注册后无法单独移除）。

function handler(raw) { /* ... */ }
WebNative.on("Event", handler);
WebNative.off("Event", handler); // 传入同一引用才能移除

5.4 WebNativeReady

桥接注入完成后：window.WebNativeReady === true，同时页面会收到一次 WebNativeReady DOM 事件（window.dispatchEvent(new Event('WebNativeReady'))）。推荐用事件监听等待就绪，避免轮询：

window.addEventListener('WebNativeReady', function () {
  // 桥接已就绪，可以安全调用 WebNative.send / on / off
  WebNative.on("HelloResult", function (raw) { console.log(raw); });
});

// 页面加载时注入可能已提前完成，事件可能已派发，需同时兜底判断
function whenReady(fn) {
  if (window.WebNativeReady) { fn(); return; }
  window.addEventListener('WebNativeReady', fn, { once: true });
}

5.5 内部字段（请勿使用）

__facefReady、__facefNative、__receive、__receiveBatch 为桥接内部实现，供插件使用，业务代码不要调用。

6. C++ 高级接口

6.1 获取运行时选项

#include "IWebNativeBrowserCore.h"

const FWebNativeBrowserRuntimeOptions& Options =
    IWebNativeBrowserCoreModule::Get().GetRuntimeOptions();

FWebNativeBrowserRuntimeOptions 字段对应 06-CEF 参数配置 的全部 ini 键（bClearCache ↔ clear_cache、bMultiOpen ↔ multi_open 等），运行期读取可判断当前生效配置。

6.2 创建浏览器视图（无 UMG 场景）

需要脱离 UMG、直接内嵌到自有 Slate 层级时：

FWebNativeBrowserViewArgs Args;
Args.InitialURL = TEXT("https://example.com");
Args.ViewSize = FIntPoint(1920, 1080);
Args.OnMessage.BindLambda([](const FString& FunctionName, const FString& MessageBody)
{
    UE_LOG(LogTemp, Log, TEXT("[WebNative] %s: %s"), *FunctionName, *MessageBody);
});

TSharedRef<IWebNativeBrowserView> View =
    IWebNativeBrowserCoreModule::Get().CreateBrowserView(Args);
TSharedRef<SWidget> SlateWidget = View->GetSlateWidget(); // 加入你的 Slate 层级

6.3 IWebNativeBrowserView 接口

方法 说明
GetSlateWidget() 获取浏览器 Slate 控件
LoadURL(FString) 加载 URL
GoBack() / GoForward() / Reload(bool) 导航控制
ExecuteJavaScript(FString) 执行 JS
SendMessageToJavaScript(FString, FString) 发送消息到网页
FlushMessagesToJS() 立即刷出队列消息
ShowDevTools() / CloseDevTools() / ToggleDevTools() DevTools 控制
CloseBrowser() 关闭浏览器
SetViewSize(FIntPoint) 设置视图尺寸
SetRenderOptions(bool, bool) 设置 GPU 渲染与 CPU 回退
SetAcceptsInput(bool) / SetAutoFocusOnMouseDown(bool) 输入控制
SetMouseTransparency(bool, int32, int32) 设置鼠标穿透（开关/阈值/块大小）
SetAutoResizeToWidget(bool) 自动缩放开关
SetMessageDispatchBudgetPerFrame(int32) 每帧消息派发预算
SetForwardUEKeyEvents(bool) 键盘事件转发开关
SetOnMessage / SetOnLoadStateChanged / SetOnUrlChanged / SetOnBeforePopup / SetOnLoadEnd 绑定各类委托

6.4 委托签名

委托 参数
FWebNativeBrowserNativeMessageDelegate (const FString& FunctionName, const FString& MessageBody)
FWebNativeBrowserLoadStateDelegate (bool bIsLoading, bool bCanGoBack, bool bCanGoForward)
FWebNativeBrowserUrlChangedDelegate (const FString& URL)
FWebNativeBrowserBeforePopupDelegate (const FString& TargetURL, const FString& TargetFrameName)
FWebNativeBrowserLoadEndDelegate (const FString& URL, int32 HttpStatusCode)

下一步

Clone this wiki locally