Формат UXML

Файлы Unity Extensible Markup Language (UXML) — это текстовые файлы, определяющие структуру пользовательского интерфейса. Формат UXML основан на HTML, XAML и XML. Если вы уже работали с этими форматами раньше, вы найдете сходство с UXML. Однако формат UXML содержит небольшие отличия, обеспечивающие эффективный способ работы с Unity.

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

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

определить структуру пользовательского интерфейса (UI) в XML.
определить UI(пользовательский интерфейс) Позволяет пользователю взаимодействовать с вашим приложением. Подробнее
См. в макете Словарь с таблицами стилей USS.

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

Определение новых элементов

С помощью UI Toolkit вы можете определять свои собственные компоненты и элементы пользовательского интерфейса.

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

Например, следующий код получает новый класс StatusBar и реализует его конструктор по умолчанию:

class StatusBar : VisualElement
{
    public StatusBar()
    {
        m_Status = String.Empty;
    }

    string m_Status;
    public string status { get; set; }
}

Чтобы UI Toolkit создавал экземпляр нового класса при чтении файла UXML, вы должны определить фабрику для своего класса. Если вашей фабрике не нужно делать что-то особенное, вы можете получить фабрику из UxmlFactory. Рекомендуется поместить фабричный класс в класс компонента.

Например, в следующем коде показано, как определить фабрику для класса StatusBar, унаследовав фабрику от UxmlFactory. Фабрика называется UxmlFactory:

class StatusBar : VisualElement
{
    public new class UxmlFactory : UxmlFactory {}

    // ...
}

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

Определение атрибутов элементов

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

Например, в следующем коде показано, как определить класс характеристик UXML для инициализации свойства status как свойства StatusBar класс. Свойство состояния инициализируется из данных XML.

class StatusBar : VisualElement
{
    public new class UxmlFactory : UxmlFactory {}

    public new class UxmlTraits : VisualElement.UxmlTraits
    {
        UxmlStringAttributeDescription m_Status = new UxmlStringAttributeDescription { name = "status" };

        public override IEnumerable uxmlChildElementsDescription
        {
            get { yield break; }
        }

        public override void Init(VisualElement ve, IUxmlAttributes bag, CreationContext cc)
        {
            base.Init(ve, bag, cc);
            ((StatusBar)ve).status = m_Status.GetValueFromBag(bag, cc);
        }
    }

    // ...
}

UxmlTraits служит двум целям:

Фабрика использует его для инициализации вновь созданного объекта.
Процесс создания схемы анализирует ее, чтобы получить информацию об элементе. Эта информация преобразуется в директивы схемы XML.

Приведенный выше пример кода делает следующее:

Объявление m_Status определяет XML-атрибут с именем status.
uxmlChildElementsDescription возвращает пустой IEnumerable, который указывает, что элемент StatusBar не имеет детей.
Член Init() считывает значение атрибута status в наборе свойств из синтаксического анализатора XML и устанавливает StatusBar.status в это значение.
Размещение класса UxmlTraits внутри класса StatusBar позволяет Init() для доступа к закрытым членам StatusBar.
Новый класс UxmlTraits наследуется от базового класса UxmlTraits, поэтому он разделяет атрибуты базового класса.
Init() вызывает base.Init() для инициализации свойств базового класса.

В приведенном выше примере кода строковый атрибут объявляется с помощью класса UxmlStringAttributeDescription. UI Toolkit поддерживает следующие типы атрибутов, каждый из которых связывает тип C# с типом XML:

Атрибут	Значение атрибута
`UxmlStringAttributeDescription`	Строка
`UxmlFloatAttributeDescription`	Значение с плавающей запятой одинарной точности в диапазоне типа C# `float`.
`UxmlDoubleAttributeDescription`	Значение с плавающей запятой двойной точности в диапазоне типа C# `double`.
`UxmlIntAttributeDescription`	Целочисленное значение в диапазоне типа C# `int`.
`UxmlLongAttributeDescription`	Длинное целочисленное значение в диапазоне типа C# `long`.
`UxmlBoolAttributeDescription`	`true` или `false`
`UxmlColorAttributeDescription`	Строка, представляющая цвет (`#FFFFFF`)
`UxmlEnumAttributeDescription`	Строка, представляющая одно из значений для `Enum` типа `T`.

В приведенном выше примере кода uxmlChildElementsDescription возвращает пустой IEnumerable, который указывает, что StatusBar не принимает дочерние элементы.

