Создание настраиваемого контроля

Хороший пользовательский контроллер является абстрактным, автономным и повторяющимся.

Переключатель слайдов Slide Toggle является хорошим примером пользовательского контроля:

• Это абстрактно. Вы можете использовать его для настройки параметров, таких как громкость, яркость, масштаб и мощность.
• Вы задаёте ему метку и начальное значение. Slide Toggle вызывает событие при изменении своего состояния.
• Он повторяется. Вы можете использовать его в нескольких местах в приложении.

Панель меню вашего приложения не является хорошим примером пользовательского контроля:

• Это не абстрактно. Это специфично для вашего приложения.
• Он не является самостоятельным. Возможно, у него есть зависимости от других частей вашего приложения.
• Это не повторяющееся меню. Возможно, в вашем приложении есть только одно меню.

После создания настраиваемого контроля, вы можете стилизовать его с помощью 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 Builder. Если вы хотите скрыть его на вкладке Библиотека, добавьте атрибут HideInInspector.

Инициализация настраиваемого контроля

Настраиваемые элементы управления наследуют от VisualElement. A VisualElement не является MonoBehaviour и поэтому не получает никаких обратных вызовов, которые MonoBehaviour получает, например 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 пользовательские свойства для стилизации пользовательского контроля.

Примечание: Inspector окно в UI Builder не показывает USS пользовательских свойств. Чтобы изменить USS пользовательских свойств, используйте текстовый редактор для редактирования USS файл непосредственно.

Для взаимодействия с пользовательскими свойствами USS для пользовательского контроля в C# используйте структуру CustomStyleProperty и событие CustomStylesResolvedEvent.

CustomStyleProperty описывает имя и тип свойства, которое вы читаете из таблицы стилей.

UI Toolkit отправляет CustomStylesResolvedEvent для любого элемента, который непосредственно получает пользовательское свойство USS. Он отправляет событие для любого элемента, который соответствует селектору, для селекторов, где правило содержит значение пользовательского свойства. UI Toolkit не отправляет событие для элементов, которые наследуют значение. Событие содержит ссылку на объект ICustomStyle. Вы должны использовать его TryGetValue() метод для чтения эффективного значения объекта CustomStyleProperty. Этот метод имеет перегрузки для различных типов CustomStyleProperty.

Для настраиваемого стиля с примером настраиваемого контроля см. Создание настраиваемого стиля для настраиваемого контроля.

Примечание: Вы не можете определить переходы для свойств пользовательского стиля.

Обработка событий для настраиваемых элементов управления

Подробные сведения о том, как обрабатывать события для пользовательских элементов управления, см. в Обработка событий.

Примечание:

• Unity отправляет события клавиатуры к элементу, находящемуся в фокусе. события клавиатуры для настраиваемого элемента управления, установить свойства, связанные с focus.
• Для обработки событий касания и ввода мышью регистрируйте обратные вызова для соответствующих типов событий, таких как события указателя и события мышив конструкторе.

Передовые методы и советы

• Показывать свойства, которые представляет пользовательский контроллер, и другие функциональные аспекты его поведения как свойства UXML, а свойства, влияющие на внешний вид пользовательского контроллера, как свойства USS.

• Используйте уникальное, короткое и читаемое пространство имен, чтобы избежать столкновений имен с другими элементами.

• Держите UXML атрибуты примитивные. Данные, которые можно указать в UXML ограничивается набором примитивных типов данных. UXML не поддерживает сложные структуры данных или коллекции. Передайте сложные данные к вашим пользовательским контролям во время выполнения через C# скриптов или привязки данных, не в UXML.

• В C# выносите USS-классы или имена в константы. Так элементы можно находить по классу или имени с помощью UQuery.

• принимает BEM стандарт для USS-классов. Благодаря этому к любому элементу можно обратиться селектором по списку классов.

• Используйте статические обратные вызовы, чтобы снизить расход памяти. Регистрация метода экземпляра в качестве обратного вызова может приводить к лишним выделениям памяти. Чтобы их избежать, применяйте анонимные статические лямбда-функции, вызывающие обычные статические методы C#. Контекст текущего элемента можно получить через EventBase.currentTarget свойства.

• Отображение пользовательской геометрии с помощью обратного вызова generateVisualContent для пользовательских элементов управления. Пример использования, который отображает частично заполненный круг, см. в примере RadialProgress.

• Настраиваемые элементы управления удобны, однако те же результаты можно получить с помощью следующих средств:

  • Соберите UI из существующих элементов и измените их стили и свойства.
  • Используйте шаблоны UXML. Используйте обычные C# MonoBehaviours для добавления логики, относящейся к конкретному UI Документу, в котором находится ваш UI. Документ. Чтобы узнать, как использовать MonoBehaviours для управления UI в UI Документе, см. Создание первого времени выполнения UI. Для достижения инкапсуляции создайте свойства и методы внутри MonoBehaviour, которые внутренне получают VisualElementс помощью UQuery и манипулируют их свойствами.

Дополнительные ресурсы

• Создание настраиваемых примеров управления