249 lines
10 KiB
Markdown
249 lines
10 KiB
Markdown
|
# UI 拼接工具
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
UI 拼接工具提供 JSON 配置与 Unity 预制体的双向转换，帮助 UI 相关人员通过 JSON 配置文件快速生成 UI 预制体，同时支持从现有预制体反向导出 JSON 用于版本控制或重新生成。
|
|||
|
|
|
|||
|
|
## 核心组件
|
|||
|
|
|
|||
|
|
| 组件 | 职责 | 文件路径 |
|
|||
|
|
|-----|------|---------|
|
|||
|
|
| **UIPrefabGenerator** | 解析 JSON 并生成 UI 预制体 | `Assets/Editor/Command/UIPrefabGenerator.cs` |
|
|||
|
|
| **UIPrefabToJson** | 从预制体反向导出 JSON | `Assets/Editor/Command/UIPrefabToJson.cs` |
|
|||
|
|
| **RemoteCommand** | 提供外部调用接口 | `Assets/Editor/Command/RemoteCommand.cs` |
|
|||
|
|
| **ExternalCommandListener** | 监听外部命令触发文件 | `Assets/Editor/Command/ExternalCommandListener.cs` |
|
|||
|
|
|
|||
|
|
工具脚本在文档库中的位置（已并入编辑器工具模块）：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
modules/frameworks/编辑器工具/UI工具/
|
|||
|
|
├── ExternalCommandListener.cs # 外部命令监听器
|
|||
|
|
├── RemoteCommand.cs # 远程命令接口
|
|||
|
|
├── UIPrefabGenerator.cs # JSON 转预制体生成器
|
|||
|
|
└── UIPrefabToJson.cs # 预制体转 JSON 导出器
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## JSON 配置文件结构
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"name": "BagWindow",
|
|||
|
|
"width": 1024,
|
|||
|
|
"height": 768,
|
|||
|
|
"elements": [
|
|||
|
|
{
|
|||
|
|
"type": "Image",
|
|||
|
|
"name": "BgPanel",
|
|||
|
|
"anchorMin": [0, 0],
|
|||
|
|
"anchorMax": [1, 1],
|
|||
|
|
"position": [0, 0, 0],
|
|||
|
|
"sizeDelta": [0, 0],
|
|||
|
|
"sprite": "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/Sprites/Bg.png"
|
|||
|
|
},
|
|||
|
|
{
|
|||
|
|
"type": "Text",
|
|||
|
|
"name": "TitleText",
|
|||
|
|
"anchorMin": [0.5, 0.9],
|
|||
|
|
"anchorMax": [0.5, 0.9],
|
|||
|
|
"position": [0, 0, 0],
|
|||
|
|
"sizeDelta": [200, 40],
|
|||
|
|
"text": "背包",
|
|||
|
|
"font": "Assets/Game/GameHFResource/CN/Fonts/FZY4K-M05S SDF.asset",
|
|||
|
|
"fontSize": 28,
|
|||
|
|
"color": [1, 1, 1, 1]
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 支持的 UI 元素类型
|
|||
|
|
|
|||
|
|
| 类型 | 对应 Unity 组件 | 关键属性 |
|
|||
|
|
|-----|-------------|---------|
|
|||
|
|
| **Image** | Image | sprite, color, type, preserveAspect |
|
|||
|
|
| **TextMeshProUGUI** | TextMeshProUGUI | text, font, fontSize, color, alignment |
|
|||
|
|
| **Button** | Button | interactable, transition, navigationMode |
|
|||
|
|
| **Slider** | Slider | minValue, maxValue, value, wholeNumbers, direction |
|
|||
|
|
| **Toggle** | Toggle | isOn, toggleTransition, transition |
|
|||
|
|
| **InputField** | InputField | text, placeholder, characterLimit, contentType |
|
|||
|
|
| **ScrollRect** | ScrollRect | horizontal, vertical, movementType |
|
|||
|
|
| **GridLayoutGroup** | GridLayoutGroup | cellSize, spacing, constraint, padding |
|
|||
|
|
| **VerticalLayoutGroup** | VerticalLayoutGroup | spacing, childAlignment, padding |
|
|||
|
|
| **HorizontalLayoutGroup** | HorizontalLayoutGroup | spacing, childAlignment, padding |
|
|||
|
|
|
|||
|
|
## 外部命令触发机制
|
|||
|
|
|
|||
|
|
### 触发方式
|
|||
|
|
|
|||
|
|
通过创建/修改 `Trigger_Command.txt` 文件触发 UI 生成：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
GenerateUIPrefab:Assets/Editor/UI/BagWindow.json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 命令格式
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
<命令名>:<参数1>:<参数2>:...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**支持的命令**：
|
|||
|
|
|
|||
|
|
| 命令 | 参数 | 说明 |
|
|||
|
|
|-----|------|------|
|
|||
|
|
| **GenerateUIPrefab** | `jsonPath` [, `prefabPath`] | 根据 JSON 生成 UI 预制体 |
|
|||
|
|
| **ExportPrefabToJson** | `prefabPath` [, `jsonPath`] | 从预制体反向导出 JSON |
|
|||
|
|
| **ReadJson** | [参数列表] | 读取 JSON 配置（测试用） |
|
|||
|
|
|
|||
|
|
### 完整执行流程
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 外部系统写入命令到 Trigger_Command.txt │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ ExternalCommandListener (FileSystemWatcher) 检测到文件变化 │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 解析命令格式：GenerateUIPrefab:Assets/Editor/UI/BagWindow.json │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 通过反射调用 RemoteCommand.GenerateUIPrefab(string[] args) │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ UIPrefabGenerator.GeneratePrefabFromJson(jsonPath, prefabPath) │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 生成预制体到指定路径：Assets/Game/GameHFResource/CN/UIWindows/... │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 使用示例
|
|||
|
|
|
|||
|
|
### 方式一：外部命令触发
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 正向：从 JSON 生成预制体
|
|||
|
|
echo "GenerateUIPrefab:Assets/Editor/UI/BagWindow.json" > "F:\JMNet\CrystalBattle_Client\Trigger_Command.txt"
|
|||
|
|
|
|||
|
|
# 反向：从预制体导出 JSON
|
|||
|
|
echo "ExportPrefabToJson:Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab" > "F:\JMNet\CrystalBattle_Client\Trigger_Command.txt"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 方式二：Unity 编辑器菜单
|
|||
|
|
|
|||
|
|
**正向生成**：
|
|||
|
|
1. 打开 Unity 编辑器
|
|||
|
|
2. 点击菜单 `Tools > External > Test GenerateUIPrefab`
|
|||
|
|
3. 查看 Console 窗口日志确认执行结果
|
|||
|
|
|
|||
|
|
**反向导出**：
|
|||
|
|
1. 打开 Unity 编辑器
|
|||
|
|
2. 点击菜单 `Tools > UI > Export Prefab to JSON`
|
|||
|
|
3. 选择要导出的预制体文件
|
|||
|
|
|
|||
|
|
### 方式三：代码调用
|
|||
|
|
|
|||
|
|
```csharp
|
|||
|
|
// 正向：从 JSON 生成预制体
|
|||
|
|
UIPrefabGenerator.GeneratePrefabFromJson(
|
|||
|
|
"Assets/Editor/UI/BagWindow.json",
|
|||
|
|
"Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab"
|
|||
|
|
);
|
|||
|
|
|
|||
|
|
// 反向：从预制体导出 JSON
|
|||
|
|
UIPrefabToJson.ExportPrefabToJson(
|
|||
|
|
"Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab",
|
|||
|
|
"Assets/Editor/UI/BagWindow.json"
|
|||
|
|
);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
1. **路径格式**：JSON 中的资源路径使用 `/` 分隔符，且为 Unity 项目相对路径
|
|||
|
|
2. **资源引用**：确保 JSON 中引用的 Sprite、Font 等资源已存在于项目中
|
|||
|
|
3. **编码格式**：JSON 文件使用 UTF-8 编码
|
|||
|
|
4. **坐标系统**：使用 Unity RectTransform 的 anchorMin/anchorMax/position/sizeDelta 四元组
|
|||
|
|
5. **文件锁定**：生成前确保目标预制体文件未被其他进程占用
|
|||
|
|
|
|||
|
|
## 部署步骤
|
|||
|
|
|
|||
|
|
### 方法一：手动复制
|
|||
|
|
|
|||
|
|
1. 复制 `modules/frameworks/编辑器工具/UI工具/` 目录下的所有文件
|
|||
|
|
2. 粘贴到目标项目的 `Assets/Editor/Command/` 目录中
|
|||
|
|
3. 确保目录结构如下：
|
|||
|
|
```
|
|||
|
|
Assets/Editor/Command/
|
|||
|
|
├── ExternalCommandListener.cs
|
|||
|
|
├── RemoteCommand.cs
|
|||
|
|
├── UIPrefabGenerator.cs
|
|||
|
|
└── UIPrefabToJson.cs
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 方法二：自动部署脚本
|
|||
|
|
|
|||
|
|
创建部署脚本 `DeployUITools.bat`：
|
|||
|
|
|
|||
|
|
```batch
|
|||
|
|
@echo off
|
|||
|
|
set "SOURCE_DIR=E:\AI\UnityAI\modules\frameworks\编辑器工具\UI工具"
|
|||
|
|
set "TARGET_DIR=%cd%\Assets\Editor\Command"
|
|||
|
|
|
|||
|
|
mkdir "%TARGET_DIR%" 2>nul
|
|||
|
|
xcopy "%SOURCE_DIR%\*.cs" "%TARGET_DIR%\" /y
|
|||
|
|
xcopy "%SOURCE_DIR%\*.cs.meta" "%TARGET_DIR%\" /y
|
|||
|
|
|
|||
|
|
echo UI 工具部署完成
|
|||
|
|
pause
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 部署检查项
|
|||
|
|
|
|||
|
|
| 检查项 | 要求 |
|
|||
|
|
|-------|------|
|
|||
|
|
| **目标路径** | 必须放置在 `Assets/Editor/Command/` 目录下 |
|
|||
|
|
| **文件完整性** | 必须包含所有 4 个 cs 文件及其 meta 文件 |
|
|||
|
|
| **Unity 版本** | 支持 Unity 2020 及以上版本 |
|
|||
|
|
| **依赖组件** | 需要导入 TextMeshPro 包 |
|
|||
|
|
|
|||
|
|
### 验证部署
|
|||
|
|
|
|||
|
|
部署完成后，在 Unity 编辑器中验证：
|
|||
|
|
|
|||
|
|
1. 打开 Unity 编辑器
|
|||
|
|
2. 检查菜单 `Tools > UI` 是否存在
|
|||
|
|
3. 检查菜单 `Tools > External` 是否存在
|
|||
|
|
4. 在 Console 窗口确认无编译错误
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**版本**: v1.2
|
|||
|
|
**适用**: StrayFog 框架 UI 拼接开发人员
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 文档关联
|
|||
|
|
|
|||
|
|
> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
|
|||
|
|
|
|||
|
|
| 文档 | 关联原因 |
|
|||
|
|
|---|---|
|
|||
|
|
| [编辑器工具入口](README.md) | 本文件是编辑器工具模块的子文档 |
|
|||
|
|
| [UI 窗口系统](../UI窗口系统/README.md) | UI 拼接工具服务于 UI 窗口系统 |
|
|||
|
|
| [UI 界面拼接设计指南](../UI窗口系统/界面拼接.md) | 设计指南说明 JSON 驱动的界面拼接原则 |
|
|||
|
|
| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
|
|||
|
|
| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义编辑器工具层与运行时层边界 |
|
|||
|
|
| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 编辑器工具开发规则互相引用 |
|
|||
|
|
| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
|