#快速开始

本指南将带你了解 QuickUI UE5 插件 与 QuickUIDesign 模板的完整配合使用流程，助你快速上手基于 React 构建交互式 UE5 界面。

#工作流程概览

UE5 编辑器 (QuickUI 插件)
        │
        ├── 1. 安装 QuickUI 插件 → 在 UE5 项目中启用
        │
        ├── 2. 从 GitHub 克隆 QuickUIDesign → npm install
        │
        ├── 3. 开发调试: npm run dev → UE5 中加载 http://localhost:3000
        │
        ├── 4. 构建部署: npm run build → npm run merge-html
        │
        └── 5. 上线: UE5 Web 浏览器控件加载合并后的 HTML

#第一步：在 UE5 中安装 QuickUI 插件

#下载插件

从QuickUI Plugin on Fab.com下载对应 UE5 版本的 QuickUI 插件包。

#安装到 UE5 项目

商城下载插件，这会自动将插件文件夹复制到 UE5 项目的 Plugins/ 目录下。

如果你需要在其他插件目录下安装 QuickUI 插件，需要将 QuickUI 插件文件夹复制到 UE5 项目的 Plugins/ 目录下：

YourProject/
├── Plugins/
│   └── QuickUI/          # QuickUI 插件文件
├── Content/
├── Source/
└── YourProject.uproject

#启用插件

1. 打开 UE5 项目
2. 进入 编辑 → 插件 (Edit → Plugins)
3. 搜索 "QuickUI"
4. 勾选 已启用 (Enabled) 复选框
5. 按提示重启 UE5 编辑器

#添加 QuickUI 控件

在UMG蓝图中，你应该能看到 QuickUI 控件，将其添加到UMG中，并确使用Canvas组件挂载，将其铺满UMG区域：

#蓝图配置

一个完整的QuickUI蓝图配置流程大概如下图：

在UMG蓝图中，配置 QuickUI 主要有三步骤：

#加载QuickUI文件：

• 若是开发模式则是加载开发URL地址，
• 若是生产模式则是加载生产Html地址。

#UE5接收自定义事件的注册与绑定：

• 自定义事件注册与绑定, Event Name则是事件名称(需要与React组件中的事件名称一致)。
  下图是一个完整绑定流程（注册->绑定->回调）

图中注册的Event1事件，如果与React组件中的Event1一致。那么UE5作为后端,将接收到React组件中的事件参数。

#鼠标事件注册与绑定，如 MouseDown、MouseUp、MouseWheel。

注意：MouseDown、MouseUp、MouseWheel事件分别独立，需要分别注册与绑定。

#回调函数配置

• 使用 Callback 组件配置事件回调函数，将UE5处理的结果返回给QuickUI。
• Payload 是事件触发时传递的参数，Json字符串。
• Fn Name 是事件触发时执行的函数，用于处理事件逻辑，需要与React组件中的事件名称一致。 下图是一个完整的回调函数蓝图流程（事件触发->回调函数执行）：

注意：Payload 必须是Json字符串格式传递，否则QuickUI前端解析报错。

具体效果请参考百度云盘 Demo 工程项目

详细文档介绍请参考路由系统 - QuickUIDesign 文档

#第二步：搭建 QuickUIDesign 项目

#安装 Node.js 运行环境

QuickUIDesign 基于 Node.js 生态构建，需要先安装 Node.js 运行时（内置 npm 包管理器）。

#下载安装 Node.js 运行环境

1. 访问 Node.js 官网，推荐下载 LTS（长期支持） 版本（18+ 或更高）
2. 根据你的操作系统选择对应的安装包（Windows 选 .msi，macOS 选 .pkg）
3. 运行安装程序，一路按默认设置安装即可

Windows 用户安装完成后，建议重启一次系统，确保 Node.js 和 npm 已正确注册到系统环境变量 PATH 中。

#验证安装 Node.js 运行环境

打开终端（Windows 按 Win + R → 输入 cmd → 回车），执行以下命令确认安装成功：

# 查看 Node.js 版本（需 ≥ 18）
node -v

# 查看 npm 版本（需 ≥ 9）
npm -v

预期输出示例：

v18.20.4
10.8.1

版本号只需 ≥ 上述要求即可，具体小版本号可能不同。

#国内用户（可选）：配置 npm 镜像源

如果你位于中国大陆，建议配置淘宝镜像源以获得更快的下载速度：

