04 高级交互

本章介绍 WebNativeBrowser 的高级交互能力：从 Web 拖拽/点击放置到 UE 场景，以及鼠标穿透、DevTools 调试等进阶用法。

---

1. 应用场景

把 Web 页面变成资产库、道具栏、建筑目录、设备列表或运行时编辑工具，并把用户的选择自然衔接到 UE 游戏视口：

• 游戏道具放置、关卡搭建、家具布置
• 数字孪生设备部署、交互展陈
• 建筑目录拖放、园区资产摆放

插件职责与项目职责的边界：

层级	职责
WebNativeBrowser	跨 Web/UE 的消息、焦点与光标空间基础能力
项目蓝图/C++	创建哪个 Actor、是否允许放置、放置位置、联网同步

---

2. 点击放置流程

1. 用户点击 Web 资源条目。
2. 页面发送资源 ID 和"开始放置"命令。
3. UE 校验资源 ID，进入放置状态。
4. 调用 SetFocusToGameViewport()，让后续鼠标输入进入 UE 场景。
5. 获取光标坐标并反投影到世界空间。
6. 项目进行射线检测并显示预览体。
7. 用户点击确认，项目在 UE 游戏线程创建 Actor。

WebNative.send("DragModel", {
  modelId: "cube",
  modelName: "Cube",
  modelPath: "/Engine/BasicShapes/Cube.Cube",
  action: "drag_start"
});

以上消息体取自示例页面 3_digitaltwin.html（Content/webnative/html/）的模型点击通知，字段含义见第 5 节；业务名称可按项目消息规范修改。

---

3. 拖拽放置流程

1. Web 的 dragstart 记录当前资源，并通知 UE 准备放置。
2. 在跨入场景前切换到 UE 游戏视口焦点。
3. UE 使用平台光标和世界空间反投影持续更新预览位置。
4. 用户释放鼠标后，项目确认放置；取消时销毁预览体并恢复普通交互状态。

拖拽期间只更新一个预览对象，不要随鼠标移动重复创建 Actor；高频移动状态也不需要逐条修改 Web DOM。

---

4. 公开接口

接口	用途
WebNative.send(functionName, messageBody)	Web 向 UE 发送选中资源和业务命令
SetFocusToGameViewport()	将输入焦点从页面切换到 UE 游戏视口
GetRawPlatformCursorPos(OutScreenPos)	Tick更新平台光标的屏幕坐标
DeprojectCursorToWorld(ScreenPos, OutWorldPos, OutWorldDir)	Tick将屏幕坐标转换为世界空间射线

这些接口均可用于蓝图工作流；C++ 项目也可以调用对应公开函数（见 03-WebNativeWidget 参数配置 第 7 节）。

---

5. 推荐消息数据

{
  "modelId": "cube",
  "modelName": "Cube",
  "modelPath": "/Engine/BasicShapes/Cube.Cube",
  "action": "drag_start"
}

• modelId / modelName：稳定的业务标识与展示名称，来自页面元素的 data-model-id / data-model-name。
• modelPath：UE 资产路径（data-model-path）。项目侧必须把允许的 modelPath 映射到受控资源，不要让网页传入任意本地文件路径或任意 UE 对象路径。
• action：动作标记（drag_start 表示点击/拖拽开始），可按需扩展 drag_confirm、drag_cancel 等。

---

6. 项目侧必须处理

• 将允许的 modelId / modelPath 映射到受控的 UClass、Static Mesh 或业务对象。
• 在 UE 游戏线程执行 UObject/Actor 创建和销毁。
• 处理射线检测、可放置表面、碰撞、吸附、旋转与范围限制。
• 在控件销毁、关卡切换和应用退出时取消未完成的放置状态。

---

7. 鼠标穿透与透明交互

当页面存在透明区域时，可配合 Widget 的鼠标穿透参数实现"网页与 UE 场景共存"的交互：

• bEnableMouseTransparency = true：开启 alpha 命中测试。
• MouseTransparencyAlphaThreshold：低于该 alpha 值的像素视为透明，鼠标点击穿透到 UE。
• 典型场景：半透明 HUD 面板，面板空白处点击可直接操作场景中的对象。

参数完整说明见 03-WebNativeWidget 参数配置 第 4 节。

---

8. DevTools 调试

开发阶段我们想像浏览器一样F12进行调试工作，增加断点可以通过网页任意区域进行ctrl+F12快捷键打开调试窗口，启动当前机器默认浏览器进行调试工作

9. 参考资源

资源	用途
Plugins/WebNativeBrowser/Content/webnative/html/3_digitaltwin.html	数字孪生前端案例：模型点击/拖拽通知、data-model-id / data-model-path 属性规范、属性面板、设备树实现
Plugins/WebNativeBrowser/Content/webnative/Blueprints/BP_DemoScene	蓝图示例：解析 DragModel 消息、SetFocusToGameViewport 切换焦点、DeprojectCursorToWorld 反投影、Tick 更新预览 Actor

---

下一步

• 完整参数与接口：03-WebNativeWidget 参数配置
• 消息协议设计：02-双向通讯
• 典型业务场景架构：05-案例介绍