ui-ugui

理解现有的 Unity uGUI，进行有针对性的编辑，并生成基于 Canvas 的新层级结构。

处理 ScrollRect/ScrollView 时，请阅读参考文件：

• references/scrollview-setup.md — 必需的层级结构、设置规则和常见故障

范围

确定用户的具体需求：

请求类型	操作
关于 UI 的问题	理解 — 分析层级结构，解释其结构
修改特定元素	编辑 — 仅进行有针对性的修改
创建新 UI	生成 — 创建新的层级结构
修复/改进现有 UI	编辑 — 修改现有内容，不要重建

只生成用户要求的内容：

请求	输出
UI 布局	仅预制件或场景层级结构
“附带代码”/“附带逻辑”/“可正常使用”	层级结构 + 脚本

以下说法并不意味着需要脚本：

• “合适的按钮” → 配置完善的 Button 组件
• “可用的 UI” → 能正常渲染的有效层级结构
• “菜单界面” → 仅视觉布局

关键规则

命名空间消歧：

• 创建或引用 UI 组件时，始终使用完全限定的类型名称
• UnityEngine.UI.Image，而非 Image
• UnityEngine.UI.Button，而非 Button
• 项目中的其他命名空间可能导致类型歧义错误

修改前先验证：

• 进行更改前，始终检查当前已有内容
• 添加子对象前，确认父对象存在
• 修改属性前，确认组件存在
• 切勿假设层级结构的状态——先查询

优先采用增量修复，而非重建：

• 修复问题时，进行有针对性的更正
• 切勿为了修复问题而销毁并重建整个层级结构——被销毁的对象会导致一连串空引用
• 优先找出具体出错的属性并只修复该属性，而不是重写大段内容
• 修复失败时，先撤销更改，再尝试其他方案

一次只做一项更改：

• 每次只做一项更改，然后验证结果
• 不要批量进行多项互不相关的修改
• 编辑特定元素时，注意不要意外修改或删除相邻元素
• 如果出现问题，先弄清原因，再尝试其他方案
• 避免同时进行多项更改的“撒网式调试”

颜色和可见性：

• 确保文本默认清晰可读： 选择颜色时，确保文本与背景形成对比；但应尊重有意采用的低对比度设计（禁用状态、占位文本、装饰元素）
• 检查新元素的可见性： 创建 UI 元素后，确认其尺寸非零且位于父对象边界内。为后续切换、动画等目的而有意创建为隐藏状态的元素不受此限

遵循规格：

• 严格遵循用户规格： 用户提供像素尺寸、十六进制颜色、位置、间距或其他精确值时，必须精确应用——不要估算或替换
• 尽量减少无关更改： 编辑时，避免更改用户未提及的属性，除非相关调整是修复正常生效所必需的

约定

优先遵循项目现有模式。 应用默认设置前，先搜索现有文件。

类型	约定	好	不好
GameObject 名称	PascalCase	SubmitButton	submit-button
预制件路径	功能文件夹	Assets/UI/Inventory/	Assets/Prefabs/UI/

工作流

1. 验证状态 — 采取任何操作前，检查场景/层级结构中已有的内容。
2. 分析 — 准确确定所需内容，不添加额外内容。
3. 搜索 — 查找现有预制件、画布和资源。不要假设路径。
4. 遵循项目模式 — 匹配文件夹结构和命名方式。
5. 创建或编辑 — 使用正确的锚点构建结构，或进行有针对性的编辑。
6. 确认结果 — 确认更改生效后再继续。

Canvas 设置

每个 UI 都需要一个 Canvas：

Canvas (Screen Space - Overlay or Camera)
├── CanvasScaler (Scale With Screen Size recommended)
├── GraphicRaycaster
└── [UI Content]

CanvasScaler 设置：

