Introduction to UI Toolkit

UI 빌더

UI 툴킷 시작하기

UI 툴킷으로 첫 번째 UI를 만들고 싶으신가요? 이 기본__ UI__(사용자 인터페이스) 사용자가 애플리케이션과 상호 작용하도록 해 줍니다. Unity는 현재 3개의 UI 시스템을 지원합니다. 자세한 정보
See in Glossary 툴킷 워크플로 예시로 시작하는 것을 추천드립니다.

참고: 데모 목적인 이 가이드에서는 에디터 UI의 UI 컨트롤을 추가하는 방법을 설명합니다. 하지만 UI 문서에 UI 컨트롤을 추가하는 지침은 런타임 UI에도 적용됩니다. 자세한 내용은 런타임 UI 시작하기를 참조하십시오.

특정 작업을 자주 수행하는 경우 UI 툴킷을 사용하여 해당 작업에 대한 전용 UI를 만들 수 있습니다. 예를 들어 커스텀 에디터 창을 생성할 수 있습니다. 이 예시는 커스텀 에디터 창을 생성하고 UI 빌더, UXML, C# 스크립트를 사용하여 커스텀 에디터 창에 UI 컨트롤을 추가하는 방법을 보여 줍니다.

이 예시에서 만든 완성된 파일은 이 GitHub 저장소에서 찾을 수 있습니다.

커스텀 에디터 창 생성

두 개의 레이블이 있는 커스텀 에디터 창을 생성합니다.

임의의 템플릿을 사용하여 Unity 에디터에서 프로젝트를 생성합니다.
프로젝트 창에서 Assets 폴더를 오른쪽 클릭하고 Create > UI Toolkit > Editor Window를 선택합니다.
UI Toolkit Editor Window Creator에서 C# 상자에 SimpleCustomEditor를 입력합니다.
UXML 체크박스를 선택하고 USS 체크박스를 선택 해제합니다.
Confirm을 선택합니다.
에디터 창을 열려면 Window > UI Toolkit > SimpleCustomEditor를 선택합니다.

Assets/Editor 폴더에서 소스 파일을 찾을 수 있습니다.

창에 UI 컨트롤 추가

다음과 같은 방법으로 창에 UI 컨트롤을 추가할 수 있습니다.

UI 빌더를 사용하여 시각적으로 UI 요소 추가
XML 같은 텍스트 파일(UXML)을 사용하여 UI 컨트롤 추가
C# 스크립트를 사용하여 UI 컨트롤 추가

이러한 방법을 개별적으로 사용하거나 조합하여 사용할 수 있습니다. 다음 예시에서는 이러한 방법을 조합하여 레이블, 버튼, 토글 세 가지를 세트로 만듭니다.

UI 빌더를 사용하여 UI 컨트롤 추가

창에 UI 컨트롤을 시각적으로 추가하려면 UI 빌더를 사용하십시오. 다음 단계에서는 기본 레이블 외에 커스텀 에디터 창에 버튼과 토글을 추가합니다.

Editor 폴더에서 SimpleCustomEditor.uxml을 더블 클릭하여 UI 빌더를 엽니다.
UI 빌더에서 Library > Controls의 Button 및 Toggle을 Hierarchy 또는 Viewport의 창 미리 보기로 드래그합니다.
계층 창에서 Label을 선택합니다.
인스펙터 창에서 Text 필드의 기본 텍스트를 These controls were created in UI Builder로 변경합니다.
계층 창에서 Button을 선택합니다.
인스펙터 창에서 Text 필드에 This is button1을 입력합니다.
Name 필드에 button1을 입력합니다.
계층 창에서 Toggle을 선택합니다.
인스펙터 창에서 Label 필드에 Number?를 입력합니다.
Name 필드에 toggle1을 입력합니다.
저장한 후 UI Builder 창을 닫습니다.
아직 커스텀 에디터 창을 닫지 않았다면 닫습니다.
프로젝트 창에서 SimpleCustomEditor.cs를 선택하고 인스펙터 창에서 Visual Tree Asset이 SimpleCustomEditor (Visual Tree Asset)로 설정되었는지 확인합니다.
Window > UI Toolkit > SimpleCustomEditor를 선택하여 커스텀 에디터 창을 다시 열면 방금 추가한 버튼과 토글을 확인할 수 있습니다.

