---
name: ui-prefab-dev
description: Unity UI Prefab 开发：结构分析、组件修改、代码生成。涉及 UI Prefab 层级查看、组件属性读取、UI 控制器代码编写。触发关键词：UI界面 UI开发、Prefab 预制体、UIBaseController、AutoGen、UGUI、RectTransform、Image Button Text、ScrollRect 列表、extract_ui_prefab、ExtractedPrefabs、UI控制器。
version: "1.0"
updated: "2026-05-08"
---

# UI Prefab 开发

分析、修改和生成 Unity UI Prefab 及相关 C# 控制器代码。

## 前置知识

- **UI Prefab 位置**: `Assets/` 下的各 UI 模块目录
- **UI 控制器代码**: `Assets/Code/Scripts/GamePlay/UI/`（60+ 控制器）
- **生成代码标记**: `*Controller.AutoGen.cs` 文件（自动生成，勿手动修改）
- **ExtractedPrefabs**: `ExtractedPrefabs/` 目录存放导出的 Prefab JSON 结构
- **JSON 格式说明**: `ExtractedPrefabs/README.md`

## 工作流

### 1. 获取 UI Prefab 结构

通过 Unity MCP 提取 Prefab 结构信息：

```
execute_custom_tool: {
  tool_name: "extract_ui_prefab",
  parameters: { prefab_path: "Assets/xxx/xxx.prefab" }
}
```

读取返回的 JSON 文件，参考 `ExtractedPrefabs/README.md` 理解 JSON 格式。

> **重要**: 每次分析前都需重新提取（避免读取旧数据）。

### 2. 理解 UI 层级结构

JSON 格式和属性格式定义见 `ExtractedPrefabs/README.md`。

常见组件类型：
- **RectTransform**: 锚点、位置、尺寸
- **Image**: Sprite 引用、Color、ImageType、RaycastTarget
- **Text/TMP_Text**: 文本内容、字体、字号、颜色
- **Button**: Transition 类型、颜色状态
- **CanvasRenderer**: 渲染参数

### 3. 分析 UI 控制逻辑

UI 控制器代码模式：

```
// 手动编写的控制器（可修改）
public class UI_XXXController : UIBaseController
{
    // 绑定 UI 组件引用
    // 业务逻辑方法
}

// 自动生成的控制器（不可手动修改）
public class UI_XXXController.AutoGen : ... 
{
    // 自动生成的组件绑定代码
}
```

### 4. 修改或创建 UI

修改已有 UI：
1. 提取 Prefab JSON 了解当前结构
2. 查看对应的 `*Controller.cs` 了解代码逻辑
3. 修改 Prefab（通过 Unity Editor）或代码
4. 确保 AutoGen 和手动代码分工明确

创建新 UI：
1. 在 Unity 中创建 Prefab
2. 编写对应的 Controller 类（继承 UIBaseController）
3. 如需自动绑定，编写 AutoGen 辅助类
4. 注册到 UI 管理系统中

## 不适用场景

- 纯逻辑 UI 改动（不涉及 Prefab 结构变化）→ 直接改 Controller 代码即可
- 简单的位置/颜色微调 → 无需走完整提取流程，直接描述修改即可

## 属性格式参考

| 类型 | 格式示例 |
|------|----------|
| Vector2 | `AnchoredPosition:0,0` |
| Vector3 | `LocalPosition:0,0,0` |
| Color | `Color:#RRGGBBAA` |
| Bool | `RaycastTarget:true` |
| Enum | `ImageType:Sliced` |
| 引用 | `Sprite:icon_name` |

## UI 模块索引

```
GamePlay/UI/
├── Activity/        # 活动界面
├── BattlePass/      # 战令
├── Camp/            # 营地
├── Character/       # 角色界面
├── Dispatch/        # 派遣
├── Draw/            # 抽卡
├── Legion/          # 军团
├── LegionBattle/    # 军团战
├── LegionPve/       # 军团PVE
├── LevelFight/      # 关卡战斗
├── Loading/         # 加载界面
├── Login/           # 登录
├── Mail/            # 邮件
├── Package/         # 背包
├── PVP/             # PVP
├── Raffle/          # 抽奖
├── Shop/            # 商店
├── Story/           # 剧情
├── Task/            # 任务
└── Team/            # 编队
```

## 安全规则

- AutoGen 文件（`*Controller.AutoGen.cs`）不可手动修改
- Prefab 修改后需要在 Unity 中保存，.meta 文件由 Unity 自动生成
- 图片资源引用确保路径正确，避免丢失引用
- UI 变更可能影响多个界面，修改前确认影响范围