• 默认使用 UI Scale Mode「Scale With Screen Size」，除非项目有特定理由使用「Constant Pixel Size」（例如像素风美术、固定分辨率目标）
• 参考分辨率：遵循项目标准（例如 1920x1080）
• 使用 Screen Space - Camera 创建 Canvas 时，先读取相机的参考分辨率
• Match Width Or Height：0.5（平衡）
• 如果现有 Canvas 使用「Constant Pixel Size」，请标记并在更改前询问用户
• 布局时优先使用锚点和 Layout Group，而非绝对像素位置

布局组件

Layout Group 控制子项尺寸：

• 当父对象具有 Layout Group 时，它会管理子对象的 RectTransform
• 父对象可能会覆盖子对象的锚点和 sizeDelta
• 设置值之前，先确认由父对象还是子对象控制尺寸

Vertical/Horizontal Layout Group：

• Control Child Size：决定父对象是否设置子对象的尺寸
• Child Force Expand：决定子对象是否拉伸以填满空间
• 如果关闭了 Control Child Size，子对象必须有明确的尺寸

避免布局冲突：

• 父对象控制子对象时，不要手动设置子对象的锚点或尺寸
• 不要给应保持固定尺寸的元素添加 Layout Group
• 嵌套的 Layout Group 需要仔细配置各层级
• 布局错误时，先检查父对象设置，再修改子对象
• ContentSizeFitter 与启用了 Control Child Size 的 Layout Group 位于同一对象上时，会发生冲突
• 父对象启用了 Control Child Size 时，子对象上的 ContentSizeFitter 会被覆盖（造成浪费）
• 在带有 Layout Group 的父对象下使用 ContentSizeFitter 时，请对相应轴禁用父对象的 Control Child Size
• 常见模式：ScrollView Content 应具有 ContentSizeFitter 和 VerticalLayoutGroup，其中 VLG 控制子对象，而 ContentSizeFitter 调整 Content 本身的尺寸

Grid Layout Group：

• 用于物品栏网格、卡片布局
• 必须明确设置 Cell Size——子对象的尺寸会与之匹配
• Constraint 控制行数或列数上限

Content Size Fitter：

• Horizontal/Vertical Fit：Preferred Size
• 用于需要根据内容调整尺寸的容器
• 需要布局元素或文本组件提供首选尺寸

RectTransform 锚点

元素必须具有非零尺寸才能显示：

• 通过 sizeDelta 设置明确的宽度和高度，或
• 使用带有适当偏移量的拉伸锚点，或
• 由父对象 Layout Group 控制尺寸（启用 Control Child Size）

锚点配置顺序：

1. 先设置锚点预设（角、边或拉伸）
2. 然后设置位置/偏移值
3. 确认最终尺寸非零

常见模式：

• 拉伸锚点 — 用于填充可用空间的自适应元素
• 角锚点 — 用于位置和尺寸固定的元素
• 边锚点 — 用于仅沿一个方向拉伸的元素

根据自然语言描述设置位置： 当用户描述位置时（例如「右上角」「底部栏」「左侧」）：

1. 确定它是角（固定点）、边（沿一个轴拉伸），还是填充（沿两个轴拉伸）
2. 设置 anchor min 和 anchor max——对于角，它们是同一个点；对于边/填充，它们跨越一个范围
3. 设置与锚点位置匹配的轴心点——轴心点必须与元素的锚定位置对齐，而不是保持默认值（0.5, 0.5）。「右上角」元素的轴心点应位于右上角；「顶部栏」的轴心点应位于顶部边缘的中心
4. 配置锚点和轴心点之后再设置位置/偏移值

可见性检查清单：

• 宽度和高度均大于零
• 元素位于父对象边界内
• 元素未被同级元素遮挡（检查层级顺序）
• Image 组件具有精灵图，或颜色的 alpha > 0

常用组件

组件	用途
Image	背景、图标
RawImage	渲染纹理、视频
Text (TMP)	所有文本（使用 TextMeshPro）
Button	可点击元素
Toggle	复选框、单选按钮
Slider	数值范围
ScrollRect	可滚动内容
InputField (TMP)	文本输入

