커스텀 컨트롤 만들기

커스텀 컨트롤을 만들려면 커스텀 컨트롤 C# 클래스를 생성하고 초기화해야 합니다.UXML 및 UI 빌더에서 사용할 수 있도록 노출할 수 있습니다.데이터에 바인딩할 수도 있습니다.

커스텀 컨트롤 클래스 만들기

VisualElement 클래스 또는 VisualElement 클래스의 하위 클래스에서 파생된 C# 클래스를 생성합니다.예를 들어, BindableElement대신 BaseField 의 일반 기본 클래스에서 파생된 바인딩 가능한 커스텀 컨트롤을 만들 수 있습니다.이것은 다음과 같은 이점이 있습니다.

• 지정한 일반 파라미터 타입에 대해 InotifyValueChanged 인터페이스 구현
• 기본적으로 컨트롤에 초점을 맞출 수 있도록 설정
• 왼쪽에 레이블 요소가 있고 오른쪽에 입력이 있는 가로 레이아웃 제공

참고:내부 계층 구조와 기존 USS 클래스를 이해한다면 빌트인 UI 컨트롤에서 파생된 커스텀 컨트롤을 만들 수 있습니다.커스텀 컨트롤은 향후 변경될 수 있는 내부 구조에 따라 달라질 수 있으므로 Unity는 이러한 관행을 권장하지 않습니다.

커스텀 컨트롤 초기화

커스텀 컨트롤은 VisualElement에서 상속됩니다.VisualElement는 게임 오브젝트의 수명에 바인딩되지 않으며, 다음 콜백을 수신하지 않습니다.

• Awake()
• OnEnable()
• OnDisable()
• OnDestroy()

생성자에서 커스텀 컨트롤을 초기화할 수 있습니다.그러나 애플리케이션에 필요한 경우 커스텀 컨트롤이 UI에 추가될 때까지 초기화를 지연시킬 수 있습니다.이렇게 하려면 AttachToPanelEvent에 대한 콜백을 등록합니다.UI에서 커스텀 컨트롤이 제거되었는지 감지하려면 DetachFromPanelEvent 콜백을 사용합니다.

public CustomControl()
{
    var myCustomElement = rootVisualElement.Q(className: "my-custom-element");
    myCustomElement.RegisterCallback<AttachToPanelEvent>(e =>
        { /* do something here when element is added to UI */ });
    myCustomElement.RegisterCallback<DetachFromPanelEvent>(e =>
        { /* do something here when element is removed from UI */ });
}

UI 툴킷은 모든 요소에 대해 이 두 이벤트를 디스패치하며 커스텀 VisualElement 서브 클래스가 필요하지 않습니다.자세한 내용은 패널 이벤트를 참조하십시오.

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

커스텀 컨트롤을 UXML 및 UI 빌더에서 사용하려면 해당 컨트롤을 노출해야 합니다.커스텀 컨트롤을 노출하려면 UxmlFactory<T>에서 파생된 팩토리 클래스를 정의합니다.

커스텀 컨트롤에 새 속성을 추가하여 UXML에서 사용할 수 있습니다.커스텀 컨트롤에 새 속성을 추가하려면 요소에서 속성 정의에 설명된 대로 UxmlTraits에서 파생된 특성 클래스를 정의하고 Init() 메서드를 오버라이드하십시오.UI 빌더는 이것을 사용하여 인스펙터에서 UXML 프로퍼티 값을 변경할 때 뷰포트용으로 생성된 시각적 요소가 업데이트되게 합니다.

UI 빌더의 인스펙터에서 커스텀 컨트롤의 UXML 프로퍼티를 사용하려면 UXML과 C# 스크립트 간에 프로퍼티 이름을 일치시켜야 합니다.UXML에 대해 표준 케밥 케이스 표기법을 사용하고, C#에 대해 카멜 케이스 또는 파스칼 케이스를 사용합니다.예를 들어, C#에서 MyFloat 또는 myFloat라는 프로퍼티는 UXML에서는 my-float가 되어야 합니다.

데이터에 커스텀 컨트롤 바인딩

커스텀 컨트롤을 직렬화된 프로퍼티에 바인딩하여 컨트롤과 프로퍼티 간의 값을 동기화할 수 있습니다.

커스텀 컨트롤을 데이터에 바인딩하려면:

• 필요에 따라 INotifyValueChanged 인터페이스를 구현하고 ChangeEvent를 수신 대기합니다.
• BindableElement](../ScriptReference/UIElements.BindableElement.html) 클래스에서 상속하거나 IBindable 인터페이스를 구현합니다.

자세한 내용은 SerializedObject 데이터 바인딩을 참조하십시오.

바인딩 가능한 커스텀 컨트롤의 예는 바인딩 가능한 커스텀 컨트롤 만들기를 참조하십시오.

USS로 커스텀 컨트롤 스타일링

USS를 사용하여 빌트인 컨트롤과 동일한 방식으로 커스텀 컨트롤의 모양을 커스터마이즈할 수 있습니다.커스텀 컨트롤의 스타일을 지정하기 위해 USS 커스텀 프로퍼티를 생성할 수도 있습니다.

참고:UI 빌더의 인스펙터 창에 USS 커스텀 프로퍼티가 표시되지 않습니다.USS 커스텀 프로퍼티를 편집하려면 텍스트 에디터를 사용하여 USS 파일을 직접 편집합니다.

C#에서 커스텀 컨트롤의 커스텀 USS 프로퍼티와 상호 작용하려면 CustomStyleProperty 구조체와 CustomStylesResolvedEvent 이벤트를 사용하십시오.

