Version: 2020.3
레이아웃 엔진
UXML 템플릿 작성

UXML 포맷

Unity Extensible Markup Language (UXML) files are text files that define the structure of the user interface. The UXML format is inspired by HTML, XAML, and XML. If you’ve worked with these formats before, you’ll find similarities with UXML. However, the UXML format includes small differences to provide an efficient way to work with Unity.

이 섹션에서는 Unity가 지원하는 UXML 포맷을 설명하고, UXML 템플릿을 작성, 로드 및 정의하는 방법에 대한 상세 정보를 제공합니다. 또한 새로운 요소를 정의하고 UQuery를 정의하는 방법도 함께 소개합니다.

UXML makes it easier for less technical users to build a user interface within Unity. In UXML you can:

  • 사용자 인터페이스(UI)의 구조를 XML로 정의합니다.
  • USS 스타일시트로 UI 레이아웃을 정의합니다.

이 경우 개발자들이 에셋 임포트, 로직 정의 및 데이터 처리 같은 기술 작업을 직접 수행해야 합니다.

Defining new elements

With UI Toolkit, you can define your own user interface components and elements.

UXML 파일을 사용하여 새로운 요소를 정의하기 전에 VisualElement 또는 해당 서브 클래스 중 하나에서 새로운 클래스를 파생한 후 새로운 클래스 안에 적절한 기능을 구현해야 합니다. 새로운 클래스는 반드시 기본 생성자를 구현해야 합니다.

예를 들어, 다음 코드는 새로운 StatusBar 클래스를 파생하고 해당 기본 생성자를 구현합니다.

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

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

In order for UI Toolkit to instantiate a new class when reading a UXML file, you must define a factory for your class. Unless your factory needs to do something special, you can derive the factory from UxmlFactoy<T>. It’s recommended that you put the factory class within your component class.

예를 들어 다음 코드는 UxmlFactory<T>에서 StatusBar 클래스의 팩토리를 파생하여 해당 클래스에 대한 팩토리를 정의하는 방법을 보여줍니다. 팩토리에는 UxmlFactory라는 이름이 지정됩니다.

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

    // ...
}

이 팩토리를 정의하고 나면 UXML 파일에서 <StatusBar> 요소를 사용할 수 있습니다.

요소에 대한 속성 정의

새로운 클래스에 대해 UXML 특성을 정의하고 해당 팩토리가 그러한 특성을 사용하도록 설정할 수 있습니다.

For example, the following code demonstrates how to define a UXML traits class to initialize the status property as a property of the StatusBar class. The status property initializes from XML data.

class StatusBar : VisualElement
{
    public new class UxmlFactory : UxmlFactory<StatusBar, UxmlTraits> {}

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

        public override IEnumerable<UxmlChildElementDescription> 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는 다음의 두 가지 역할을 수행합니다.

  • The factory uses it to initialize the newly created object.
  • The schema generation process analyzes it to get information about the element. This information translates into XML schema directives.

위 코드 예제는 다음을 수행합니다.

