Написание шаблонов UXML

Шаблоны UXML – это текстовые файлы, написанные с использованием XML-разметки, которые определяют логическую структуру пользовательского интерфейса. В следующем примере кода показано, как определить простую панель, предлагающую пользователю сделать выбор:

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

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

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

В UI(пользовательский интерфейс) Позволяет пользователю взаимодействовать с вашим приложением. Подробнее
См. в Словарь Toolkit, каждый элемент определяется либо в UnityEngine.UIElements или пространство имен UnityEditor.UIElements:

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

Например, если вы хотите использовать элемент 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, вы должны включить определение пространства имен и расположение файла схемы в тег <UXML> вместе с пространствами имен Unity.

Когда вы создаете новый ресурс шаблона UXML, выбирая Ресурс > Создать > Инструментарий пользовательского интерфейса > Окно редактора, редактор автоматически определяет для вас пространства имен.

Определение пользовательского интерфейса находится в корневом каталоге <UXML>. Определение пользовательского интерфейса представляет собой серию вложенных XML-элементов, каждый из которых представляет VisualElement.

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

• name: идентификатор элемента. Имя должно быть уникальным.
• picking-mode: установите либо Положение, чтобы реагировать на события мыши, либо Игнорировать , чтобы игнорировать события мыши.
• focus-index: (УСТАРЕЛО) Используйте tabIndex и фокусируемый.
• tabindex: целое число, определяющее позицию табуляции текущего элемента.
• фокусируемый: логическое значение, указывающее, можно ли сфокусировать элемент.
• класс: разделенный пробелами список идентификаторов, характеризующих элемент. Используйте классы для назначения визуальных стилей элементам. Вы также можете использовать классы для выбора набора элементов в UQuery.
• подсказка: строка, которая отображается в виде всплывающей подсказки при наведении указателя мыши на элемент.
• view-data-key : строка, определяющая ключ, используемый для сериализации элемента.

Пример шаблона UXML не определяет визуальный аспект пользовательского интерфейса. Рекомендуется определить информацию о стиле, такую ​​как размеры, шрифты и цвета для рисования пользовательского интерфейса, в отдельном файле USS (см. Стили и таблицы стилей Unity).

Добавление стилей в UXML

Для ссылки на файл таблицы стилей файл UXML может использовать элемент <Style> в любом объявлении элемента.

Например, если у вас есть файл UXML и файл USS ​​с именем «styles.uss» в одной папке:

<engine:UXML ...> <engine:VisualElement class="root"> <Style src="styles.uss" /> </engine:VisualElement> </engine:UXML> #root { width: 200px; height: 200px; background-color: red; }

Примечание. Unity не поддерживает элементы <Style> в корневом каталоге <UXML>. элемент.

Вы также можете объявить встроенные стили непосредственно как атрибут элементов UXML:

<engine:UXML ...> <engine:VisualElement style="width: 200px; height: 200px; background-color: red;" /> </engine:UXML>

Повторное использование файлов UXML

Вы можете создавать компоненты, просто определяя их в файле UXML. и импортируйте его с помощью элементов <Template> и <Instance> в другом файле UXML.

При разработке большого пользовательского интерфейса вы можете создать файлы шаблонов UXML, определяющие части пользовательского интерфейса.

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

Например, предположим, что у вас есть компонент Portrait в файле Assets/Portrait.uxml:

<engine:UXML ...> <engine:VisualElement class="portrait"> <engine:Image name="portaitImage" style="--unity-image: url(\"a.png\")"/> <engine:Label name="nameLabel" text="Name"/> <engine:Label name="levelLabel" text="42"/> </engine:VisualElement> </engine:UXML>

Вы можете встроить компонент Portrait в другие шаблоны UXML следующим образом:

<engine:UXML ...> <engine:Template src="/Assets/Portrait.uxml" name="Portrait"/> <engine:VisualElement name="players"> <engine:Instance template="Portrait" name="player1"/> <engine:Instance template="Portrait" name="player2"/> </engine:VisualElement> </engine:UXML>

Переопределение атрибутов UXML

При создании экземпляров шаблона UXML можно переопределить значения атрибутов по умолчанию для его элементов. Переопределение атрибутов позволяет многократно использовать один и тот же шаблон с разными значениями для каждого экземпляра.

Чтобы переопределить атрибут, необходимо указать:

• Атрибут element-name элемента, атрибуты которого вы хотите переопределить
• Имя переопределяемого атрибута
• Новое значение атрибута

В следующем примере

• player-name-label – это атрибут элемента element-name.
• text – это атрибут переопределения.
• Алиса – новое значение атрибута

