docs: 添加JSON配置驱动的UI生成方式文档

2026-05-25 18:24:10 +08:00
parent 93b718b230
commit 6e0f518580
1 changed files with 158 additions and 1 deletions
--- a/03_核心功能/UI/UI界面拼接设计指南.md
+++ b/03_核心功能/UI/UI界面拼接设计指南.md
@@ -163,5 +163,162 @@ Window

 ---

-**版本**: v1.0  
+## 八、JSON配置驱动的UI生成方式
+
+### 8.1 概述
+
+本项目支持通过JSON配置文件自动生成Unity UI预制体，实现UI界面的快速构建和迭代。
+
+### 8.2 核心组件
+
+| 组件 | 职责 | 文件路径 |
+|-----|------|---------|
+| **UIPrefabGenerator** | 解析JSON并生成UI预制体 | `Assets/Editor/Command/UIPrefabGenerator.cs` |
+| **RemoteCommand** | 提供外部调用接口 | `Assets/Editor/Command/RemoteCommand.cs` |
+| **ExternalCommandListener** | 监听外部命令触发文件 | `Assets/Editor/Command/ExternalCommandListener.cs` |
+
+### 8.3 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]
+    }
+  ]
+}
+```
+
+### 8.4 支持的UI元素类型
+
+| 类型 | 对应Unity组件 | 关键属性 |
+|-----|-------------|---------|
+| **Image** | Image | sprite, color, type (Simple/Sliced/Tiled/Filled) |
+| **Text** | TextMeshProUGUI | text, font, fontSize, color |
+| **Button** | Button | onClick, targetGraphic, transition |
+| **Slider** | Slider | minValue, maxValue, value, fillRect |
+| **Toggle** | Toggle | isOn, targetGraphic |
+
+### 8.5 外部命令触发机制
+
+#### 8.5.1 触发方式
+
+通过创建/修改 `Trigger_Command.txt` 文件触发UI生成：
+
+```
+GenerateUIPrefab:Assets/Editor/UI/BagWindow.json
+```
+
+#### 8.5.2 命令格式
+
+```
+<命令名>:<参数1>:<参数2>:...
+```
+
+**支持的命令**：
+
+| 命令 | 参数 | 说明 |
+|-----|------|------|
+| **GenerateUIPrefab** | `jsonPath` [, `prefabPath`] | 根据JSON生成UI预制体 |
+| **ReadJson** | [参数列表] | 读取JSON配置（测试用） |
+
+#### 8.5.3 完整执行流程
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  外部系统写入命令到 Trigger_Command.txt                             │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  ExternalCommandListener (FileSystemWatcher) 检测到文件变化         │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  解析命令格式：GenerateUIPrefab:Assets/Editor/UI/BagWindow.json     │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  通过反射调用 RemoteCommand.GenerateUIPrefab(string[] args)         │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  UIPrefabGenerator.GeneratePrefabFromJson(jsonPath, prefabPath)    │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  生成预制体到指定路径：Assets/Game/GameHFResource/CN/UIWindows/...  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 8.6 Unity编辑器菜单测试
+
+在Unity编辑器中提供了测试菜单：
+
+| 菜单路径 | 功能 |
+|---------|------|
+| `Tools > External > Test ReadJson` | 测试ReadJson命令 |
+| `Tools > External > Test GenerateUIPrefab` | 测试GenerateUIPrefab命令 |
+
+### 8.7 使用示例
+
+#### 方式一：外部命令触发
+
+```bash
+# 创建触发文件
+echo "GenerateUIPrefab:Assets/Editor/UI/BagWindow.json" > "F:\JMNet\CrystalBattle_Client\Trigger_Command.txt"
+```
+
+#### 方式二：Unity编辑器菜单
+
+1. 打开Unity编辑器
+2. 点击菜单 `Tools > External > Test GenerateUIPrefab`
+3. 查看Console窗口日志确认执行结果
+
+#### 方式三：代码调用
+
+```csharp
+// 直接调用生成方法
+UIPrefabGenerator.GeneratePrefabFromJson(
+    "Assets/Editor/UI/BagWindow.json",
+    "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab"
+);
+```
+
+### 8.8 注意事项
+
+1. **路径格式**：JSON中的资源路径使用 `/` 分隔符，且为Unity项目相对路径
+2. **资源引用**：确保JSON中引用的Sprite、Font等资源已存在于项目中
+3. **编码格式**：JSON文件使用UTF-8编码
+4. **坐标系统**：使用Unity RectTransform的anchorMin/anchorMax/position/sizeDelta四元组
+5. **文件锁定**：生成前确保目标预制体文件未被其他进程占用
+
+---
+
+**版本**: v1.1  
 **适用**: StrayFog框架UI拼接开发人员