CustomStyleProperty는 스타일시트에서 읽은 프로퍼티의 이름과 타입을 설명합니다.

UI 툴킷은 커스텀 USS 프로퍼티를 직접 수신하는 모든 요소에 대해 CustomStylesResolvedEvent를 디스패치합니다.선택자가 일치하는 모든 요소, 규칙에 커스텀 프로퍼티 값이 포함된 선택자에 대해 이벤트를 디스패치합니다.UI 툴킷은 값을 상속하는 요소에 대해서는 이벤트를 디스패치하지 않습니다.이벤트는 ICustomStyle 오브젝트에 대한 레퍼런스를 보유합니다.CustomStyleProperty의 유효 값을 읽으려면 TryGetValue() 메서드를 사용해야 합니다.이 메서드에는 다양한 타입의 CustomStyleProperty에 대한 오버로드가 있습니다.

커스텀 컨트롤 예제가 포함된 커스텀 스타일은 커스텀 컨트롤에 대한 커스텀 스타일 만들기를 참조하십시오.

참고:커스텀 스타일 프로퍼티에 대한 전환을 정의할 수 없습니다.

커스텀 컨트롤 이벤트 처리

커스텀 컨트롤의 이벤트 처리 방법에 대한 자세한 내용은 이벤트 처리를 참조하십시오.

참고:

• Unity는 현재 초점이 맞춰진 요소에 키보드 이벤트를 디스패치합니다.커스텀 컨트롤에 대한 키보드 이벤트를 처리하려면 ’focus’와 관련된 프로퍼티를 설정합니다.
• 터치 및 마우스 입력 이벤트를 처리하려면 생성자에 포인터 이벤트 및 마우스 이벤트 등 관련 이벤트 유형에 대한 콜백을 등록합니다.

UI 빌더에서 커스텀 컨트롤 사용

UI 빌더에서 시각적 트리에 커스텀 컨트롤을 추가하려면:

1. Library > Project > Custom Controls (C#)를 선택합니다.
2. 커스텀 컨트롤을 계층(Hierarchy) 창으로 드래그합니다.

베스트 프랙티스와 팁

베스트 프랙티스:

• 커스텀 컨트롤이 나타내는 프로퍼티 및 동작의 기타 기능적 측면을 UXML 프로퍼티로 노출하고, 커스텀 컨트롤의 모양에 영향을 주는 프로퍼티를 USS 프로퍼티로 노출합니다.
• 다른 요소와의 이름 충돌을 피하려면 고유하고 짧고 읽기 쉬운 네임스페이스를 사용하십시오.
• UXML 속성을 기본으로 유지합니다.UXML에서 지정할 수 있는 데이터는 기본 데이터 형식 집합으로 제한됩니다.UXML은 복잡한 데이터 구조나 컬렉션을 지원하지 않습니다.런타임에 복잡한 데이터를 UXML이 아닌 C# 스크립트 또는 데이터 바인딩을 통해 커스텀 컨트롤에 전달하십시오.
• C#에서는 USS 클래스 또는 이름을 상수로 노출합니다.이를 통해 UQuery를 사용하여 클래스 또는 이름별로 요소를 찾을 수 있습니다.
• USS 클래스에 BEM 표준을 채택합니다.이를 통해 클래스 리스트 선택자를 사용하여 모든 요소를 지정할 수 있습니다.
• 메모리 사용량을 줄이려면 정적 콜백을 사용하십시오.콜백으로 사용할 인스턴스 메서드를 등록할 때 불필요한 할당을 생성할 수 있습니다.할당을 피하려면 일반 C# 정적 메서드로 호출하는 익명의 정적 람다 함수를 사용하십시오.현재 요소의 컨텍스트는 EventBase.currentTarget 프로퍼티를 통해 검색할 수 있습니다.

팁:

• 커스텀 컨트롤에 대한 generateVisualContent 콜백을 통해 커스텀 지오메트리를 렌더링합니다.부분적으로 채워진 원을 렌더링하는 예제 사용법은 RadialProgress 예제를 참조하십시오.

• 커스텀 컨트롤은 편리합니다.그러나 다음과 같은 방법으로도 동일한 결과를 얻을 수 있습니다.

  • 기존 요소로 UI를 어셈블하고 스타일과 프로퍼티를 변경할 수 있습니다.
  • UXML 템플릿을 사용합니다.일반 C# ’MonoBehaviour'를 사용하여 UI를 담고 있는 특정 UI 문서와 관련된 로직을 추가하십시오.(MonoBehaviour를 사용하여 UI 문서에서 UI를 제어하는 방법을 알아보려면 [첫 번째 런타임 UI 만들기](UIE-HowTo-CreateRuntimeUI.html)를 참조하십시오).캡슐화를 달성하려면MonoBehaviour내부에 [UQuery](UIE-UQuery.html)로 [VisualElement`](../ScriptReference/UIElements.VisualElement.html)를 내부적으로 가져오고 해당 프로퍼티를 조작하는 프로퍼티와 메서드를 생성하십시오.

추가 리소스

• 커스텀 컨트롤을 UXML 및 UI 빌더에 노출
• 두 가지 속성을 가진 커스텀 컨트롤 만들기
• 슬라이드 토글 커스텀 컨트롤 만들기
• 방사형 진행률 표시기 만들기
• 바인딩 가능한 커스텀 컨트롤 만들기
• 커스텀 컨트롤에 대한 커스텀 스타일 만들기