UnityAI/modules/frameworks/编辑器工具/UI拼接工具.md

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 配置文件结构

{
  "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/...  │
└─────────────────────────────────────────────────────────────────────┘

使用示例

方式一：外部命令触发

# 正向：从 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. 选择要导出的预制体文件

方式三：代码调用

// 正向：从 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：

@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 拼接开发人员

---

文档关联

当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

文档	关联原因
编辑器工具入口	本文件是编辑器工具模块的子文档
UI 窗口系统	UI 拼接工具服务于 UI 窗口系统
UI 界面拼接设计指南	设计指南说明 JSON 驱动的界面拼接原则
modules/模块索引.md	模块索引是项目知识总入口
rules/10-架构说明.md	架构说明定义编辑器工具层与运行时层边界
rules/20-开发规则.md	编辑器工具开发规则互相引用
rules/30-模块登记规则.md	模块登记规则定义分类和状态口径