#QuickUIDesign

#关于 QuickUIDesign 模板

QuickUIDesign 是一个基于 React 的 UE5（Unreal Engine 5）UI 开发模板。它提供了一套完整的工具链，使开发者能够使用现代前端技术创建高性能、交互性强的 UE5 界面。

#模板结构

模板源码位于 src/ 目录下，组织结构如下：

src/
├── assets/                    # 静态资源文件
│   └── img/
│       ├── QuickUI-A.svg      # QuickUI 标志 SVG
│       ├── QuickUI-A-base64.txt
│       ├── lufei.png           # 示例图片
│       └── lufei-base64.txt
├── components/                # React 组件
│   └── UEConnect-Demo/
│       └── index.tsx          # UE5 连接演示组件
├── lib/
│   └── utils.ts               # 工具函数（cn 辅助方法）
├── pages/
│   └── template/
│       ├── index.tsx           # 应用入口
│       └── App.tsx             # 根组件
├── styles/
│   └── index.css               # Tailwind CSS 指令
└── types/
    └── @type.d.ts              # TypeScript 类型声明

#核心文件说明

#入口文件：src/pages/template/index.tsx

应用的入口文件，负责挂载根组件：

import App from './App'
import { createRoot } from 'react-dom/client'

const container = document.getElementById('root')
const root = createRoot(container)
root.render(
  <>
    <App />
  </>
)

#根组件：src/pages/template/App.tsx

主应用组件，负责建立 UE5 连接上下文和自适应布局配置：

import { useEffect } from 'react'
import { useQuickUIEventListener } from 'ue-connect'
import autofit from 'autofit.js'
import '@/styles/index.css'
import { UEProvider } from 'ue-connect'
import UEConnectDemo from '@/components/UEConnect-Demo'

export default function App({ Fit = false }: { Fit?: boolean }) {
  useQuickUIEventListener('UEcallback', (event) => {})

  useEffect(() => {
    if (Fit)
      autofit.init({
        dw: 1920,
        dh: 1080,
        el: 'body',
        resize: true,
        transition: 0.25,
        limit: 0.3
      })
  }, [])

  return (
    <UEProvider>
      <div className="flex flex-col items-center justify-center w-screen h-screen select-none overflow-hidden">
        <UEConnectDemo />
      </div>
    </UEProvider>
  )
}

关键特性：

• UEProvider：为所有子组件提供全局的 UE5 连接上下文
• useQuickUIEventListener：需在根组件中调用一次，以启用子组件中的事件监听
• autofit.js（可选）：自适应缩放工具，确保在不同分辨率下 UI 布局一致。传参 Fit={true} 激活

#演示组件：src/components/UEConnect-Demo/index.tsx

一个完整的参考组件，展示了 ue-connect 的核心 API 用法：

• useInputBlocker：禁用右键菜单和 Tab 键
• useUEContext：获取 UE5 连接状态、设备类型、鼠标状态和最近按键操作
• useQuickUIEventSender：向 UE5 发送自定义事件
• useQuickUIEventListener：监听来自 UE5 的事件
• data-nohit 属性：标记元素为鼠标事件不可穿透，确保 Web UI 与 UE5 之间的事件正确路由

#样式：src/styles/index.css

Tailwind CSS 入口文件，包含三个核心指令：

@tailwind base;
@tailwind components;
@tailwind utilities;

#工具函数：src/lib/utils.ts

cn() 辅助函数，结合 clsx 和 tailwind-merge 实现条件式类名合并：

import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

#类型声明：src/types/@type.d.ts

项目中静态资源导入的模块声明：

declare module '*.svg'
declare module '*.png'
declare module '*.jpg'
declare module '*.jpeg'
declare module '*.gif'
declare module '*.bmp'
declare module '*.tiff'
declare module '*.scss'
declare module '*.json'
declare module '*.txt' {
  const content: string
  export default content
}

#ue-connect 模块

ue-connect 是项目的核心 UE5 连接器模块，位于 ue-connect/ 目录下。它提供了一套完整的 hooks 和上下文管理工具，用于建立 React 与 UE5 之间的双向通信。 详细文档请访问 ue-connect 文档

#assets-tool 工具集

assets-tool/ 目录包含两个构建辅助工具，用于优化 UE5 集成的最终产物体积和性能。

#工具结构

assets-tool/
├── convertImageToBase64.js   # 图片转 Base64 工具
└── merge-html.js             # HTML 内联合并工具

#convertImageToBase64

