QuickUIDesign

关于 QuickUIDesign 模板

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

版本更新记录

v1.0.0 初始版本发布，包含核心模板结构、UE5 连接演示、资源工具链和 Rspack 构建配置。
v1.1.0 新增媒体资源打包支持，支持将图片、音频、视频等媒体资源打包到 HTML 文件中。

模板结构

模板源码位于 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 类型声明
│
└──public/
    ├── audios/
    │   └── light-on.mp3           # 示例音频资源（非内联引用）
    └── img/
    │   └── lufei.png              # 示例图片资源（非内联引用）
    └── index.html                 # HTML 模板

核心文件说明

入口文件：`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）转换为 Base64 编码的文本文件，便于在 UE5 中直接嵌入资源。

具体参考 src/pages/template/App.tsx中的使用示例
⚠ 注意：QuickUI支持2中图片资源加载，内联和非内联。推荐小图片资源使用 Base64 编码内联到 HTML 文件中。
若是非内联资源，在UE5打包时需要额外打包图片资源，具体参考加载构建后的 HTML
使用方式：

# 转换单个文件
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、.jpeg、

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/ 目录

开发服务器：

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

使用模板

开发

启动开发服务器：

npm run dev

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

构建

构建生产版本：

npm run build
npm run merge-html

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

UE5 集成

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

#QuickUIDesign

#关于 QuickUIDesign 模板

#版本更新记录

#模板结构

#核心文件说明

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

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

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

#样式：src/styles/index.css

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

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

#ue-connect 模块

#assets-tool 工具集

#工具结构

#convertImageToBase64

#merge-html

#项目构建配置

#rspack.config.js

#使用模板

#开发

#构建

#UE5 集成