最佳实践

• 所有文本都使用 TextMeshPro（而不是旧版 Text）
• 含有文本的 WorldSpace UI 也应使用 Text Mesh Pro；请检查项目，并在项目中尚未导入 TMP essentials 时导入
• 如果已导入 TextMeshPro Essentials，请在资源导入完成后关闭 TMP Importer Windows 和 Import Unity Package Window
• 按逻辑组织层级结构（Header、Content、Footer）
• 尽可能使用 Layout Groups，而不是手动定位
• 将非交互式图像的 Raycast Target 设为 false
• 使用精灵图集提升性能

绝不要使用 EditorApplication.ExecuteMenuItem("Window/TextMeshPro/Import TMP Essential Resources")，除非用户要求交互式安装 TMP Essentials。它会打开一个模态对话框，在人工关闭之前，调用它的任何操作都会被阻塞。

不要使用 AssetDatabase.ImportPackage() 导入 TMP 资源，应使用规范的非交互式 API TMP_PackageResourceImporter.ImportResources()。

交互就绪检查

完成任何包含交互元素的 UI 之前，请确认：

1. 场景中必须存在 EventSystem（且只能有一个）
2. Canvas 上必须有 GraphicRaycaster
3. 交互元素的 Raycast Target = true（非交互元素则设为 false，以免阻挡交互）
4. Button.onClick 应已连接（通过 Inspector 或脚本）——仅当用户要求编写脚本或实现逻辑时

如果前三项缺失，交互元素虽然会显示出来，但交互会静默失效。

理解

用户询问现有 UI 时：

先阅读层级结构。 不要猜测——回答前务必检查场景或预制件。

分析结构：

• 找出 Canvas 及其渲染模式
• 梳理父子关系
• 找出控制各个子对象的 Layout Groups
• 检查 RectTransform 锚点配置

回答以下问题：

• “这个按钮有什么作用？”→ 说明组件、层级位置和事件连接
• “这个布局是怎样的？”→ 描述 Layout Groups、锚点和层级结构
• “为什么这个元素不可见？”→ 检查尺寸、锚点、父对象边界和组件状态
• “是什么控制这个元素的尺寸？”→ 追溯 Layout Group 设置或锚点

编辑

针对现有 UI 进行定向修改时：

先检查，再编辑。 务必先检查当前状态。

编辑流程：

1. 确认目标对象存在
2. 找出需要更改的具体属性或组件
3. 进行必要的最小更改
4. 继续操作前验证结果

切勿通过销毁对象来修复问题：

• 销毁对象会导致其他位置的引用变为空
• 应就地修复属性，而不是重新创建对象
• 如果必须移除某个元素，请先更新所有引用

C#（仅在用户要求时）

• 使用完全限定的 UI 类型，以避免命名空间冲突
• 使用 [SerializeField] 保存 Inspector 引用
• 在 Awake() 中缓存组件引用
• 使用事件/委托处理按钮回调
• 将脚本放在与预制件相同的文件夹中（遵循项目现有模式）

组件引用：

• 访问前确认被引用的对象存在
• 处理序列化引用可能为空的情况
• 连接引用时，确认目标组件确实存在

错误恢复

出现问题时：

停下来诊断：

• 找出确切的错误或症状
• 尝试修复前先确定根本原因
• 不要进行推测性更改

逐步修复：

• 一次处理一个问题
• 验证每项修复后再继续下一项
• 记录所做的更改

避免破坏性做法：

• “从头开始”会连同正常工作的部分一起破坏
• 重建整个层级结构会引发更多问题，而非解决问题
• 优先采用精准修复，而不是全面替换

遇到困难时：

• 重新确认当前层级结构的状态
• 检查之前的更改是否已实际应用
• 考虑是否是方法本身有误，而非实现有误