Unity UI Toolkit

Unity UI Toolkit

协助使用 Unity UI Toolkit 进行开发，包括 UXML 标记、USS 样式、C# VisualElement API 和现代 UI 模式。

此技能的用途

UXML 结构

• 正确的元素层级和命名约定
• 常见控件：TextField、Button、Toggle、Slider、ObjectField、ListView
• 布局容器：VisualElement、ScrollView、Foldout、TwoPaneSplitView
• 使用模板和绑定实现数据驱动的 UI

USS 样式

• 基于类的样式和选择器
• Flexbox 布局（flex-direction、justify-content、align-items）
• USS 变量和深色主题优化
• 伪类（:hover、:active、:disabled）
• 过渡和动画

C# VisualElement API

• 查询 API：rootElement.Q<Button>("my-button")
• 事件处理：.clicked += 和 .RegisterValueChangedCallback()
• 使用构造函数动态创建 UI
• 使用 Bind() 和 SerializedObject 进行数据绑定

最佳实践

• 使用 UXML 定义结构、USS 定义样式、C# 编写逻辑
• 为元素命名，以便通过 Query API 访问
• 使用类来设置样式，而不是内联样式
• 在字段中缓存 VisualElement 引用
• 在 OnDestroy() 中正确清理事件

常见模式

编辑器窗口设置：

public void CreateGUI() {
    var visualTree = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>("path/to.uxml");
    visualTree.CloneTree(rootVisualElement);

    var button = rootVisualElement.Q<Button>("my-button");
    button.clicked += OnButtonClick;
}

USS 类切换：

element.AddToClassList("active");
element.RemoveFromClassList("active");
element.ToggleInClassList("active");

数据绑定：

var so = new SerializedObject(target);
rootVisualElement.Bind(so);

Unity 版本要求

• Unity 2021.2+ 支持运行时 UI Toolkit
• Unity 2019.4+ 支持仅用于编辑器的 UI Toolkit（功能有限）

完整 API 文档请参阅 ui-toolkit-reference.md。

何时使用及与其他组件的对比

在以下情况使用此技能：构建 UI Toolkit 界面、编写 UXML/USS，或在 C# 中操作 VisualElement

在以下情况使用 unity-ui-selector skill：为项目选择 UGUI 或 UI Toolkit

在以下情况使用 @unity-scripter agent：实现复杂的 UI 逻辑或自定义 VisualElement 控件

在以下情况使用 EditorScriptUIToolkit templates：使用 UXML/USS 文件生成新的 UI Toolkit 编辑器窗口

相关技能

• unity-ui-selector：帮助选择 UGUI 或 UI Toolkit
• unity-template-generator：生成 UI Toolkit 编辑器脚本模板
• unity-script-validator：验证 UI Toolkit 代码模式