lms
ee1ff7f444
- 删除 01~05 旧中文教程目录 - 将 03 核心功能教程拆分为各 framework 模块的子文档 - 06 工具脚本移入 modules/frameworks/编辑器工具/UI工具/ - 非框架内容合并进 rules/20-开发规则.md 与 rules/40-工作流清单.md - 更新所有交叉链接与文档关联表 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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) | 模块登记规则定义分类和状态口径 |
|