# 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) | 模块登记规则定义分类和状态口径 |