← UI системы Шаг 301 из 317

Миграция из uGUI в UI Toolkit

На этой странице разработчикам, имеющим опыт работы с uGUI (Unity UI), дается руководство по переходу на новую систему UI Toolkit. На этой странице рассматриваются сходства и различия между uGUI и UI Toolkit.

Поскольку uGUI является системой только времени выполнения UI, эта страница посвящена времени выполнения UI. UI Toolkit может создавать как время выполнения, так и редактор UI. Это руководство относится к обоим случаям использования UI Toolkit.

Иерархия UI

И uGUI, и UI Toolkit создают и поддерживают UI в виде иерархического дерева. В uGUI все элементы этой иерархии видны в панели Hierarchy как отдельные GameObjects. В UI Toolkit визуальные элементы организованы в визуальное дерево. Визуальное дерево не отображается в панели.

Для просмотра и отладки UI иерархия в UI Toolkit, вы можете использовать UI Отладчик. Вы можете найти UI Отладчик на панели инструментов Редактора, под Окно > UI Toolkit > Отладчик.

Основные различия

Canvas против UIDocument

Компонент Canvas в uGUI похож на компонент UIDocument в UI Toolkit. Оба являются MonoBehaviours, которые присоединяются к GameObjects.

В uGUI компонент Canvas находится в корне дерева UI. Он работает с компонентом Canvas Scaler для определения порядка сортировки, отображения и масштабирования UI, находящегося внизу.

В UI Toolkit, UIDocument компонент содержит ссылку на PanelSettings объект. PanelSettings содержит настройки отображения для UI, включая режим масштабирования и порядок сортировки. UIDocument компоненты могут указывать на одну и ту же PanelSettings объект, который оптимизирует производительность при использовании нескольких UI экранов в одной и той же сцене.

В uGUI иерархия дерева UI расположена ниже иерархии GameObject, содержащей компонент Canvas. В UI Toolkit компонент UIDocument содержит ссылку на корневой элемент Визуального Дерева.

Компонент UIDocument также содержит ссылку на файл UXML, который определяет макет UI, из которого строится Визуальное Дерево во время выполнения. Дополнительные сведения см. в разделе Создание UI.

Примечание: Для редактора UI, нет UIDocument компонент. Свой класс можно унаследовать от EditorWindow, а затем осуществить CreateGUI()* Практический пример см. в руководстве по Создание пользовательских окон редактора.

GameObject компоненты против визуальных элементов

UI Toolkit относится к элементам UI как к элементам управления или визуальным элементам. Примерами элементов UI являются:

Контроль
Кнопки
Текстовые метки

uGUI строит иерархию UI из GameObjects. Добавление новых элементов UI требует добавления новых элементов GameObjects в иерархию. Отдельные элементы управления реализованы как компоненты MonoBehaviour.

В UI Toolkit, визуальное дерево виртуален и не использует GameObject. Строить и просматривать иерархию интерфейса в окне иерархии больше нельзя, зато исчезают издержки на отдельный GameObject для каждого элемента интерфейса.

В uGUI, UI элементы вытекают (прямо или косвенно) из UIBehavior базовый класс. Точно так же в UI Toolkit все элементы интерфейса наследуют базовый класс VisualElement. Ключевое различие — это VisualElement класс не наследуется от MonoBehaviour. Вы не можете прикрепить визуальные элементы к GameObjects.

Работа с элементами управления UI Toolkit в скрипте аналогична работе с элементами управления uGUI.

В следующей таблице показаны типичные взаимодействия скриптов с UI контроллерами в uGUI и их UI Toolkit аналогами.

Действия	uGUI	UI Toolkit
Запись текста в метку	`m_Label.text = "My Text";`	`m_Label.text = "My Text";`
Чтение состояния переключателя	`bool isToggleChecked = m_Toggle.isOn;`	`bool isToggleChecked = m_Toggle.value;`
Назначение обратного вызова кнопке	`m_Button.onClick.AddListener(MyCallbackFunc);`	`m_Button.clicked += MyCallbackFunc_1;` или `m_Button.RegisterCallback<ClickEvent>(MyCallbackFunc_2);`

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