Чтобы элемент принимал дочерние элементы любого типа, необходимо переопределить свойство uxmlChildElementsDescription. Например, чтобы элемент StatusBar принимал дочерние элементы любого типа, свойство uxmlChildElementsDescription должно быть указано следующим образом:

public override IEnumerable uxmlChildElementsDescription
{
    get
    {
        yield return new UxmlChildElementDescription(typeof(VisualElement));
    }
}

Определение префикса пространства имен

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

Чтобы определить префикс пространства имен, добавьте в сборку атрибут UxmlNamespacePrefix для каждого префикса пространства имен, который вы хотите определить.


[assembly: UxmlNamespacePrefix("My.First.Namespace", "first")]
[assembly: UxmlNamespacePrefix("My.Second.Namespace", "second")]

Это можно сделать на корневом уровне (вне любого пространства имен) любого C#-файла сборки.

Система генерации схемы выполняет следующие действия:

Проверяет наличие этих атрибутов и использует их для создания схемы.
Добавляет определение префикса пространства имен в качестве атрибута элемента во вновь созданных файлах UXML.
Включает расположение файла схемы для пространства имен в свой атрибут xsi:schemaLocation.

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

Определенный префикс доступен во вновь созданном UXML, выбрав Создать > UI Toolkit > Окно редактора в папке Project/Assets/Editor.

Расширенное использование

Настройка имени UXML

Вы можете настроить имя UXML, переопределив его свойства IUxmlFactory.uxmlName и IUXmlFactory.uxmlQualifiedName. Убедитесь, что uxmlName уникально в вашем пространстве имен и что uxmlQualifiedName уникально в вашем проекте.

Если оба имени не уникальны, при попытке загрузить сборку возникает исключение.

В следующем примере кода показано, как переопределить и настроить имя UXML:

public class FactoryWithCustomName : UxmlFactory<..., ...>
{
    public override string uxmlName
    {
        get { return "UniqueName"; }
    }

    public override string uxmlQualifiedName
    {
        get { return uxmlNamespace + "." + uxmlName; }
    }
}

Выбор фабрики для элемента

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

Вы можете заставить процесс выбора учитывать значения атрибутов элемента, переопределив IUXmlFactory.AcceptsAttributeBag. Затем фабрика проверит атрибуты элемента, чтобы решить, может ли она создать экземпляр объекта для элемента UXML.

Это полезно, если ваш класс VisualElement является универсальным. В этом случае фабрика классов для специализации вашего класса может проверить значение XML-атрибута type. В зависимости от значения, создание экземпляра может быть принято или отклонено. В качестве примера см. реализацию PropertyControl.

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

Переопределение значения по умолчанию атрибута базового класса

Вы можете изменить значение по умолчанию для атрибута, объявленного в базовом классе, установив его defaultValue в производном классе UxmlTraits. .

Например, в следующем коде показано, как изменить значение по умолчанию m_TabIndex:

class MyElementTraits : VisualElement.UxmlTraits
    {
        public MyElementTraits()
        {
            m_TabIndex.defaultValue = 0;
        }
    }

Принятие любого атрибута

По умолчанию сгенерированная XML-схема указывает, что элемент может иметь любой атрибут.

Значения атрибутов, кроме объявленных в классе UxmlTraits, не ограничены. Это отличается от средств проверки XML, которые проверяют, соответствует ли значение объявленного атрибута его объявлению.

Дополнительные атрибуты включены в пакет IUxmlAttributes, который передается в IUxmlFactory.AcceptsAttributBag() и IUxmlFactory.Init(). Использование этих дополнительных атрибутов зависит от реализации фабрики. По умолчанию дополнительные атрибуты отбрасываются.

Это означает, что эти дополнительные атрибуты не привязаны к экземпляру VisualElement, и вы не можете запрашивать эти атрибуты с помощью UQuery.

При определении нового элемента вы можете ограничить допустимые атрибуты явно объявленными, установив для свойства UxmlTraits.canHaveAnyAttribute значение false в конструкторе UxmlTraits.

Использование определений схемы

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

В файле шаблона UXML атрибуты xsi:noNamespaceSchemaLocation и xsi:schemaLocation объекта указывает расположение файлов определения схемы.

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

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

Вы можете отблагодарить автора, за перевод документации на русский язык. ₽ Спасибо