← Руководство

Введение в UXML

Формат UXML вдохновлен HTML, XAML, и XML. Если вы работали с этими форматами раньше, вы найдете сходства в UXML. Однако, формат UXML включает небольшие различия, чтобы обеспечить эффективный способ работы с Unity. На этой странице представлен формат UXML на примере.

Ниже приведен пример файла UXML. Он содержит несколько встроенных элементов управления UI, которые предлагают пользователю сделать выбор:

<?xml version="1.0" encoding="utf-8"?>
<engine:UXML
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:engine="UnityEngine.UIElements"
    xmlns:editor="UnityEditor.UIElements"
    xsi:noNamespaceSchemaLocation="../../UIElementsSchema/UIElements.xsd"
>
    <engine:Box>
        <engine:Toggle name="boots" label="Boots" value="false" />
        <engine:Toggle name="helmet" label="Helmet" value="false" />
        <engine:Toggle name="cloak" label="Cloak of invisibility" value="false"/>
    </engine:Box>
    <engine:Box>
        <engine:Button name="cancel" text="Cancel" />
        <engine:Button name="ok" text="OK" />
    </engine:Box>
</engine:UXML>

Декларация UXML

Первая строка кода в вышеприведённом примере UXML — это объявление UXML. Это объявление необязательно. Если вы включаете объявление UXML, вы должны поместить его в первую строку. Объявление UXML требует объявления version. Атрибут encoding необязателен в объявлении UXML. Если вы включаете атрибут encoding, вы должны объявить кодировку символов файла.

Корень документа

Следующая строка определяет корень документа, <engine:UXML>. Элемент <engine:UXML> включает атрибуты для определения префиксов пространства имен и расположения файлов определения схемы. Вы можете указать эти атрибуты в любом порядке.

Пространство имён

В UI Toolkit каждый элемент определяется либо в пространстве имен UnityEngine.UIElements, либо в пространстве имен UnityEditor.UIElements:

Пространство имен UnityEngine.UIElements содержит элементы, которые определены как часть времени выполнения Unity.
Пространство имен UnityEditor.UIElements содержит элементы, которые доступны в Unity Editor. Чтобы полностью указать элемент, вы должны префиксировать его пространством имен.

Например, если вы хотите использовать элемент Button в шаблоне UXML, вы должны указать <UnityEngine.UIElements:Button />.

Чтобы упростить определение пространств имен, можно определить префикс пространства имен. Например, xmlns:engine="UnityEngine.UIElements" определяет префикс engine как UnityEngine.UIElements. После определения префикса пространства имен, его можно использовать для определения пространств имен. Например, <engine:Button /> эквивалентен <UnityEngine.UIElements:Button />

Пространство имен по умолчанию можно также определить, исключив префикс. Например, xmlns="UnityEngine.UIElements" определяет UnityEngine.UIElements в качестве пространства имен по умолчанию. Это означает, что указание, например, <Button /> эквивалентно <UnityEngine.UIElements:Button />.

Чтобы создать файл UXML с автоматически определенными пространствами имен, выберите Актив > Создать > UI Toolkit > UI Документ.

Примечание: если вы объявляете собственные элементы, не определяйте класс пользовательского элемента управления в UnityEngine.UIElements или UnityEditor.UIElements В противном случае UI Builder скроет ваши пользовательские элементы управления.

Определение схемы

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

В файле UXML атрибуты xsi:noNamespaceSchemaLocation или xsi:schemaLocation корневого элемента <engine:UXML> указывают местоположение файлов определения схемы.

Чтобы создать файл UXML с последним определением схемы, выберите Ассеты > Создать > UI Toolkit > UI Документ. Это создаст файл с атрибутом xsi:noNamespaceSchemaLocation для корневого элемента.

Примечание: Если ваш текстовый редактор не распознает xsi:noNamespaceSchemaLocation атрибут, используйте xsi:schemaLocation атрибут вместо.

Чтобы принудительно обновить определение схемы UXML, выберите Ассеты > Update UXML Schema.

UXML элементы

Определение UI находится в корне <engine:UXML>. Определение UI представляет собой серию вложенных элементов UXML, каждый из которых представляет визуальный элемент.

Имя элемента соответствует имени класса C#, экземпляр которого создаётся. У большинства элементов есть атрибуты, значения которых сопоставляются с соответствующими свойствами класса в C#. У каждого элемента свой набор атрибутов в дополнение к унаследованным от родительского класса. VisualElement — базовый класс для всех элементов; он предоставляет всем элементам следующие атрибуты:

name: Идентификатор элемента. Имя должно быть уникальным.
picking-mode: Установите либо Position для реагирования на события мыши, либо Ignore для игнорирования событий мыши.
focus-index: (OBSOLETE) Используйте tabIndex и focusable.
tabindex: Целое число, определяющее позицию текущего элемента в таблице.
focusable: Булевая величина, указывающая, фокусируется ли элемент.
class: Разделенный пробелами список идентификаторов, характеризующих элемент. Используйте классы для назначения визуальных стилей элементам. Вы также можете использовать классы для выбора набора элементов в UQuery.
tooltip: Строка, которая отображается как tooltip при наведении мыши на элемент.
view-data-key : Строка, которая определяет ключ, используемый для серийного номера элемента.