Unity3D

Unity3D ：创建自定义控件

ygtu

May 17, 2023 • 8 min read

推荐：将NSDT场景编辑器加入你的3D工具链

3D工具集：NSDT简石数字孪生

创建自定义控件

若要创建自定义控件，必须创建自定义控件 C# 类并对其进行初始化。您可以公开它以在 UXML 中使用，并且用户界面
建筑工人。您还可以将其绑定到数据。

创建自定义控件类

创建派生自 VisualElement 类或该类的子类的 C# 类。例如，可以创建派生自 BaseField 泛型基类而不是 BindableElement 的可绑定自定义控件。这具有以下优点：VisualElement

实现您指定的泛型参数类型的接口INotifyValueChanged
默认情况下使控件可聚焦
提供水平布局，左侧是标签元素，右侧是输入

FloatField 是一个内置的 UI Toolkit 控件，它继承自 BaseField.<br/>A。标签元素.<br/>B.输入元素。 — FloatField 是一个内置的 UI 工具包控件，它继承自 .一个。标签元素。二.输入元素。`BaseField`

注意：如果您了解内置 UI 控件的内部层次结构和现有 USS 类，则可以创建从内置 UI 控件派生的自定义控件。Unity 不鼓励这种做法，因为您的自定义控件可能依赖于其内部结构，将来可能会发生变化。

初始化自定义控件

自定义控件继承自。A 不绑定到 a 的生存期VisualElementVisualElement游戏对象
并且不会收到任何以下回调：

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

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

void OnEnable()
{
    var myCustomElement = rootVisualElement.Q(className: "my-custom-element");
    myCustomElement.RegisterCallback<AttachToPanelEvent>(e =>
        { /* do something here when element is added to UI */ });
    myCustomElement.RegisterCallback<DetachFromPanelEvent>(e =>
        { /* do something here when element is removed from UI */ });
}

UI 工具包为所有元素调度这两个事件，不需要自定义子类。有关详细信息，请参阅面板事件。VisualElement

向 UXML 和 UI 生成器公开自定义控件

若要将自定义控件与 UXML 和 UI 生成器配合使用，必须公开它们。若要公开自定义控件，请定义派生自 UxmlFactory<T> 的工厂类。

可以将新属性添加到要在 UXML 中使用的自定义控件。若要向自定义控件添加新属性，请定义派生自 traits 类并重写该方法，如定义元素的属性中所述。UI 生成器依赖于此来确保UxmlTraitsInit()视觉元素
创建于视窗
在检查员
.

若要在 UI 生成器的检查器中使用自定义控件的 UXML 属性，必须匹配 UXML 和 C# 脚本之间的属性名称。对 UXML 使用标准烤肉串大小写表示法，对 C# 使用骆驼大小写或帕斯卡大小写。例如，在 C# 中命名为或的属性应位于 UXML 中。MyFloatmyFloatmy-float

将自定义控件绑定到数据

将自定义控件绑定到序列化属性，以同步控件和属性之间的值。

将自定义控件绑定到数据：

实现 INotifyValueChanged 接口，并根据需要侦听 ChangeEvent。
从 BindableElement 类继承或实现 IBindable 接口。

有关更多详细信息，请参阅序列化对象数据绑定。

有关可绑定的自定义控件示例，请参阅创建可绑定的自定义控件。

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

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

注： UI 生成器中的“检查器”窗口不显示 USS 自定义属性。要编辑 USS 自定义属性，请使用文本编辑器直接编辑 USS 文件。

若要与 C# 中的自定义控件的自定义 USS 属性进行交互，请使用 CustomStyleProperty 结构和 CustomStylesSolveEvent 事件。

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

UI Toolkit 为直接接收自定义 USS 属性的任何元素调度 CustomStylesSolveEvent。它为选择器匹配的任何元素调度事件，用于规则包含自定义属性值的选择器。UI 工具包不会为继承值的元素调度事件。该事件包含对 ICustomStyle 对象的引用。必须使用其 TryGetValue（） 方法来读取 CustomStyleProperty 的有效值。此方法对不同类型的自定义样式属性具有重载。

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

注意：您无法为自定义样式属性定义过渡。

处理自定义控件的事件

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

注：

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

在 UI 生成器中使用自定义控件

将自定义控件添加到可视化树
在 UI 生成器中：

选择“库>项目”>“自定义控件（C#）”。
将自定义控件拖到“层次结构”窗口中。

最佳做法和提示

最佳实践：

将自定义控件表示的属性及其行为的其他功能方面公开为 UXML 属性，并将影响自定义控件外观的属性公开为 USS 属性。
使用唯一、简短且可读的命名空间以避免名称碰撞
与其他元素。
保持 UXML 属性基元。可以在 UXML 中指定的数据仅限于一组基元数据类型。UXML 不支持复杂的数据结构或集合。在运行时通过 C# 将复杂数据传递给自定义控件脚本
或数据绑定，而不是在 UXML 中。
在 C# 中，将 USS 类或名称公开为常量。这允许您使用 UQuery 按类或名称查找元素。
采用 BEM 标准用于 USS 类。这允许您使用类列表选择器处理每个元素。
使用静态回调可降低内存占用量。注册要用作回调的实例方法时，可能会创建不必要的分配。若要避免分配，请使用调用常规 C# 静态方法的匿名静态 lambda 函数。可以通过 EventBase.currentTarget 属性检索当前元素的上下文。

小贴士：

通过自定义控件的生成可视化内容回调呈现自定义几何图形。有关呈现部分填充圆的示例用法，请参阅径向进度示例。

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

从现有元素组装 UI，并更改其样式和属性。
使用 UXML 模板。使用常规 C# 添加与保存 UI 的特定 UI 文档相关的逻辑。（若要了解如何使用 s 控制 UI 文档中的 UI，请参阅创建第一个运行时 UI。要实现封装，请在内部创建属性和方法，这些属性和方法使用 UQuery 在内部获取 VisualElement并操作其属性。MonoBehaviourMonoBehaviourMonoBehaviour

其他资源

向 UXML 和 UI 生成器公开自定义控件
创建具有两个属性的自定义控件
创建滑动切换自定义控件
创建径向进度指示器
创建可绑定的自定义控件
为自定义控件创建自定义样式

由3D建模学习工作室整理翻译，转载请注明出处！

上一篇：Unity3D ：使用 C# 脚本构建 UI (mvrlink.com)

下一篇：Unity3D ：向 UXML 和 UI 生成器公开自定义控件 (mvrlink.com)