创建自定义控件

一个好的自定义控件是抽象的、独立的和重复的。

滑动切换是自定义控件的一个很好的示例：

• 这是抽象的。您可以使用它来调整设置，例如音量、亮度、比例和功率。
• 它是独立的。你给它一个标签和一个初始值。幻灯片切换会在事件状态更改时触发事件。
• 它是反复出现的。您可以在应用程序的多个位置使用它。

应用程序的菜单栏不是自定义控件的良好示例：

• 它不是抽象的。它特定于您的应用程序。
• 它不是独立的。它可能依赖于应用程序的其他部分。
• 它不会重复出现。您的应用程序中可能只有一个菜单。

创建自定义控件后，可以使用 USS 设置其样式，并添加逻辑以在 C# 中处理事件。

创建和使用自定义控件

若要创建自定义控件，请执行以下作：

• 添加UxmlElement属性添加到自定义控件类定义。
• 将自定义控件类声明为分部类。
• 继承自VisualElement或其派生类之一。

例如：

using UnityEngine;
using UnityEngine.UIElements;

[UxmlElement]
public partial class ExampleElement : VisualElement {}

创建自定义控件后，你可以在UXML和UI Builder中使用它们。

以下示例 UXML 文档使用自定义控件：

<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <ExampleElement />
</ui:UXML>

默认情况下，自定义控件显示在 UI 生成器的“库”选项卡中。如果要从“库”选项卡中隐藏它，请添加HideInInspector属性。

初始化自定义控件

自VisualElement.一个VisualElement不受游戏对象Unity 场景中的基本对象，可以表示角色、道具、风景、相机、航路点等。游戏对象的功能由附加到它的组件定义。更多信息
请参阅术语表并且不会收到以下任何回调：

• Awake()
• OnEnable()
• OnDisable()
• OnDestroy()

可以在其构造函数中初始化自定义控件。但是，如果应用程序需要它，可以延迟初始化，直到将自定义控件添加到 UI。为此，请注册一个回调AttachToPanelEvent.若要检测自定义控件是否已从 UI 中删除，请使用DetachFromPanelEvent回调。

public CustomControl()
{
    RegisterCallback<AttachToPanelEvent>(e =>
        { /* do something here when element is added to UI */ });
    RegisterCallback<DetachFromPanelEvent>(e =>
        { /* do something here when element is removed from UI */ });
}

UI Toolkit 为所有元素调度这两个事件，不需要自定义VisualElement亚纲。有关更多信息，请参阅小组活动。

使用 USS 设置自定义控件的样式

使用 USS 自定义自定义控件的外观，其方式与内置控件相同。您还可以创建 USS 自定义属性以设置自定义控件的样式。

注意：该检查器一个Unity 窗口，显示有关当前选定游戏对象、资产或项目设置的信息，允许您检查和编辑值。更多信息
请参阅术语表窗口不显示 USS 自定义属性。要编辑 USS 自定义属性，请使用文本编辑器直接编辑 USS 文件。

若要在 C# 中与自定义控件的自定义 USS 属互，请使用CustomStyleProperty结构和CustomStylesResolvedEvent事件。

CustomStyleProperty描述从样式表中读取的属性的名称和类型。

UI 工具包调度CustomStylesResolvedEvent对于直接接收自定义 USS 属性的任何元素。它为选择器匹配的任何元素（规则包含自定义属性值的选择器）分派事件。UI 工具包不会为继承该值的元素调度事件。该事件包含对ICustomStyle对象。您必须使用它TryGetValue()读取有效值的方法CustomStyleProperty.此方法对不同类型的CustomStyleProperty.

有关具有自定义控件示例的自定义样式，请参阅为自定义控件创建自定义样式。

【注】您无法为自定样式属性定义过渡。

处理自定义控件的事件

有关如何处理自定义控件的事件的详细信息，请参阅处理事件。

注意：

• Unity 将键盘事件分派到当前聚焦的元素。若要处理自定义控件的键盘事件，请设置与focus.
• 若要处理触摸和鼠标输入事件，请在构造函数中注册相关事件类型（如指针事件和鼠标事件）的回调。

最佳做法和提示

• 将自定义控件表示的属性及其行为的其他功能方面公开为 UXML 属性，并将影响自定义控件外观的属性公开为 USS 属性。

• 使用唯一、简短且可读的命名空间来避免名称碰撞当物理引擎检测到两个游戏对象的碰撞器接触或重叠时，当至少一个游戏对象具有刚体组件并且处于运动状态时，就会发生碰撞。更多信息
  请参阅术语表与其他元素。

• 保持 UXML 属性原始。你可以在UXML中指定的数据仅限于一组基元数据类型。UXML 不支持复杂的数据结构或集合。通过 C# 在运行时将复杂数据传递给自定义控件脚本一段代码，允许您创建自己的组件、触发游戏事件、随时间修改组件属性以及以您喜欢的任何方式响应用户输入。更多信息
  请参阅术语表或数据绑定，而不是 UXML。

• 在 C# 中，将 USS 类或名称公开为常量。这允许您使用 UQuery 按类或名称查找元素。

• 采用 USS 级 BEM 标准。这允许您使用类列表选择器来寻址每个元素。

• 使用静态回调以降低内存占用。注册要用作回调的实例方法时，可能会创建不必要的分配。若要避免分配，请使用调用常规 C# 静态方法的匿名静态 lambda 函数。您可以通过EventBase.currentTarget财产。

• 通过generateVisualContent自定义控件的回调。有关呈现部分填充圆的示例用法，请参阅 RadialProgress 示例。

• 自定义控件很方便。但是，您可以通过以下方式获得相同的结果：

  • 从现有元素组装 UI，并更改其样式和属性。
  • 使用UXML模板。使用常规 C#MonoBehaviours 以添加与保存 UI 的特定 UI 文档相关的逻辑。了解如何使用MonoBehaviour要控制 UI 文档中的 UI，请参阅创建第一个运行时 UI。要实现封装，请在MonoBehaviour在内部获取VisualElements 与 UQuery 并纵它们的属性。

其他资源

• 创建自定义控件示例