创建可绑定的自定义控件

版本： 2023.2+

此示例演示如何在自定义编辑器窗口中创建可绑定的自定义控件。

示例概述

此示例创建绑定到具有 double 数据类型的属性的自定义控件。您可以调整此示例以绑定到具有其他数据类型（如字符串或整数）的属性。

您可以在此 GitHub 存储库中找到此示例创建的已完成文件。

先决条件

本指南适用于熟悉 Unity 编辑器、UI 工具包和 C# 脚本的开发人员。在开始之前，请熟悉以下内容：

• UI 生成器
• 可视化树 由轻量级节点组成的对象图，用于保存窗口或面板中的所有元素。它定义了使用 UI 工具包构建的每个 UI。
  请参阅术语表
• UXML的
• SerializedObject 数据绑定

创建自定义控件类

创建一个 C# 类来定义自定义控件。

1. 使用任何模板创建 Unity 项目。
2. 创建一个名为ExampleField以存储您的文件。
3. 在ExampleField文件夹中，创建一个名为ExampleField.cs并将其内容替换为以下内容：

using UnityEngine.UIElements;

namespace UIToolkitExamples
{
    // ExampleField inherits from BaseField with the double type. ExampleField's underlying value, then, is a double.
    [UxmlElement]
    public partial class ExampleField : BaseField<double>
    {
        Label m_Input;

        // Default constructor is required for compatibility with UXML factory
        public ExampleField() : this(null)
        {

        }

        // Main constructor accepts label parameter to mimic BaseField constructor.
        // Second argument to base constructor is the input element, the one that displays the value this field is
        // bound to.
        public ExampleField(string label) : base(label, new Label() { })
        {
            // This is the input element instantiated for the base constructor.
            m_Input = this.Q<Label>(className: inputUssClassName);
        }

        // SetValueWithoutNotify needs to be overridden by calling the base version and then making a change to the
        // underlying value be reflected in the input element.
        public override void SetValueWithoutNotify(double newValue)
        {
            base.SetValueWithoutNotify(newValue);

            m_Input.text = value.ToString("N");
        }
    }
}

在 UXML 文件中使用自定义控件

1. 在ExampleField文件夹中，创建一个名为ExampleField.uxml.
2. 打开ExampleField.uxml并将其内容替换为以下内容：

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:example="UIToolkitExamples">
    <example:ExampleField label="Binding Target" binding-path="m_Value" />
</ui:UXML>

为绑定目标创建类

1. 在 Unity 中，双击ExampleField.uxml在 UI Builder 中打开它。ExampleField 显示在“层次结构”窗口中，并在视口用户在屏幕上应用的可见区域。
   请参阅术语表.如果在“层次结构”窗口中选择 ExampleField，则检查器一个 Unity 窗口，显示有关当前选定游戏对象、资产或项目设置的信息，允许您检查和编辑值。更多信息
   请参阅术语表窗口显示分配给“绑定路径”（Binding Path） 和“标签”（Label） 框的值。
2. 在ExampleField文件夹中，创建一个名为ExampleFieldComponent.cs并将其内容替换为以下内容：

using UnityEngine;

namespace UIToolkitExamples
{
    public class ExampleFieldComponent : MonoBehaviour
    {
        [SerializeField]
        double m_Value;
    }
}

为绑定目标创建自定义编辑器

1. 在ExampleField文件夹中，创建一个名为Editor.
2. 在Editor文件夹中，创建一个名为ExampleFieldCustomEditor.cs并将其内容替换为以下内容：

using UnityEditor;
using UnityEngine.UIElements;
using UnityEngine;

namespace UIToolkitExamples
{
    [CustomEditor(typeof(ExampleFieldComponent))]
    public class ExampleFieldCustomEditor : Editor
    {
        [SerializeField]
        VisualTreeAsset m_Uxml;

        public override VisualElement CreateInspectorGUI()
        {
            var parent = new VisualElement();

            m_Uxml?.CloneTree(parent);

            return parent;
        }
    }
}

测试示例

1. 在 Unity 中，选择ExampleFieldCustomEditor.cs在项目窗口一个窗口，显示您的内容Assets文件夹（项目选项卡）更多信息
   在术语表中查看.
2. 拉ExampleField.uxml进入 Inspector 窗口中的 Uxml 框。
3. 添加一个空的游戏对象Unity 场景中的基本对象，可以表示角色、道具、风景、相机、航路点等。游戏对象的功能由附加到它的组件定义。更多信息
   请参阅术语表设置为场景场景包含游戏的环境和菜单。将每个唯一的场景文件视为一个独特的关卡。在每个场景中，你放置你的环境、障碍物和装饰品，基本上是将你的游戏设计和构建成碎片。更多信息
   请参阅术语表.
4. 添加ExampleFieldComponent组件添加到游戏对象。自定义控件显示在检查器中，默认值为0用于绑定目标。如果更改基础 double 属性的值，UI 会反映该更改。

其他资源

• 自定义控件