#常见问题

#如何加载开发模式的QuickUI？

在 UE5 开发环境中，使用LoadURL加载http://localhost:3000，即可加载开发模式的QuickUI。

在开发工具激活后，使用快捷键 Ctrl + Shift + I 打开浏览器控制台，即可查看 QuickUI 控制台输出信息。

#连接与通信

#isConnected 始终为 false

问题： 在 Web 端使用 useUEContext() 获取的 isConnected 始终显示"未连接"。

原因： Web 端未运行在 UE5 的 Web 浏览器控件中，UE5 引擎未注入 ue 通信对象。

解决方案：

• 确保 HTML 文件已通过 UE5 的 QuickUI 插件 Web 浏览器控件加载，而非直接在桌面浏览器中双击打开
• 在 UE5 编辑器中运行游戏（Play），Web UI 会自动建立连接
• 开发时可在QuickUI的DevTools控制台输入 window.ue 检查 UE 通信对象是否存在

#事件发送无响应，ue.uecommand.emitjsonevent is not a function

问题： 调用 useQuickUIEventSender 返回的发送函数后，UE5 端未收到事件，控制台报错 emitjsonevent is not a function。

原因： UE5 引擎中的 QuickUI 插件版本过低，或 uecommand 对象不完整。

解决方案：

• 确认 UE5 项目中已安装并启用了最新版 QuickUI 插件
• 检查 UE5 蓝图中的事件名称与前端 useQuickUIEventSender('eventName') 传入的名称保持一致
• 该 hooks 内部有自动降级机制，当 emitjsonevent 不可用时会回退到 executejs 方式发送

#useQuickUIEventListener 注册的回调从未触发

问题： 使用 useQuickUIEventListener 监听事件，但回调函数从未执行。

原因： ue-connect 需要在根组件中先调用一次 useQuickUIEventListener 来建立事件监听通道。

解决方案：

// 必须有一个顶层组件先调用 useQuickUIEventListener
function App() {
  // 在根组件中先调用一次，事件名称任意
  useQuickUIEventListener('UEcallback', (event) => {})

  return (
    <UEProvider>
      <YourComponent />
    </UEProvider>
  )
}

更推荐的做法： 直接使用 UEProvider，其内部已集成了事件监听初始化。

#鼠标与输入

#Web UI 的点击事件穿透到了 UE5 场景

问题： 点击 Web UI 上的按钮或元素时，鼠标事件穿透到了 UE5 游戏场景，导致 UE5 角色或相机产生响应。

原因： 未在 Web UI 元素上添加 data-nohit 属性。

解决方案： 在需要阻止鼠标事件穿透的容器或元素上添加 data-nohit 属性：

<div data-nohit className="ui-panel">
  {/* 此区域内的鼠标事件不会穿透到 UE5 */}
  <button onClick={handleClick}>点击</button>
</div>

useUEMouse 会自动检测带有 data-nohit 的元素，鼠标悬停在该区域时自动禁用向 UE5 转发鼠标事件。

#右键菜单在 Web UI 中弹出

问题： 在 Web UI 上右键点击时，浏览器默认的右键菜单弹出。

解决方案： 使用 useInputBlocker 禁用右键菜单：

import { useInputBlocker } from 'ue-connect'

function App() {
  useInputBlocker({ disableContextMenu: true, disableTabKey: true })
  // ...
}

#Tab 键导致焦点跳转

问题： 按下 Tab 键导致浏览器焦点在元素间跳转，干扰 UE5 操作。

解决方案： 在 useInputBlocker 中同时禁用 Tab 键：

useInputBlocker({ disableContextMenu: true, disableTabKey: true })

#构建与部署

#UE5 中图片不显示

原因： UE5 的 Web 浏览器控件无法加载外部资源文件，所有图片必须嵌入到 HTML 中。

解决方案：

• 使用 convertImageToBase64 工具将图片转为 Base64
• 在代码中导入 Base64 文本文件使用

import logoBase64 from '@/assets/img/QuickUI-A-base64.txt'

function Logo() {
  return <img src={logoBase64} alt="logo" />
}

#构建后 UE5 加载 HTML 样式错乱或脚本不执行

问题： 使用 rspack build 构建后，在 UE5 中加载 HTML 文件出现样式丢失或脚本错误。

原因： Rspack 构建产物中引用了外部的 JS 和 CSS 文件，UE5 无法加载这些外链资源。

解决方案： 构建完成后使用 merge-html 工具将所有资源内联为单个 HTML 文件：

npm run build
npm run merge-html

#@ 别名在 TypeScript 中报错

问题： import App from '@/pages/template/App' 报模块找不到的错误。

原因： TypeScript 配置中未识别 @ 路径别名。

解决方案： 检查 tsconfig.json 中是否正确配置了 paths：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

#UE5 集成

#autofit.js 自适应缩放不生效

问题： 在 UE5 中 Web UI 显示大小不正确，未按设计分辨率缩放。

原因： autofit.js 初始化需要传入 Fit={true} 参数来激活。

解决方案：

// 在 App 组件中传入 Fit 参数
<App Fit={true} />

// 或在根组件中直接初始化
useEffect(() => {
  autofit.init({
    dw: 1920,     // 设计宽度
    dh: 1080,     // 设计高度
    el: 'body',
    resize: true,
    transition: 0.25,
    limit: 0.3    // 缩放限制
  })
}, [])

#UE5 端收不到 QuickUI 自定义事件

问题： 前端调用 useQuickUIEventSender 发送事件，但 UE5 蓝图/UMG 中未收到。

原因： 事件名称不匹配。

解决方案：

• 前端事件名称对应 UE5 后端的 QuickUIListenEvent 节点
• 监听的事件名称对应 UE5 后端的 QuickUIEventCallBack 节点
• 保持前后端事件名称完全一致（区分大小写）

// 前端发送
const sendEvent = useQuickUIEventSender('playerUpdate')
sendEvent({ health: 100, ammo: 30 })

// UE5 端使用 "playerUpdate" 作为 QuickUIListenEvent 的事件名称接收

// 前端监听
useQuickUIEventListener('gameStateChange', (event) => {
  console.log('收到事件:', event)
})

// UE5 端使用 "gameStateChange" 作为 QuickUIEventCallBack 的事件名称发送