UXML을 사용하여 UI 컨트롤 추가

텍스트 파일로 UI를 정의하는 것을 선호하는 경우 UXML을 편집하여 UI 컨트롤을 추가할 수 있습니다. 다음 단계에서는 창에 또 다른 레이블, 버튼, 토글 세트를 추가합니다.

Editor 폴더에서 Assets > Create > UI Toolkit > UI Document를 선택하여 SimpleCustomEditor_UXML.uxml이라는 UXML 파일을 생성합니다.
프로젝트 창에서 SimpleCustomEditor_UXML.uxml의 화살표를 선택합니다.
inlineStyle을 더블 클릭하여 텍스트 편집기에서 SimpleCustomEditor_UXML.uxml을 엽니다.
SimpleCustomEditor_uxml.uxml의 내용을 다음으로 바꿉니다.

   <ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements" xsi="http://www.w3.org/2001/XMLSchema-instance" engine="UnityEngine.UIElements" editor="UnityEditor.UIElements" noNamespaceSchemaLocation="../../UIElementsSchema/UIElements.xsd" editor-extension-mode="False">
       <ui:Label text="These controls were created with UXML." />
       <ui:Button text="This is button2" name="button2"/>
       <ui:Toggle label="Number?" name="toggle2"/>
   </ui:UXML>

SimpleCustomEditor.cs를 엽니다.

다음을 CreateGUI 메서드에 추가하여 수동으로 생성한 UXML 파일을 임포트합니다.

// Import UXML created manually.
var visualTree = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>("Assets/Editor/SimpleCustomEditor_uxml.uxml");
VisualElement labelFromUXML_uxml = visualTree.Instantiate();
root.Add(labelFromUXML_uxml);

변경 사항을 저장합니다.
Window > UI Toolkit > SimpleCustomEditor를 선택합니다. 그러면 레이블 3개, 버튼 2개, 토글 2개가 있는 커스텀 에디터 창이 열립니다.

C# 스크립트를 사용하여 UI 컨트롤 추가

코딩을 선호하는 경우 C# 스크립트를 사용하여 창에 UI 컨트롤을 추가할 수 있습니다. 다음 단계에서는 창에 또 다른 레이블, 버튼, 토글 세트를 추가합니다.

SimpleCustomEditor.cs를 엽니다.
Unity는 레이블, 버튼, 토글 같은 기본 UI 컨트롤에 UnityEngine.UIElements를 사용합니다. UI 컨트롤을 사용하려면 다음 선언을 추가해야 합니다(아직 없는 경우).
```
using UnityEngine.UIElements;
```
기존 레이블의 텍스트를 "Hello World! From C#"에서 "These controls were created using C# code."로 변경합니다.

EditorWindow 클래스에는 rootVisualElement라는 프로퍼티가 있습니다. 창에 UI 컨트롤을 추가하려면 먼저 일부 속성을 사용하여 요소 클래스를 인스턴스화한 후 rootVisualElement의 Add 메서드를 사용합니다.

완성된 CreateGUI() 메서드는 다음과 같습니다.

public void CreateGUI()
{
    // Each editor window contains a root VisualElement object
    VisualElement root = rootVisualElement;

    // VisualElements objects can contain other VisualElements following a tree hierarchy.
    Label label = new Label("These controls were created using C# code.");
    root.Add(label);

    Button button = new Button();
    button.name = "button3";
    button.text = "This is button3.";
    root.Add(button);

    Toggle toggle = new Toggle();
    toggle.name = "toggle3";
    toggle.label = "Number?";
    root.Add(toggle);

    // Instantiate UXML created automatically which is set as the default VisualTreeAsset.
    root.Add(m_UXMLTree.Instantiate());

    // Import UXML created manually.
    var visualTree = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>("Assets/Editor/SimpleCustomEditor_uxml.uxml");
    VisualElement labelFromUXML_uxml = visualTree.Instantiate();
    root.Add(labelFromUXML_uxml);
}

