ui-uitk

理解现有的 Unity UI Toolkit 代码，进行有针对性的编辑，生成新的 UXML/USS 文件和 Manipulator，并处理 UI 运行时绑定。

参考资料

按需阅读：

• references/uss-guide.md — USS 模式和示例
• references/svg-icons.md — SVG 图标生成（仅在生成图标时）
• references/common-issues.md — 需要避免的常见错误
• references/ui-runtime-binding.md — 运行时将数据绑定到 UI 的模式和指南（仅在用户提出要求或涉及绑定时）
• references/painter2d.md — 用于自定义视觉效果的 Painter2D API：渐变、形状、弧线、程序化绘制（需要渐变、自定义形状、进度环、程序化绘制，或任何 USS 无法实现的视觉效果时，均须阅读）
• references/pointermanipulator-guide.md — 创建和使用 Manipulator 的模式和指南（仅在用户提出要求或涉及 Manipulator 时）。这有助于为 Visual Element 设置拖放功能或简单的事件处理。
• references/custom-elements.md — 自定义 UI Element 模式，以及使用 UXML、USS 和 C# 创建可复用组件的指南。这有助于创建可在项目中重复使用的复杂 UI 组件。

路径相对于此技能的文件夹 — 直接读取 references/uss-guide.md。

理解

解释 UI 结构时，使用以下格式：

[ElementType] name="elementName" class="class1 class2"
├── [ChildType] name="childName"
│   └── [GrandchildType]
└── [ChildType] class="another-class"

编辑

常见编辑请求：

请求	操作
“更改按钮颜色”	编辑该按钮的 USS 选择器
“在此处添加标签”	在指定位置向 UXML 添加元素
“把这个调大”	在 USS 中编辑宽度/高度
“隐藏此元素”	在 USS 中添加 display: none，或从 UXML 中移除
“重命名此元素”	更新 UXML 中的 name 属性

不要过度编辑：

• 仅更改用户要求的内容
• 保留格式和结构
• 不要“改进”无关代码
• 除非用户要求，否则不要添加注释
• 对于有针对性的更改，优先修改特定元素或选择器，而不是重写整个文件 — 但要灵活判断；如果更改涉及文件的大部分内容，重写可能更简洁
• 编辑时注意不要意外删除现有元素、样式或引用
• 编辑 USS 时，聚焦于与请求相关的属性和选择器 — 避免不必要的重组，但如果更改确实需要，则应调整结构

验证

无法在 Editor 外部验证 UXML 或 USS — Unity 会在导入这些文件时解析它们，并在 Console 中报告问题。写入文件后，让用户检查结果。

工作流：

1. 将完整文件写入项目中的目标路径。不要写入不完整或草稿内容 — Editor 一旦检测到未完成的 UXML 文件，就会出现解析错误。
2. 请用户将焦点切换到 Unity Editor。此操作会触发对已更改资源的重新导入。
3. 请用户报告 Console 中的任何问题。UXML 解析错误会指出文件和行号；USS 问题则会显示为有关未知属性或选择器的警告。
4. 根据用户反馈修复问题，并从第 1 步重复操作。

由于收集反馈需要用户来回沟通，因此应尽可能一次做对：

• 先完成所有文件，再请用户检查，这样一次重新导入就能覆盖所有文件，而不是每个文件都导入一次。
• 写入文件前，重新阅读 references/uss-guide.md 和 references/common-issues.md，不要等出错后再读。
• 留意那些能通过解析但会导致渲染错误的问题 — 这些问题不会出现在 Console 中，因此需要用户目视检查 UI。references/common-issues.md 列出了这类问题。

生成

创建新 UI 时：

只生成请求的内容：

请求	输出
仅 USS	仅 .uss 文件
仅 UXML	仅 .uxml 文件
UI 屏幕／菜单／面板	仅 .uss + .uxml
“带代码”／“带逻辑”／“可运行”	.uss + .uxml + .cs

以下请求并不意味着需要 C#：

• “合适的按钮” → 样式完善的 Button 元素
• “货币显示” → 一个 Label 元素
• “可用的 UI” → 可渲染的有效 UXML／USS
• “库存屏幕” → 仅视觉布局
• “库存系统”／“装备系统”／“制作系统” → 询问：“物品是否应该可拖动？”如果是，请参阅 references/pointermanipulator-guide.md 了解相关模式

生成工作流：

1. 分析 — 准确确定所需文件，不要添加额外文件。
2. 搜索 — 查找现有的 USS、UXML 和资源，不要假设路径。
3. 遵循项目模式 — 匹配文件夹结构和命名约定。
4. 复用 — 检查是否有共享样式表，适用时予以复用。
5. 先编写 USS — 对照以下限制进行验证。
6. 编写 UXML — 引用 USS 并验证结构。
7. 完整写出文件 — 绝不要只提供部分内容；有关错误如何返回以及为何一次性生成完整文件优于分多次生成，请参阅上文“验证”。
8. 场景设置 — 如果将 UI 添加到场景中，请分配 PanelSettings。
9. 数据绑定 — 如果有此请求，请添加采用运行时数据绑定模式的 C# 脚本（参阅 references/ui-runtime-binding.md）。如有需要，生成 scriptable object 资源。在 UXML 中将该资源分配给 UI 元素根节点，或通过 C# 中的数据源进行分配。

