为自定义控件创建自定义样式

版本: 2023.2+

此示例演示如何在自定义控件中使用自定义 USS 变量。

示例概述

此示例创建一个自定义控件，该控件从 USS 读取两种颜色并使用它们生成纹理。

您可以在此 GitHub 仓库 中找到此示例创建的完整文件。

先决条件

本指南适用于熟悉 Unity 编辑器、UI(用户界面) 允许用户与您的应用程序交互。Unity 目前支持三种 UI 系统。 更多信息
请参见 词汇表 工具包和 C# 脚本的开发人员。在开始之前，请熟悉以下内容

• UI 生成器
• 可视树由轻量级节点组成的对象图，用于保存窗口或面板中的所有元素。它定义了您使用 UI 工具包构建的每个 UI。
  请参见 词汇表
• UXML
• USS

创建自定义控件

创建一个 C# 脚本以定义自定义控件，并创建一个 USS 文件以定义自定义样式。

1. 使用任何模板创建一个 Unity 项目。
2. 创建一个名为 create-custom-style-custom-control 的文件夹来存储您的文件。
3. 在 ExampleElementCustomStyle 文件夹中，创建一个名为 ExampleElementCustomStyle.cs 的 C# 脚本，并将它的内容替换为以下内容

using UnityEngine;
using UnityEngine.UIElements;

namespace UIToolkitExamples
{
    [UxmlElement]
    public partial class ExampleElementCustomStyle : VisualElement
    {
        // Use CustomStyleProperty<T> to fetch custom style properties from USS
        static readonly CustomStyleProperty<Color> S_GradientFrom = new CustomStyleProperty<Color>("--gradient-from");
        static readonly CustomStyleProperty<Color> S_GradientTo = new CustomStyleProperty<Color>("--gradient-to");

        // Image child element and its texture
        Texture2D m_Texture2D;
        Image m_Image;

        public ExampleElementCustomStyle()
        {
            // Create an Image and a texture for it. Attach Image to self.
            m_Texture2D = new Texture2D(100, 100);
            m_Image = new Image();
            m_Image.image = m_Texture2D;
            Add(m_Image);

            RegisterCallback<CustomStyleResolvedEvent>(OnStylesResolved);
        }

        // When custom styles are known for this control, make a gradient from the colors.
        void OnStylesResolved(CustomStyleResolvedEvent evt)
        {
            Color from, to;

            if (evt.customStyle.TryGetValue(S_GradientFrom, out from)
                && evt.customStyle.TryGetValue(S_GradientTo, out to))
            {
                GenerateGradient(from, to);
            }
        }

        public void GenerateGradient(Color from, Color to)
        {
            for (int i = 0; i < m_Texture2D.width; ++i)
            {
                Color color = Color.Lerp(from, to, i / (float)m_Texture2D.width);
                for (int j = 0; j < m_Texture2D.height; ++j)
                {
                    m_Texture2D.SetPixel(i, j, color);
                }
            }

            m_Texture2D.Apply();
            m_Image.MarkDirtyRepaint();
        }
    }
}

创建自定义控件和自定义样式

创建一个名为 ExampleElementCustomStyle.uss 的 USS 文件，并将它的内容替换为以下内容

ExampleElementCustomStyle {
    --gradient-from: red;
    --gradient-to: yellow;
}

在 UI 文档中使用自定义控件

创建一个 UI 文档以使用自定义控件，并将自定义样式应用于自定义控件。

1. 在 ExampleElementCustomStyle 文件夹中，创建一个名为 ExampleElementCustomStyle.uxml 的 UI 文档。
2. 双击 ExampleElementCustomStyle.uxml 在 UI 生成器中打开它。
3. 选择 库 > 项目 > UIToolkitExamples，并将 ExampleElementCustomStyle 拖动到层次结构窗口中。视窗窗口中将出现一个灰色正方形。
4. 将 ExampleElementCustomStyle.uss 文件添加为现有 USS。这会将自定义 USS 变量应用于正方形。

其他资源

• 创建自定义控件
• BEM 标准