UI 工具包简介

UI 生成器

UI Toolkit 入门

想要使用 UI Toolkit 创建您的第一个 UI？使用此基本的 UI 工具包工作流示例开始使用。

注意：出于演示目的，本指南介绍了如何为编辑器UI添加UI控件。但是，有关将 UI 控件添加到 UI 文档的说明也适用于运行时 UI。有关更多信息，请参阅运行时 UI 入门。

如果您经常执行特定任务，则可以使用 UI Toolkit 为其创建专用 UI。例如，您可以创建自定义编辑器窗口。该示例演示了如何使用UI Builder、UXML和C#脚本创建自定义编辑器窗口并将UI控件添加到自定义编辑器窗口中。

您可以在此 GitHub 存储库中找到此示例创建的已完成文件。

创建自定义编辑器窗口

创建一个带有两个标签的自定义编辑器窗口。

在 Unity 编辑器中使用任何模板创建项目。
在“项目”窗口中，右键单击Assets文件夹，然后选择“创建> UI 工具包”>“编辑器窗口”。
在 UI Toolkit Editor Window Creator 中，输入SimpleCustomEditor在 C# 框中。
保持选中 UXML 复选框并清除 USS 复选框。
选择确认。
要打开编辑器窗口，请选择窗口（Window） > UI 工具包 > SimpleCustomEditor。

您可以在Assets/Editor文件夹。

将 UI 控件添加到窗口

您可以通过以下方式将 UI 控件添加到窗口：

使用 UI 生成器直观地添加 UI 控件
使用类似 XML 的文本文件（UXML）添加 UI 控件
使用 C# 脚本添加 UI 控件

您可以单独使用或组合使用这些方法中的任何一种。以下示例使用这些方法的组合创建三组标签、按钮和切换。

使用 UI 生成器添加 UI 控件

若要直观地将 UI 控件添加到窗口，请使用 UI 生成器。除了默认标签之外，以下步骤还在自定义编辑器窗口中添加按钮和切换开关。

在Editor文件夹，双击SimpleCustomEditor.uxml以打开 UI Builder。
在UI构建器中，将按钮（Button） 和 切换（Toggle）从 库（Library） > 控件（Controls）拖到层级（Hierarchy）或 视口（Viewport）中的窗口预览中。
在“层次结构”窗口中，选择“标签”。
在检查器一个 Unity 窗口，显示有关当前选定游戏对象、资产或项目设置的信息，允许您检查和编辑值。更多信息
请参阅术语表窗口中，将默认文本更改为These controls were created in UI Builder在“文本”字段中。
在“层次结构”窗口中，选择“按钮”。
在“检查器”窗口中，输入This is button1在“文本”字段中。
进入button1在“名称”字段中。
在“层次结构”窗口中，选择“切换”。
在“检查器”窗口中，输入Number?在标签字段中。
进入toggle1在“名称”字段中。
保存并关闭 UI Builder 窗口。
如果您尚未关闭自定义编辑器窗口，请关闭此作。
在“项目”窗口中，选择SimpleCustomEditor.cs并确保 可视化树资源（Visual Tree Asset） 设置为SimpleCustomEditor (Visual Tree Asset)在“检查器”窗口中。
选择 Window > UI Toolkit > SimpleCustomEditor 重新打开自定义编辑器窗口，以查看刚刚添加的按钮和切换。

使用UXML添加UI控件

如果你更喜欢在文本文件中定义你的UI，你可以编辑UXML以添加UI控件。以下步骤将另一组标签、按钮和切换添加到窗口中。

在Editor文件夹中，选择 资产（Assets） > 创建 > UI 工具包> UI 文档（UI Document），以创建名为SimpleCustomEditor_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.

导入手动创建的UXML文件，方法是将以下内容添加到CreateGUI方法：

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

保存您的更改。
选择 Window > UI Toolkit > SimpleCustomEditor。这将打开你的自定义编辑器窗口，其中包含三个标签、两个按钮和两个切换开关。

使用 C# 脚本添加 UI 控件

如果您更喜欢编码，可以使用 C# 脚本将 UI 控件添加到窗口。以下步骤将另一组标签、按钮和切换添加到窗口中。

打开SimpleCustomEditor.cs.
Unity 使用UnityEngine.UIElements用于基本 UI 控件，如标签、按钮和切换。若要使用 UI 控件，必须添加以下声明（如果尚不存在）。
```
using UnityEngine.UIElements;
```
将现有标签的文本从"Hello World! From C#"自"These controls were created using C# code.".

EditorWindow 类有一个名为rootVisualElement.要将 UI 控件添加到窗口，请先使用一些属性实例化元素类，然后使用Add方法rootVisualElement.

您的完成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_VisualTreeAsset.Instantiate());

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

选择 Window > UI Toolkit > SimpleCustomEditor 打开自定义编辑器窗口，查看三个标签、三个按钮和三个切换开关。

定义 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 : ""));
    }
}

测试示例

从菜单中，选择窗口>UI 工具包> SimpleCustomEditor。

其他资源

UXML的
可视化树由轻量级节点组成的对象图，用于保存窗口或面板中的所有元素。它定义了使用 UI 工具包构建的每个 UI。
请参阅术语表
标签
按钮
切换允许用户打开或关闭选项的复选框。更多信息
请参阅术语表
创建自定义编辑器窗口