  • m_Status 선언은 status라는 이름의 XML 속성을 정의합니다.
  • uxmlChildElementsDescriptionStatusBar 요소에 자식이 없음을 의미하는 빈 IEnumerable을 반환합니다.
  • Init() 멤버는 XML 파서의 프로퍼티 백에 있는 status 속성의 값을 읽은 후 StatusBar.status 프로퍼티를 이 값으로 설정합니다.
  • UxmlTraits 클래스를 StatusBar 클래스 내부에 배치하여 Init() 메서드가 StatusBar의 프라이빗 멤버에 액세스하도록 허용합니다.
  • 새로운 UxmlTraits 클래스는 UxmlTraits 기본 클래스에서 상속되기 때문에 기본 클래스의 속성을 공유합니다.
  • Init()base.Init()를 호출하여 기본 클래스 프로퍼티를 초기화합니다.

The code example above declares a string attribute with the UxmlStringAttributeDescription class. UI Toolkit supports the following types of attributes and each links a C# type to an XML type:

속성 속성 값
UxmlStringAttributeDescription 문자열입니다.
UxmlFloatAttributeDescription C# float 타입의 범위 내에 있는 단일 정밀도 부동 소수점 값입니다.
UxmlDoubleAttributeDescription C# double 타입의 범위 내에 있는 이중 정밀도 부동 소수점 값입니다.
UxmlIntAttributeDescription C# int 타입의 범위 내에 있는 정수 값입니다.
UxmlLongAttributeDescription C# long 타입의 범위 내에 있는 긴 정수 값입니다.
UxmlBoolAttributeDescription true 또는 false입니다.
UxmlColorAttributeDescription 컬러를 나타내는 문자열(#FFFFFF)입니다.
UxmlEnumAttributeDescription<T> Enum 타입 T에 대한 값 중 하나를 나타내는 문자열입니다.

위 코드 예제에서 uxmlChildElementsDescription은 빈 IEnumerable을 반환하며, 이는 StatusBar 요소가 자식을 허용하지 않음을 의미합니다.

To have an element accept children of any type, you must override the uxmlChildElementsDescription property. For example, for the StatusBar element to accept children of any type, the uxmlChildElementsDescription property must be specified as follows:

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

네임스페이스 접두사 정의

C#으로 새 요소를 정의하고 나면 UXML 파일에서 해당 요소를 사용할 수 있습니다. 새 요소가 새로운 네임스페이스로 정의된 경우 해당 네임스페이스에 대한 접두사를 정의해야 합니다. 네임스페이스 접두사는 속성으로 루트 <UXML> 요소에 대해 선언되고, 요소 범위 지정 시 전체 네임스페이스 이름을 대체합니다.

네임스페이스 접두사를 정의하려면 UxmlNamespacePrefix` 속성을 정의하려는 각 네임스페이스 접두사의 어셈블리에 추가하십시오.


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

You can do this at the root level (outside any namespace) of any C# file of the assembly.

이 스키마 생성 시스템은 다음을 수행합니다.

  • Checks for these attributes and uses them to generate the schema.
  • Adds the namespace prefix definition as an attribute of the <UXML> element in newly created UXML files
  • Includes the schema file location for the namespace in its xsi:schemaLocation attribute.

You should update the UXML schema of your project. Select Assets > Update UXML Schema to ensure that your text editor recognizes the new element.

The defined prefix is available in the newly created UXML by selecting Create > UI Toolkit > Editor Window in the Project/Assets/Editor folder.

고급 사용

UXML 이름 커스터마이즈

IUxmlFactory.uxmlNameIUXmlFactory.uxmlQualifiedName 프로퍼티를 오버라이드하여 UXML 이름을 커스터마이즈할 수 있습니다. uxmlName이 네임스페이스 내에서 고유한 이름이고, uxmlQualifiedName이 프로젝트 내에서 고유한 이름이어야 합니다.

If both names aren’t unique, an exception is thrown when you attempt to load your assembly.

다음 코드 예제는 UXML 이름을 오버라이드하고 커스터마이즈하는 방법을 보여줍니다.

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

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

요소에 대한 팩토리 선택

기본적으로 IUxmlFactory는 요소를 인스턴스화하고, 요소 이름을 사용하여 요소를 선택합니다.

IUXmlFactory.AcceptsAttributeBag을 오버라이드하여 선택 프로세스가 요소의 속성 값을 고려하도록 만들 수 있습니다. 그러면 팩토리는 요소 속성을 검사하여 UXML 요소의 오브젝트를 인스턴스화할 수 있는지 결정합니다.

This is useful if your VisualElement class is generic. In this case, the class factory for a specialization of your class could examine the value of a XML type attribute. Depending on the value, instantiation can be accepted or refused. For an example, see the implemenatation of PropertyControl<T>.

두 개 이상의 팩토리가 요소를 인스턴스화할 수 있는 경우에는 첫 번째로 등록된 팩토리가 선택됩니다.

기본 클래스 속성의 기본 값 오버라이드

파생된 UxmlTraits 클래스에서 defaultValue를 설정하여 기본 클래스에서 선언된 속성의 기본 값을 변경할 수 있습니다.

예를 들어 다음 코드는 m_TabIndex의 기본값을 변경하는 방법을 보여줍니다.

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

속성 허용

기본적으로 생성된 XML 스키마는 요소가 모든 속성을 가질 수 있다고 명시합니다.

UxmlTraits 클래스에서 선언된 속성을 제외한 속성 값은 제한되지 않습니다. 이는 선언된 속성의 값이 해당 선언과 일치하는지 확인하는 XML 검증기와 대조됩니다.

Additional attributes are included in the IUxmlAttributes bag that’s passed to the IUxmlFactory.AcceptsAttributBag() and IUxmlFactory.Init() functions. It’s up to the factory implementation to use these additional attributes. The default behavior is to discard additional attributes.

This means that these additional attributes aren’t attached to the instantiated VisualElement and you cannot query these attributes with UQuery.

새 요소를 정의할 때 UxmlTraits 생성자에서 UxmlTraits.canHaveAnyAttribute 프로퍼티를 false로 설정하여 허용되는 속성을 명시적으로 선언된 속성으로만 제한할 수 있습니다.

Using Schema definitions

스키마 정의 파일은 속성, 그리고 각 UXML 요소가 포함할 수 있는 자식 요소를 지정합니다. 스키마 정의 파일을 가이드로 사용하여 올바른 문서를 작성하고 문서의 유효성을 확인하십시오.

In the UXML template file, the xsi:noNamespaceSchemaLocation and xsi:schemaLocation attributes of the <UXML> root element specify the location of the schema definition files.

Select Assets > Create > UI Toolkit > Editor Window to automatically update your schema definition with the latest information from the VisualElement sub-classes used by your project. To force an update of the UXML schema files, select Assets > Update UXML Schema.

Note: Some text editors don’t recognize the xsi:noNamespaceSchemaLocation attribute. If your text editor can’t find the schema definition files, you should also specify the xsi:schemaLocation attribute.

레이아웃 엔진
UXML 템플릿 작성