Version: 2023.1
언어: 한국어
커스텀 컨트롤 만들기
UXML 태그 이름 및 속성 커스터마이즈

UXML 및 UI 빌더에 커스텀 컨트롤 노출

UXML 및 UI 빌더에서 커스텀 컨트롤을 사용하려면 노출시켜야 합니다.

팩토리 정의

새 요소를 정의하려면 VisualElement 또는 그 서브 클래스 중 하나에서 새 클래스를 파생한 다음 이 새 클래스 내에서 적절한 기능을 구현합니다.

새 클래스는 기본 생성자를 구현해야 합니다.예제:

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

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

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

예를 들어 다음 코드 스니핏은 StatusBar 클래스에 대해 UxmlFactory라는 팩토리를 정의합니다.

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

    // ...
}

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

요소에 대한 속성 정의

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

예를 들어 다음 코드 스니핏은 UXML 특성 클래스를 정의하여 status 프로퍼티를 StatusBar 클래스의 프로퍼티로 초기화하는 방법을 보여줍니다 상태 프로퍼티는 UXML 데이터에서 초기화됩니다.

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 프로퍼티를 이 값으로 설정합니다.
  • UxmlTraits 클래스는 StatusBar 클래스 안에 배치됩니다.이렇게 하면 Init() 메서드가 StatusBar의 프라이빗 멤버에 액세스할 수 있습니다.
  • 새로운 UxmlTraits 클래스는 UxmlTraits 기본 클래스에서 상속되기 때문에 기본 클래스의 속성을 공유합니다.
  • Init()base.Init()를 호출하여 기본 클래스 프로퍼티를 초기화합니다.

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

속성 속성 값
UxmlStringAttributeDescription 문자열입니다.
UxmlFloatAttributeDescription C# float 타입의 범위 내에 있는 단일 정밀도 부동 소수점 값입니다.
UxmlDoubleAttributeDescription C# double 타입의 범위 내에 있는 이중 정밀도 부동 소수점 값입니다.
UxmlIntAttributeDescription C# int 타입의 범위 내에 있는 정수 값입니다.
UxmlLongAttributeDescription C# long 타입의 범위 내에 있는 긴 정수 값입니다.
UxmlBoolAttributeDescription true 또는 false입니다.
UxmlColorAttributeDescription USS 포맷으로 정의된 컬러를 나타내는 문자열입니다.
UxmlEnumAttributeDescription<T> Enum 타입 T에 대한 값 중 하나를 나타내는 문자열입니다.
UxmlTypeAttributeDescription<T> 타입의 어셈블리 자격 이름을 나타내는 문자열입니다.
UxmlAssetAttributeDescription<T> A string that represents an asset.

위 코드 예제에서 uxmlChildElementsDescriptionStatusBar 요소가 XML 스키마에 대한 자식 요소 설명을 허용하지 않음을 나타내는 빈 IEnumerable을 반환합니다.

요소가 모든 타입의 자식을 허용하도록 만들려면 uxmlChildElementsDescription 프로퍼티를 오버라이드해야 합니다.예를 들어 StatusBar 요소가 모든 타입의 자식을 허용하려면 uxmlChildElementsDescription 프로퍼티를 다음과 같이 지정해야 합니다.

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")]

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

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

  • 이러한 속성에 대한 검사를 수행하고, 속성을 사용하여 스키마를 생성합니다.
  • 네임스페이스 접두사 정의를 새로 생성된 UXML 파일에 있는 <UXML> 요소의 속성으로 추가합니다..
  • xsi:schemaLocation 속성의 네임스페이스에 대한 스키마 파일 위치를 포함합니다.

텍스트 에디터가 새 요소를 인식하는지 확인하려면 Assets > Update UXML Schema를 선택하여 스키마 정의를 업데이트합니다.

접두사가 있는 새 UXML 문서를 생성하려면 Assets > Create > UI Toolkit > UI Document를 선택합니다.

추가 리소스

커스텀 컨트롤 만들기
UXML 태그 이름 및 속성 커스터마이즈