Доступ к UI элементам

В uGUI существует два способа доступа скриптов к элементам UI:

Назначение ссылки на компоненты UI в редакторе.
Поиск компонентов в иерархии с помощью вспомогательных функций, таких как GetComponentInChildren<T>().

Поскольку не существует GameObject или компонентов в UI Toolkit, вы не можете напрямую назначать ссылки на элемент управления в редакторе. Они должны быть разрешены во время выполнения с помощью функции запроса. Вместо этого, доступ к визуальному дереву через UIDocument компонент.

UIDocument является MonoBehaviour, так что вы можете назначить его в качестве ссылки и сделать его частью Префаб. Компонент UIDocument содержит ссылку на корневой визуальный элемент. Из корня, скрипты могут найти дочерние элементы по типу или по имени, подобно uGUI.

В таблице ниже показано прямое сравнение доступа к UI управления в uGUI и UI Toolkit

Действия	uGUI	UI Toolkit
Найти UI элемент по имени	`transform.FindChild("childName");`	`rootVisualElement.Query("childName");`
Найти UI элемент по типу	`transform.GetComponentInChildren<Button>();`	`rootVisualElement.Query<Button>();`
Прямое назначение ссылки в редакторе	Возможно	Невозможно

Создать UI

Одним из самых больших различий между uGUI и UI Toolkit является создание пользовательских интерфейсов.

И uGUI, и UI Toolkit позволяют визуально построить UI и просмотреть его в Редакторе. В uGUI UI сохраняется в Префаб вместе с любыми логическими скриптами, прикрепленными к отдельным UI контроллерам.

В UI Toolkit макет UI создается в UI Builder, затем сохраняется в виде одного или нескольких файлов UXML. Во время выполнения компоненты UIDocument загружают файлы UXML, которые Визуальное Дерево собирает в памяти.

Для метода, похожего на uGUI, можно создать UI контроллеры непосредственно из скрипта, а затем добавить их в Визуальное Дерево во время выполнения.

Префабы

uGUI использует GameObjects для отдельных UI элементов управления и Префабы, которые содержат визуальные эффекты и логику. UI Toolkit использует другой подход к многократному использованию, так как разделяет логику и макет. Вы можете создавать многократно используемые UI компоненты с помощью UXML и пользовательских элементов управления.

Чтобы создать шаблон, похожий на Префаб в UI Toolkit:

Создать файл UXML для частичного элемента UI.
Создайте GameObject с компонентом UIDocument.
Ссылка на файл UXML в GameObject.
Добавить скрипт для обработки логики компонента UI в том же GameObject.
Сохраните GameObject как Префаб.

UI макет

Расположение отдельных UI элементов на экране в uGUI является ручным процессом. По умолчанию, UI контроллеры свободно плавающие и влияют только на их непосредственный родитель. Другие UI контроллеры под тем же родителем не влияют на позиции или размеры своих братьев. Pivots и якоря контролируют положение и размер элемента.

Система макета UI Toolkit находится под влиянием веб-дизайна и основана на автоматическом генерировании макета. Автоматическая система макета по умолчанию влияет на все элементы, а размер и положение элемента влияет на другие элементы под тем же родителем.

Поведение по умолчанию в UI Toolkit сравнимо с размещением всех элементов внутри VerticalLayoutGroup в uGUI и добавлением компонента LayoutElement к каждому из них.

Вы можете отключить автоматическое создание макета, изменив свойство IStyle position визуального элемента. Это свойство имеется у всех визуальных элементов. Образец кода см. в Визуальное дерево.

UI Toolkit не имеет прямых эквивалентов для анкерирования и поворота элементов UI, из-за фундаментальных различий в расположении по сравнению с uGUI.

Размер и положение элемента контролируются движком макета. Более подробную информацию см. в Движок макета и Системы координат и позиций.

Порядок представления

В uGUI порядок GameObjects в иерархии определяет порядок отображения. Объекты ниже в иерархии отображаются последними и появляются сверху. В сцене с несколькими Canvas, Sort Order на корне Canvas определяет порядок отображения отдельных деревьев UI.

