Version: 2022.3
언어: 한국어
Create a custom control
Customize UXML tag names and attributes

Expose custom control to UXML and UI Builder

To use custom controls with UXML and UI Builder, you must expose them.

Define a factory

To define new elements, derive a new class from VisualElement or one of its subclasses, and then implement the appropriate functionality within this new class.

Your new class must implement a default constructor. For example:

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 it reads 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 UxmlFactory<T>. It’s recommended that you put the factory class within your component class.

For example, the following code snippet define a factory named UxmlFactory for the StatusBar class:

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

    // ...
}

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

Define attributes on elements

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

For example, the following code snippet defines a UXML traits class to initialize the status property as a property of the StatusBar class. The status property initializes from UXML 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는 다음의 두 가지 역할을 수행합니다.

  • 팩토리가 새로 생성된 오브젝트를 초기화하는 데 사용합니다.
  • 스키마 생성 프로세스가 요소에 대한 정보를 가져오기 위해 분석합니다. 이 정보는 XML 스키마 지시문으로 변환됩니다.

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

  • m_Status 선언은 status라는 이름의 XML 속성을 정의합니다.
  • uxmlChildElementsDescriptionStatusBar 요소에 자식이 없음을 의미하는 빈 IEnumerable을 반환합니다.
  • Init() 멤버는 XML 파서의 프로퍼티 백에 있는 status 속성의 값을 읽은 후 StatusBar.status 프로퍼티를 이 값으로 설정합니다.
  • The UxmlTraits class is placed inside the StatusBar class. This allows the Init() method to access the private members of 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 a UMXL type:

속성 속성 값
UxmlStringAttributeDescription 문자열입니다.
UxmlFloatAttributeDescription C# float 타입의 범위 내에 있는 단일 정밀도 부동 소수점 값입니다.
UxmlDoubleAttributeDescription C# double 타입의 범위 내에 있는 이중 정밀도 부동 소수점 값입니다.
UxmlIntAttributeDescription C# int 타입의 범위 내에 있는 정수 값입니다.
UxmlLongAttributeDescription C# long 타입의 범위 내에 있는 긴 정수 값입니다.
UxmlBoolAttributeDescription true 또는 false입니다.
UxmlColorAttributeDescription A string that represents a color defined in USS format.
UxmlEnumAttributeDescription<T> A string that represents one of the values for the Enum type T.
UxmlTypeAttributeDescription<T> A string that represents the assembly-qualified name of the type.

In the code example above, the uxmlChildElementsDescription returns an empty IEnumerable which indicates that the StatusBar element doesn’t accept child element descriptions to the XML schema.

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, you must specify the uxmlChildElementsDescription property as follows:

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

Define a namespace prefix

Once you have defined a new element in C#, you can use the element in your UXML files. To categorize elements, create your class in a namespace. When you define a new namespace, you can define a prefix for the namespace. You must define namespace prefixes as attributes of the root <UXML> element and replace the full namespace name when scoping elements.

To define a namespace prefix, add a UxmlNamespacePrefix attribute to your assembly for each namespace prefix. For example:

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

이 작업은 어셈블리 C# 파일의 루트 수준(모든 네임스페이스 외부)에서 수행할 수 있습니다.

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

  • 이러한 속성에 대한 검사를 수행하고, 속성을 사용하여 스키마를 생성합니다.
  • Adds the namespace prefix definition as an attribute of the <UXML> element in newly created UXML files.
  • xsi:schemaLocation 속성의 네임스페이스에 대한 스키마 파일 위치를 포함합니다.

To ensure that your text editor recognizes the new element, select Assets > Update UXML Schema to update the schema definition.

To create a new UXML document with the prefix, select Assets > Create > UI Toolkit > UI Document.

추가 리소스

Create a custom control
Customize UXML tag names and attributes
Copyright © 2023 Unity Technologies
优美缔软件(上海)有限公司 版权所有
"Unity"、Unity 徽标及其他 Unity 商标是 Unity Technologies 或其附属机构在美国及其他地区的商标或注册商标。其他名称或品牌是其各自所有者的商标。
公安部备案号:
31010902002961