Unity | UIToolkit 主题样式最佳实践

背景介绍

Unity UIToolkit 中定义了 Unity 样式表（Unity Style Sheet，简称 USS），与 Web 中的 CSS 一脉相承，有着相似的语法和用途。

此外，为了便于不同 UI 主题的应用，Unity 还定义了主题样式表（Theme Style Sheet，简称 TSS）， 可以看做一种特殊的 USS 文件，方便主题的管理和应用。

你可以新建一个 Unity 项目跟随以下教程，也可以使用已有 UI Toolkit 的项目来完成学习。

最佳实践流程

1. 前置准备

USS 不管是编辑器窗口界面，还是游戏界面，都是适用的，使用的方式也相同。可以根据自身的需求，在以下两个场景中任选一种进行前置准备。如果已有项目，也可以直接跳过该步骤直接开始。

场景1：游戏界面

• 在场景中创建 UIDocument：场景层级面板（Hierarchy）中，点击右键，选择 UI Toolkit -> UI Document
• 在资源中创建 UIDocument、 USS 和 TSS：资源面板（Project）中，点击右键，选择 UI Toolkit，然后依次创建 UI Document、Style Sheet 和 TSS Theme File。主题可以创建两个文件，用于后续切换主题。

场景2：编辑器窗口

2. 将 USS 应用到 UXML 中

双击 UXML 文件，将打开 UI Builder。点击 StyleSheets 面板中的 "+" 按钮，选择 Add Existing USS，选择之前创建的 USS 文件。这一步将 USS 应用到了当前的 UXML 文档上。

3. 写一个简单的样式，抽取到 USS 中

先在元素上修改背景颜色或者其他属性，然后填写类名，之后点击 Extract Inlined Styles to New Class，将样式内容抽取到刚刚添加的 USS 文件里。

点击保存后，可以看到 USS 的文本文件里增加了相关的类和样式。

4.【关键】将核心样式抽取为变量

注意：USS 变量需要使用 -- 作为前缀。

在 DarkTheme.tss 中写入：

:root {
    --sample-background: #158bb8;
}

在 LightTheme.tss 中写入：

:root {
    --sample-background: #d0dfe6;
}

在 BaseStyle.uss 中应用变量：

.sample-element {
    height: 146px;
    width: 351px;
    background-color: var(--sample-background);
}

5. 预览 TSS 样式效果

在 UI Builder 的 Viewport 面板中，选择

6.【关键】应用 TSS 样式

方法1：在 USS 中 import

在 USS 文件顶部添加以下代码（双引号内为 tss 文件路径）

@import url("/Assets/Resources/UI Toolkit/Theme/DarkTheme.tss");

该方法只适用于单一主题的应用

方法2：使用脚本应用到指定的 UXML 元素上

获取主题样式表，并添加到根元素的样式表列表里：

    var styleSheet = Resources.Load<StyleSheet>("UI Toolkit/Theme/DarkTheme");
    var root = gameObject.GetComponent<UIDocument>().rootVisualElement;
    root.styleSheets.Add(styleSheet);

示例代码：

public class MainUI : MonoBehaviour
{
    private void Start()
    {
        var root = gameObject.GetComponent<UIDocument>().rootVisualElement;
        root.Q<Button>("Light").clicked += Light;
        root.Q<Button>("Dark").clicked += Dark;
    }

    public void Light()
    {
        var styleSheet = Resources.Load<StyleSheet>("UI Toolkit/Theme/LightTheme");
        var root = gameObject.GetComponent<UIDocument>().rootVisualElement;
        root.styleSheets.Add(styleSheet);
    }

    public void Dark()
    {
        var styleSheet = Resources.Load<StyleSheet>("UI Toolkit/Theme/DarkTheme");
        var root = gameObject.GetComponent<UIDocument>().rootVisualElement;
        root.styleSheets.Add(styleSheet);
    }
}

运行效果：