Порядок отображения в визуальное дерево в UI Toolkit родительские элементы рендируются перед своими детьми, а дети рендируются от первого до последнего, так что последний появляется сверху. В сцене с несколькими элементами, каждый элемент рендируется отдельно. UI Документы, порядок представления которых определяется Sort Order установка на корне UIDocument компонент.

Чтобы изменить порядок отображения элемента в uGUI, например, чтобы элемент появился сверху, вы можете вызвать функции сестер на Transform компонент GameObject. VisualElement классе есть похожие функции для управления порядком отрисовки. Поскольку все элементы управления UI Toolkit наследуют этот класс, эта функция доступна им всем.

В таблице ниже показаны функции uGUI для управления порядком отображения и эквивалентные функции в UI Toolkit:

Действия	uGUI	UI Toolkit
Сделать элемент отображается под всеми другими братьями	`transform.SetAsFirstSibling();`	`myVisualElement.SendToBack();`
Сделать элемент отображается на вершине всех других братьев	`transform.SetAsLastSibling();`	`myVisualElement.BringToFront();`
Ручное управление порядком отображения элемента относительно его братьев	`transform.SetSiblingIndex(newIndex);`	`myVisualElement.PlaceBehind(sibling);` `myVisualElement.PlaceInFront(sibling);`

Мероприятия

Как и в uGUI, взаимодействия пользователя в UI Toolkit вызывают события. Код может подписаться на получение обратного вызова по событиям, таким как нажатие кнопки или перемещение ползунок.

В uGUI все элементы UI основаны на MonoBehaviour и могут выставлять свои события в Редакторе. Это позволяет настроить логику с другими GameObjects, например, скрыть или показать другие UI элементы, или назначить функции обратного вызова.

В UI Toolkit логика и макет UI хранятся отдельно. Обратные вызова больше нельзя устанавливать непосредственно в GameObjects или хранить в Префабы. Вы должны устанавливать все обратные вызова во время выполнения и обрабатывать их с помощью скриптов.

Button playButton = new Button("Play");
playButton.RegisterCallback<ClickEvent>(OnPlayButtonPressed);
...
private void OnPlayButtonPressed(ClickEvent evt)
{
  // Handle button press
}

Система отправки событий в UI Toolkit отличается от событий в uGUI. В зависимости от типа события, события отправляются не только к целевому контроллеру UI, но и ко всем родительским контроллерам.

Дополнительные сведения об этом см. в События отправки.

Используйте uGUI и UI Toolkit в одном проекте

Возможно, вы используете uGUI и UI Toolkit в одном и том же проекте.

Вы также можете создать весь проект с помощью uGUI и создать только некоторые пункты меню с помощью UI Toolkit.

Вы можете использовать либо UI Toolkit, либо uGUI для любого элемента, который не взаимодействует за пределами своих границ. Например, для времени выполнения UI вы можете использовать uGUI для создания экранных кнопок, таких как джойстик для мобильных устройств, и использовать UI Toolkit для создания модального окна.

Однако, расширенные взаимодействия между смешанными UI не работают:

Вы не можете использовать только клавиатуру для свободной навигации между фокусируемым элементом в UI Toolkit и выбранным объектом uGUI. Для навигации вы должны использовать скрипты C# для регистрации событий на пограничных элементах и вручную выбирать или фокусировать следующий элемент из другого домена.
Вы не можете встроить uGUI внутрь иерархии UI Toolkit или UI Toolkit в иерархию uGUI. Вы можете использовать RenderTexture для рисования, но события не будут настигать друг друга.
Конвенции стилизации и событий в UI Toolkit отличаются от uGUI. Трудно создать проект, в котором UI выглядит единым, если вы используете разбросанную смесь uGUI и UI Tookit.

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

← Предыдущий шагМиграция настраиваемых элементов управления из предыдущей версии в Unity 6 Следующий шаг →Миграция из Немедленного Режима GUI (IMGUI) в UI Toolkit