Window > UI Toolkit > SimpleCustomEditor를 선택하여 커스텀 에디터 창을 다시 열면 레이블 3개, 버튼 3개, 토글 3개가 표시됩니다.

UI 컨트롤의 동작 정의

버튼을 클릭하고 토글을 선택하거나 선택을 취소하면 UI 컨트롤이 일부 작업을 수행하도록 UI 컨트롤에 대한 이벤트 핸들러를 설정할 수 있습니다.

이 예시에서는 다음과 같은 이벤트 핸들러를 설정합니다.

버튼을 클릭했을 때 에디터 콘솔에 메시지가 표시됩니다.
토글을 선택했을 때 콘솔에 버튼이 클릭된 횟수가 표시됩니다.

완료된 SimpleCustomEditor.cs는 다음과 같습니다.

using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;

public class SimpleCustomEditor : EditorWindow
{
    [SerializeField]
    private VisualTreeAsset m_VisualTreeAsset = default;

    [MenuItem("Window/UI Toolkit/SimpleCustomEditor")]
    public static void ShowExample()
    {
        SimpleCustomEditor wnd = GetWindow<SimpleCustomEditor>();
        wnd.titleContent = new GUIContent("SimpleCustomEditor");
    }

    private int m_ClickCount = 0;

    private const string m_ButtonPrefix = "button";

    public void CreateGUI()
    {
        // Each editor window contains a root VisualElement object
        VisualElement root = rootVisualElement;

        // VisualElements objects can contain other VisualElement following a tree hierarchy.
        Label label = new Label("These controls were created using C# code.");
        root.Add(label);

        Button button = new Button();
        button.name = "button3";
        button.text = "This is button3.";
        root.Add(button);

        Toggle toggle = new Toggle();
        toggle.name = "toggle3";
        toggle.label = "Number?";
        root.Add(toggle);

        // Instantiate UXML created automatically which is set as the default VisualTreeAsset.
        root.Add(m_VisualTreeAsset.Instantiate());

        // Import UXML created manually.
        var visualTree = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>("Assets/Editor/SimpleCustomEditor_uxml.uxml");
        VisualElement labelFromUXML = visualTree.Instantiate();
        root.Add(labelFromUXML);

        //Call the event handler
        SetupButtonHandler();
    }

    //Functions as the event handlers for your button click and number counts
    private void SetupButtonHandler()
    {
        VisualElement root = rootVisualElement;

        var buttons = root.Query<Button>();
        buttons.ForEach(RegisterHandler);
    }

    private void RegisterHandler(Button button)
    {
        button.RegisterCallback<ClickEvent>(PrintClickMessage);
    }

    private void PrintClickMessage(ClickEvent evt)
    {
        VisualElement root = rootVisualElement;

        ++m_ClickCount;

        //Because of the names we gave the buttons and toggles, we can use the
        //button name to find the toggle name.
        Button button = evt.currentTarget as Button;
        string buttonNumber = button.name.Substring(m_ButtonPrefix.Length);
        string toggleName = "toggle" + buttonNumber;
        Toggle toggle = root.Q<Toggle>(toggleName);

        Debug.Log("Button was clicked!" +
            (toggle.value ? " Count: " + m_ClickCount : ""));
    }
}

예제 테스트

메뉴에서 Window > UI Toolkit > SimpleCustomEditor를 선택합니다.

추가 리소스

Introduction to UI Toolkit

UI 빌더

Unity 매뉴얼

UI 툴킷 시작하기

커스텀 에디터 창 생성

창에 UI 컨트롤 추가

UI 빌더를 사용하여 UI 컨트롤 추가

UXML을 사용하여 UI 컨트롤 추가

C# 스크립트를 사용하여 UI 컨트롤 추가

UI 컨트롤의 동작 정의

예제 테스트

추가 리소스