将图片（PNG/JPG）或 WebAssembly（WASM）文件转换为 Base64 编码的文本文件，便于在 UE5 中直接嵌入资源。

使用方式：

# 转换单个文件
node assets-tool/convertImageToBase64.js ./src/assets/img/lufei.png

# 批量转换目录下所有图片
node assets-tool/convertImageToBase64.js ./src/assets/img/

对应的 npm script：

"base64img": "node assets-tool/convertImageToBase64.js ./src/assets/img/"

工作原理：

• 读取图片/WASM 文件的二进制数据
• 转换为 Base64 字符串，添加 data:image/png;base64, 或 data:application/wasm;base64, 前缀
• 在同目录下生成 文件名-base64.txt 文件
• 支持的格式：.png、.jpg、.wasm

#merge-html

HTML 内联合并工具，将构建产物中引用的外部 JS、CSS、图片和字体文件全部内联到 HTML 文件中，生成一个完全自包含的 HTML 文件，适合在 UE5 的 Web 浏览器控件中加载。

使用方式：

node assets-tool/merge-html.js

对应的 npm script：

"merge-html": "node assets-tool/merge-html.js"

支持的合并类型：

使用场景：

• rspack build 构建后，生成的外链资源 HTML 文件通过此工具合并
• 合并得到单个自包含 HTML，可直接在 UE5 中加载，无需额外资源文件

#项目构建配置

#rspack.config.js

项目使用 Rspack（基于 Rust 的高性能 Web 构建工具）作为核心打包器，配置文件位于项目根目录。

入口配置：

// 指定应用入口文件
entry: {
  index: './src/pages/template/index.tsx',
}

src/pages/template/index.tsx 为模板应用的唯一入口，所有组件和依赖从此文件开始构建。

模块解析与别名：

resolve: {
  extensions: ['.js', '.jsx', '.ts', '.tsx'],  // 自动解析的扩展名
  alias: {
    '@': path.resolve(__dirname, './src'),               // @ 指向 src/
    'ue-connect': path.resolve(__dirname, './ue-connect') // ue-connect 模块路径
  }
}

• @ 别名简化源码导入路径，如 import App from '@/pages/template/App'
• ue-connect 别名确保模块引用指向本地 ue-connect/ 目录

代码压缩：

optimization: {
  minimizer: [
    new rspack.SwcJsMinimizerRspackPlugin({     // JS 压缩（移除注释）
      minimizerOptions: { format: { comments: false } }
    }),
    new rspack.LightningCssMinimizerRspackPlugin({  // CSS 压缩
      minimizerOptions: { errorRecovery: false }
    })
  ]
}

使用 SWC（Speedy Web Compiler）和 Lightning CSS 进行高性能的 JS/CSS 压缩。

开发服务器：

devServer: {
  open: true,                    // 自动打开浏览器
  static: { directory: path.join(__dirname, 'dist') },
  hot: true,                     // 热模块替换
  historyApiFallback: true,      // SPA 路由支持
  port: 3000                     // 开发端口
}

#文档图片资源

文档站中的图片资源统一存放于 pages/public/images/ 目录（即 root 目录下的 public/images/），可通过以下方式引用：

#目录结构

pages/                       # Rspress root 目录
├── public/
│   └── images/              # 图片资源目录
│       ├── QuickUI-A.svg    # QuickUI 品牌 Logo（已在站点导航栏中使用）
│       └── dev.png          # 示例图片
├── zh/faq/index.mdx         # 常见问题页面
├── rspress.config.ts        # 文档站配置
└── styles/
    └── theme.css            # 主题样式

#引用方式

方式一：绝对路径（通过 public/ 目录）

图片放在 pages/public/images/ 下，在 MDX 中使用 /images/文件名 引用：

![QuickUI Logo](/images/QuickUI-A.svg)

<img src="/images/QuickUI-A.svg" width="64" alt="QuickUI Logo" />

方式二：相对路径（同目录放置）

图片放在 MDX 文件同级目录下，使用相对路径引用：

![示例图片](./demo.png)

#使用场景

#使用模板

#开发

启动开发服务器：

npm run dev

将启动一个带有热模块替换的本地开发服务器，支持快速迭代开发。

#构建

构建生产版本：

npm run build
npm run merge-html

构建产物将输出到 dist/merged/ 目录，所有资源已内联为单个 HTML 文件，可直接在 UE5 中使用。

#UE5 集成

构建完成后，生成的 HTML 文件可通过 QuickUI 插件的网页浏览器控件加载到 UE5 中，实现 React 与 UE5 之间的无缝双向通信。