# 配置为淘宝镜像源
npm config set registry https://registry.npmmirror.com

# 验证是否生效
npm config get registry

#更新 npm（如有需要）

如果 Node.js 安装后 npm 版本低于 9，可以手动更新：

npm install -g npm@latest

#从 GitHub 克隆项目

#方法1：从 GitHub 克隆 QuickUIDesign 仓库到本地机器：

打开终端，执行以下命令克隆 QuickUIDesign 项目：

# 克隆项目
git clone https://github.com/playertk/QuickUIDesign.git my-ui-project

# 进入项目目录
cd my-ui-project

# 安装依赖
npm install

如果你没有安装 Git，请先访问 Git 官网 下载安装。

#方法2：从 GitHub 下载 QuickUIDesign 项目：

QuickUIDesign Zip

解压 master.zip 文件

# 进入解压后的目录
cd master
#安装依赖：
npm install

#项目结构

安装完成后，项目目录结构如下：

my-ui-project/
├── src/
│   ├── assets/           # 静态资源（图片等）
│   ├── components/       # React 组件
│   ├── lib/              # 工具函数
│   ├── pages/            # 页面组件
│   ├── styles/           # CSS/Tailwind 样式
│   └── types/            # TypeScript 类型声明
├── ue-connect/           # UE5 连接器模块
├── assets-tool/          # 构建辅助工具
├── package.json
├── rspack.config.js      # Rspack 打包配置
└── tsconfig.json

#第三步：开发调试流程

#启动开发服务器

npm run dev

这会启动一个带有热模块替换（HMR）的开发服务器，地址为 http://localhost:3000。

#在 UE5 中加载

1. 打开已启用 QuickUI 插件的 UE5 项目
2. 创建或打开一个关卡蓝图（或控件蓝图）
3. 使用 LoadURL 节点加载 http://localhost:3000
4. 运行游戏（Play）

#使用 DevTools 调试

游戏运行中：

1. 按 Ctrl + Shift + I 打开浏览器 DevTools 控制台
2. 在控制台中输入 window.ue 验证 UE5 通信对象是否存在
3. 查看连接状态和事件日志

#热更新

修改源代码后，无需重启 UE5 游戏，修改会自动同步到 UE5 界面中——这得益于 Rspack 的 HMR（热模块替换）能力。

#第四步：构建生产版本

UI 开发完成后，构建为优化后的单个 HTML 文件：

# 第一步：使用 Rspack 构建
npm run build

# 第二步：将所有资源合并为单个 HTML
npm run merge-html

构建产物位于 dist/merged/index.html —— 一个完全自包含的 HTML 文件，所有 JS、CSS 和图片都已内联。

#构建产物说明

#第五步：在 UE5 中部署最终版本

#加载构建后的 HTML

1. 在 UE5 项目中使用 QuickUI Web 浏览器控件
2. 指向构建产物 dist/merged/index.html
3. 将构建产物拷贝到 UE5 项目的 Content/html/ 目录下（这里为示意，实际项目中根据需要调整）
4. 在UE5菜单栏中， 在Edit → ProjectSettings → Packaging → Advanced → Additional Non-Asset Directories to Package 中添加 Content/html/（红框）
5. 在 Additional Non-Asset Directories to Copy 中添加 Content/html/{Your-MediaFolder}/，非内联资源需要额外拷贝（黄框）

#完整通信架构

┌─────────────────────┐          ┌──────────────────────┐
│   Web UI (React)    │          │   UE5 (蓝图)         │
│                     │          │                      │
│  useQuickUIEvent    │ ──────►  │  QuickUIListenEvent  │
│  Sender('事件名')    │  发送    │                      │
│                     │          │                      │
│  useQuickUIEvent    │ ◄────── │  QuickUIEventCallBack │
│  Listener('事件名')  │  监听    │                      │
│                     │          │                      │
│  useUEContext()     │ ◄────── │  连接状态             │
│  (isConnected...)   │          │                      │
└─────────────────────┘          └──────────────────────┘

#视频教程

• QuickUI 的AI设计工作流介绍-B站

#相关下载

• GitHub - QuickUIDesign
• QuickUI Plugin - Fab.com
• 百度云盘-Demo Project

#继续了解

• QuickUIDesign — 详细的模板结构和自定义配置
• UE-Connect — UE5 通信 Hook 的完整 API 参考
• 常见问题 — 常见问题及解决方案