<AttributeOverrides element-name="player-name-label" text="Alice" />

Переопределение атрибутов влияет на весь экземпляр, поэтому, если в экземпляре есть два элемента с именами player-name-label, и оба имеют текст, переопределение влияет на оба из них.

Пример переопределения атрибута

Допустим, вы создаете игру и хотите отображать один и тот же набор информации для каждого игрока. Вы можете создать один многократно используемый шаблон и использовать переопределения атрибутов для создания экземпляров для конкретного игрока.

Например, если вы создаете следующий шаблон:

<UXML xmlns="UnityEngine.UIElements"> <Label name="player-name-label" text="default name" /> <Label name="player-score-label" text="default score" /> </UXML>

Вы можете скопировать его из другого файла UXML и переопределить его атрибуты, чтобы отобразить имя и счет каждого игрока:

<UXML xmlns="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements"> <Template src="MyTemplate.uxml" name="MyTemplate" /> <Instance name="player1" template="MyTemplate"> <AttributeOverrides element-name="player-name-label" text="Alice" /> <AttributeOverrides element-name="player-score-label" text="2" /> </Instance> <Instance name="player2" template="MyTemplate"> <AttributeOverrides element-name="player-name-label" text="Bob" /> <AttributeOverrides element-name="player-score-label" text="1" /> </Instance> </UXML>

Переопределение нескольких атрибутов

Вы можете указать более одного атрибута для переопределения. Например, следующий синтаксис находит любой элемент в экземпляре с именем player-name-label и

• Переопределяет значение по умолчанию своего атрибута text новым значением Alice.
• Переопределяет значение по умолчанию своего атрибута tooltip новым значением, Tooltip 1.

<AttributeOverrides element-name="player-name-label" text="Alice" tooltip="Tooltip 1" />

Переопределение вложенных атрибутов

Переопределения атрибутов распространяются через вложенные шаблоны в иерархии элементов. Например, если шаблон A экземпляров шаблона B, а шаблон B экземпляров шаблона C, и шаблон A, и шаблон B могут переопределять атрибуты в шаблоне C.

При переопределении атрибутов во вложенных шаблонах приоритет имеет самое глубокое переопределение. Таким образом, в приведенном выше примере, если шаблон A и шаблон B переопределяют один и тот же атрибут шаблона C, переопределение в шаблоне B определяет, что на самом деле отображается в отображаемом пользовательском интерфейсе.

Ограничения

• Переопределение атрибутов находит соответствующие атрибуты в соответствии с указанным вами именем элемента. Они не используют селекторы USS или UQUery для сопоставления элементов.
• Переопределение атрибутов не привязано к привязке данных, хотя вы можете переопределить атрибут binding-path элемента.
• Вы не можете переопределить атрибуты name или style элемента.

Ссылки на другие файлы из UXML

Файлы UXML могут ссылаться на другие файлы UXML и файлы USS через элемент.

Как элементы <Template>, так и элементы <Style> принимают либо атрибут src, либо атрибут path. атрибут.

Атрибут src разрешает относительные пути, выводит сообщения об ошибках во время импорта (например, когда файлы отсутствуют) и гарантирует, что Unity правильно включает ссылку на активы ваших файлов UXML. в сборках игроков.

Атрибут path разрешает использование механизмов Unity Resources, но не предоставляет отчет об ошибках во время импорта и не разрешает относительные пути.

Атрибут src

Атрибут src предполагает, что путь к файлу будет относиться либо к корню проекта, либо к папке, содержащей файл UXML. Вы должны указать расширение файла. В следующих примерах файлы UXML расположены в папке Assets\Editor\UXML, а файл USS ​​— в папке Assets\Editor\USS.

• Используйте один из следующих примеров пути в зависимости от расположения файла UXML: src="../USS/styles.uss" или src="template.uxml"
• Используйте один из следующих примеров для абсолютного пути в зависимости от местоположения проекта: src="/Assets/Editor/USS/styles.uss" или < code class="mono">src="project:/Assets/Editor/UXML/template.uxml".

Атрибут путь

Атрибут path принимает файлы, расположенные либо в папке Resources, либо в папке Ресурсы редактора по умолчанию, со следующим правила:

• Если файл находится в папке Resources, не указывайте расширение файла. Например, напишите path="template" для файла, расположенного по адресу Assets/Resources/template.uxml.
• Если файл находится в папке Ресурсы редактора по умолчанию, необходимо указать расширение файла. Например, напишите path="template.uxml" для файла, расположенного в папке Assets/Editor Default Resources/template.uxml.