Unity UI Toolkit

Unity UI Toolkit

此技能的功能

使用 UI Toolkit（Unity 6+ 的现代 UI 系统）创建 Unity 界面。 生成 UXML 结构（布局）、USS 样式（外观）和 C# presenter/controller 代码 （逻辑）。涵盖运行时 UI（游戏）和 Editor UI（工具）。 逐步取代 UGUI，采用类似 Web 的方式：分离结构、样式和逻辑，使用 flexbox 和 CSS 伪类。

前提条件

• Unity 6+（原生包含 UI Toolkit，可用于运行时）
• 场景中的 GameObject 上挂有 UIDocument 组件
• PanelSettings 资源（排序顺序、缩放模式、屏幕匹配）

快速开始

1. 分析 UI 需求（需要哪个屏幕、有哪些交互）
2. 选择合适的控件（参见 references/uitk-controls.md）
3. 创建 .uxml（结构）→ .uss（样式）→ C# presenter（逻辑）
4. 在场景中挂载 UIDocument + PanelSettings

决策树

Quel type d'UI ?
+-- Runtime UI (jeu) ?
|   +-- HUD simple (health bar, score) → UXML + USS + C# direct query
|   +-- Menu / ecran complet → UXML + USS + C# presenter + navigation stack
|   +-- UI world-space → UIDocument sur GO + PanelSettings world-space
+-- Editor UI ?
|   +-- Custom Inspector → CreateInspectorGUI() + UXML (voir /unity-editor-tools)
|   +-- EditorWindow → CreateGUI() + UXML
+-- Legacy UGUI existant → evaluer migration ou coexistence

分步指南

步骤 1：UXML 文件（结构）

<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <ui:VisualElement name="root" class="screen">
        <ui:VisualElement name="header" class="header">
            <ui:Label name="title" text="Game Title" class="title-text" />
        </ui:VisualElement>
        <ui:VisualElement name="menu-buttons" class="button-container">
            <ui:Button name="btn-play" text="Play" class="menu-button" />
            <ui:Button name="btn-settings" text="Settings" class="menu-button" />
            <ui:Button name="btn-quit" text="Quit" class="menu-button" />
        </ui:VisualElement>
    </ui:VisualElement>
</ui:UXML>

步骤 2：USS 文件（样式）

.screen {
    flex-grow: 1;
    justify-content: center;
    align-items: center;
    background-color: rgb(20, 20, 30);
}
.title-text {
    font-size: 48px;
    color: rgb(230, 230, 240);
    -unity-font-style: bold;
    -unity-text-align: middle-center;
}
.button-container {
    flex-direction: column;
    align-items: center;
}
.menu-button {
    width: 300px;
    height: 60px;
    margin: 8px;
    font-size: 24px;
    color: rgb(220, 220, 230);
    background-color: rgb(40, 40, 55);
    border-radius: 8px;
    border-width: 0;
    transition: scale 0.15s ease-in-out, background-color 0.15s ease-in-out;
}
.menu-button:hover {
    scale: 1.05;
    background-color: rgb(60, 60, 80);
}
.menu-button:active {
    scale: 0.97;
    background-color: rgb(50, 100, 180);
}

步骤 3：C# presenter（逻辑）

using UnityEngine;
using UnityEngine.SceneManagement;
using UnityEngine.UIElements;

[RequireComponent(typeof(UIDocument))]
public class MainMenuPresenter : MonoBehaviour
{
    private void Awake()
    {
        var root = GetComponent<UIDocument>().rootVisualElement;
        root.Q<Button>("btn-play").clicked += OnPlay;
        root.Q<Button>("btn-settings").clicked += OnSettings;
        root.Q<Button>("btn-quit").clicked += OnQuit;
    }

    private void OnPlay() => SceneManager.LoadScene("Game");
    private void OnSettings() { /* push settings screen */ }
    private void OnQuit()
    {
#if UNITY_EDITOR
        UnityEditor.EditorApplication.isPlaying = false;
#else
        Application.Quit();
#endif
    }
}

步骤 4：在场景中设置

1. 创建一个空 GameObject“UI”
2. 添加 UIDocument 组件
3. 在 Source Asset 中指定 .uxml
4. 指定一个 PanelSettings（Assets > Create > UI Toolkit > Panel Settings Asset）
5. 配置：Scale Mode = Scale With Screen Size，Reference Resolution
6. 将 presenter 脚本挂载到同一个 GameObject 上
7. 如果有多个 UIDocument 共存，则调整 Sort Order

严格规则

• 始终使用 Q<T>("name") 查询元素（绝不使用不带类型的 Query）
• 始终使用 USS 类设置样式（除动态样式外，不使用 C# 内联样式）
• 绝不让 UXML 嵌套超过 5 层（应重构为子模板）
• 始终使用 flexbox 布局（除覆盖层外，不使用 absolute 定位）
• 始终分离 UXML（结构）、USS（样式）、C#（逻辑）——MVC
• 优先使用 [UxmlElement] / [UxmlAttribute] 创建自定义控件（Unity 6+）
• 始终通过调整 Game 视图大小测试响应式布局
• 绝不在 presenter 中编写业务逻辑——委托给服务/管理器
• 必要时始终在 OnDisable/OnDestroy 中注销回调
• 简单效果优先使用 USS 过渡，而非 C# 动画

文件组织

Assets/UI/
├── Screens/          MainMenu.uxml/.uss, Settings.uxml/.uss, HUD.uxml/.uss
├── Components/       PlayerCard.uxml/.uss, HealthBar.uxml
├── Themes/           Variables.uss, DarkTheme.tss
└── PanelSettings/    RuntimePanel.asset, WorldSpacePanel.asset

相关技能

• /unity-editor-tools — 使用 UI Toolkit 构建 Editor UI（Custom Inspectors、EditorWindows）
• /unity-code-gen — 根据 UXML 自动生成 C# presenters

故障排除

症状	可能原因	解决方案
元素不可见	没有 flex-grow 或尺寸为 0	添加 flex-grow: 1 或明确设置 width/height
样式未应用	类名错误 / specificity 问题	检查拼写，并使用 UI Debugger 检查
点击未检测到	picking-mode: Ignore	设置为 picking-mode: Position
DataBinding 未更新	缺少 [CreateProperty]	添加属性并实现 INotifyBindablePropertyChanged
文本被截断	默认 white-space: nowrap	使用 white-space: normal 或 text-overflow: ellipsis
USS 过渡卡顿	动画元素过多	限制为 :hover/:active
UI 模糊	缩放模式不正确	使用 Scale With Screen Size + reference resolution
Z-order 不正确	UIDocument 的 Sort Order	提高 Sort Order