[docs][refactor]: 将旧 01~06 中文教程合并整理为 modules/frameworks 文件夹结构

- 删除 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>
2026-07-07 18:36:15 +08:00
parent 5e5b9f8c80
commit ee1ff7f444
77 changed files with 6263 additions and 1133 deletions
--- a/modules/frameworks/编辑器工具/UI拼接工具.md
+++ b/modules/frameworks/编辑器工具/UI拼接工具.md
@@ -0,0 +1,248 @@
+# 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) | 模块登记规则定义分类和状态口径 |