颜色、可见性和规格规则：

• 确保文本默认易于阅读： 选择颜色时，确保文本与背景形成足够对比，同时尊重有意采用低对比度的情况（禁用状态、占位文本、装饰元素）。使用设计令牌时，请检查文本和背景变量是否提供了足够的对比度。
• 遵循精确数值： 用户指定的十六进制颜色、像素尺寸和间距都必须原样使用。不要近似处理或替换。

样式／主题 为 UI 设置样式或调整主题时，不要只应用于当前 UXML 中的元素，还要应用于 UI Toolkit 的核心元素，因为这些元素通常由多个子元素组成。

约定

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

类型	约定	好	不好
name 属性	camelCase	submitButton	submit-button
class 属性／USS	kebab-case	.submit-button	.submitButton
文件路径	功能文件夹	Assets/UI/Inventory/	Assets/Scripts/UI/

输出格式：

<ui:UXML>...</ui:UXML>

.class { ... }

USS 限制

Unity 的 USS 是 CSS 的子集。以下属性不存在，绝对不要使用：

绝对不要使用	改用
border 简写	分别使用 border-width、border-color
gap	在子元素上设置 margin
z-index	使用 DOM 顺序或父级嵌套
pointer-events	UXML 属性 picking-mode
filter	不支持
outline	border-* 属性
box-shadow	嵌套元素或背景图片
:first-child、:last-child、:nth-child	显式类
[attribute] 选择器	显式类
transition-property: <value>	完全省略，或仅使用 none、initial、inherit
linear-gradient()、radial-gradient()	使用 Painter2D 的自定义 VisualElement（参见 references/painter2d.md）

内联样式： 绝对不要在 UXML 中使用 style="..."。所有样式仅写在 USS 中。

外部 URL： 绝对不要使用指向外部路径的 url()。只能使用 url("project://database/Assets/...")。

优先使用灵活布局，避免硬编码尺寸：

• 使用 flex-grow、flex-shrink 或 %，而不是固定的 width/height 值
• 让元素自然排列，并受其父容器约束
• 仅在根容器上或确实需要固定尺寸时，才设置明确的像素尺寸
• 子元素应适应可用空间，而不是自行定义尺寸

USS 简洁规范

• 不写默认值（flex-direction: column 为默认值）
• 不写默认字体
• 不写冗余约束（width: 100px 无需设置 min-width/max-width）
• 不写重叠属性（flex: 1 已设置 grow/shrink）
• 使用能满足需求的最简单选择器
• 绝不重复定义选择器

UXML

每个文件都必须：

1. 声明命名空间：<ui:UXML xmlns:ui="UnityEngine.UIElements">
2. 链接样式表：<ui:Style src="Screen.uss" />
3. 恰好包含一个顶层容器
4. 不使用 style="..." 属性——仅使用 USS

<ui:UXML xmlns:ui="UnityEngine.UIElements">
  <ui:Style src="Panel.uss" />
  <ui:VisualElement name="root" class="panel">
    
  </ui:VisualElement>
</ui:UXML>

事件与交互

• 使用 Pointer Manipulator 处理 VisualElement 上的事件和交互（参见 references/pointermanipulator-guide.md）
• 如果用户要求拖放，则编写 pointer Manipulator，并通过 UXML 或 C# 将其附加到相关的 Visual Element。
• 对于简单的点击事件，可以在 UXML 中使用 clickable Manipulator
• 对于更复杂的交互，创建并使用更传统的 C# 事件回调，并根据需要将其附加到元素

对于库存和制作系统：

• 当用户请求“库存系统”“装备系统”或“制作系统”时，明确询问：“玩家是否应该能够拖放物品？”
• 如果是，请阅读 references/pointermanipulator-guide.md，了解库存/制作专用模式
• 如果不是或不明确，则仅创建静态布局

资源

不要引用 UnityDefaultRuntimeTheme.tss 或 Unity 内置主题图标。

图标优先级：

1. 重用项目中已有的图标
2. 生成 SVG（参见 references/svg-icons.md）
3. 使用图像生成器（最后手段）

引用格式：

background-image: url("project://database/Assets/UI/Textures/icon.png");

场景设置

必须配置 PanelSettings——否则 UI 不会渲染。

1. 搜索现有的 PanelSettings 资源
2. 如果没有，则创建通用资源：Assets/UI/PanelSettings.asset
3. 将其指定给 UIDocument 的 Panel Settings 字段

Editor UI（EditorWindow、PropertyDrawer）可跳过此步骤。

C#（仅在用户要求时）

• 通过 USS 类设置样式（AddToClassList()）——绝不要使用 element.style.*。内联样式的优先级高于 USS 选择器，因此无法通过样式表覆盖，而且会增加每个元素的内存开销
• UITK 使用 TextCore 文本资源——使用 FontAsset、TextStyleSheet 和 TextSettings，不要使用对应的 TextMeshPro 类型（TMP_FontAsset 等）
• 将脚本放在与 UXML/USS 相同的文件夹中