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; }
}

UXML 파일을 읽을 때 UI 툴킷이 새로운 클래스를 인스턴스화하도록 만들려면 클래스에 대해 팩토리를 정의해야 합니다. 팩토리가 특별한 작업을 할 필요가 없는 경우에는 UxmlFactoy<T>에서 팩토리를 파생할 수 있습니다. 또한 팩토리 클래스는 컴포넌트 클래스 안에 배치하는 것이 좋습니다.

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

위 코드 예제는 UxmlStringAttributeDescription 클래스로 문자열 속성을 선언합니다. UI 툴킷은 다음 타입의 속성을 지원하며 각각 C# 타입을 XML 타입에 연결합니다.

속성	속성 값
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.

프로젝트의 UXML 스키마를 업데이트해야 합니다. Assets > Update UXML Schema를 선택하여 텍스트 편집기가 새 요소를 인식하는지 확인하십시오.

정의된 접두사는 Project/Assets/Editor 폴더에서 Create > UI Toolkit > Editor Window를 선택하여 새로 생성된 UXML에서 이용할 수 있습니다.

고급 사용

UXML 이름 커스터마이즈

IUxmlFactory.uxmlName 및 IUXmlFactory.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.

Assets > Create > UI Toolkit > Editor Window를 선택하여 프로젝트에서 사용하는 VisualElement 서브 클래스에서 얻은 최신 정보로 스키마 정의를 자동으로 업데이트하십시오. UXML 스키마 파일을 강제로 업데이트하려면 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.