从 uGUI 迁移到 UI Toolkit
本页指导有 uGUI（Unity UI）经验的开发人员过渡到新的 UI Toolkit 系统。它探讨了 uGUI 和 UI Toolkit 之间的异同。
由于 uGUI 是仅限运行时的 UI 系统，因此本页重点介绍运行时 UI。UI Toolkit 可以创建运行时和编辑器 UI。本指南适用于 UI Toolkit 的两种用例。
UI 层次结构
uGUI 和 UI Toolkit 都在层次结构树结构中构建和维护 UI。在 uGUI 中，此层次结构中的所有元素都是单独可见的游戏对象Unity 场景中的基本对象，可以表示角色、道具、风景、相机、航路点等。游戏对象的功能由附加到它的组件定义。更多信息
请参阅术语表在“层次结构视图”面板中。在 UI 工具包中，视觉元素实例化或派生自 C# 的可视化树的节点VisualElement类。您可以设置外观样式、定义行为并将其作为 UI 的一部分显示在屏幕上。更多信息
请参阅术语表被组织成一个可视化树由轻量级节点组成的对象图，用于保存窗口或面板中的所有元素。它定义了使用 UI 工具包构建的每个 UI。
请参阅术语表. 可视树在面板中不可见。
要在UI Toolkit中查看和调试UI层级，可以使用UI调试器。你可以在 编辑器（Editor） 工具栏的 窗口（Window > UI Toolkit） > 调试器（Debugger） 下找到UI 调试器。
主要区别
画布与 UIDocument
这Canvas组件类似于 uGUI 中的UIDocument组件。两者都是附加到游戏对象的 MonoBehaviour。
在 uGUI 中，一个Canvas组件位于 UI 树的根目录。它适用于Canvas Scaler组件来确定下面 UI 的排序顺序、渲染和缩放模式。
在 UI Toolkit 中，UIDocument组件包含对PanelSettings对象。 这PanelSettings包含UI的渲染设置，包括缩放模式和排序顺序。 倍数UIDocument组件可以指向相同的PanelSettings对象，可优化在同一个 UI 屏幕中使用多个 UI 屏幕时的性能场景场景包含游戏的环境和菜单。将每个唯一的场景文件视为一个独特的关卡。在每个场景中，您可以放置环境、障碍物和装饰，实质上是分批设计和构建游戏。更多信息
请参阅术语表.
在 uGUI 中，UI 树层次结构位于 GameObject 下方，其中包含Canvas元件。 在 UI Toolkit 中，UIDocument组件包含对可视化树根元素的引用。
这UIDocument组件还包含对UXML文件的引用，该文件定义了在运行时构建可视化树的UI布局。有关更多信息，请参阅创建UI部分。
注意： 对于编辑器UI，没有UIDocument组件。您可以从EditorWindow，然后实现CreateGUI(). 有关实际示例，请参阅创建自定义编辑器窗口的指南。
游戏对象组件与视觉元素
UI 工具包将 UI 元素称为控件或视觉元素。UI 元素的示例包括：
- 控制
- 按钮
- 文本标签
uGUI 从 GameObjects 构建 UI 层次结构。添加新的 UI 元素需要将新的游戏对象添加到层次结构中。各个控件被实现为MonoBehaviour组件。
在 UI 工具包中，视觉树是虚拟的，不使用游戏对象。无法再在层次结构视图中生成或查看 UI 层次结构，但它消除了对每个 UI 元素使用游戏对象的开销。
在 uGUI 中，UI 元素（直接或间接）派生自UIBehavior基类。同样，在 UI Toolkit 中，所有 UI 元素都派生自名为VisualElement. 主要区别在于VisualElementclass 不是派生自MonoBehaviour.不能将视觉元素附加到游戏对象。
在脚本中使用 UI 工具包控件类似于使用 uGUI 控件。
下表显示了与 uGUI 中 UI 控件及其 UI 工具包对应项的常见脚本交互。
| 行动 | uGUI的 | UI 工具包 |
|---|---|---|
| 将文本写入标签 | m_Label.text = "My Text"; |
m_Label.text = "My Text"; |
| 读取切换的状态 | bool isToggleChecked = m_Toggle.isOn; |
bool isToggleChecked = m_Toggle.value; |
| 为按钮分配回调 | m_Button.onClick.AddListener(MyCallbackFunc); |
m_Button.clicked += MyCallbackFunc_1;或 m_Button.RegisterCallback<ClickEvent>(MyCallbackFunc_2);
|
要了解有关控件及其属性和事件的更多信息，请参阅控件概述页面。
访问界面元素
在uGUI中，有两种方式脚本一段代码，允许您创建自己的组件、触发游戏事件、随时间修改组件属性以及以您喜欢的任何方式响应用户输入。更多信息
请参阅术语表可以访问 UI 元素：
- 在编辑器中分配对UI组件的引用。
- 使用辅助函数（例如
GetComponentInChildren<T>().
由于 UI 工具包中没有游戏对象或组件，因此无法直接将引用分配给编辑器中的控件。它们必须在运行时使用查询函数解析。
相反，请通过UIDocument元件。
UIDocument是一个MonoBehaviour，因此您可以将其分配为引用并使其成为预制件：一种资产类型，允许您存储包含组件和属性的游戏对象。预制件充当模板，你可以从中在场景中创建新的对象实例。更多信息
请参阅术语表.这UIDocument组件包含对根视觉元素的引用。从根目录，脚本可以按类型或名称查找子元素，类似于 uGUI。
下表显示了在 uGUI 和 UI Toolkit 中访问 UI 控件的直接比较
| 行动 | uGUI的 | UI 工具包 |
|---|---|---|
| 按名称查找 UI 元素 | transform.FindChild("childName"); |
rootVisualElement.Query("childName"); |
| 按类型查找 UI 元素 | transform.GetComponentInChildren<Button>(); |
rootVisualElement.Query<Button>(); |
| 在编辑器中直接分配引用 | 可能 | 不可能 |
创建用户界面
uGUI 和 UI Toolkit 之间最大的区别之一是用户界面的创建。
uGUI和UI Toolkit都允许你直观地构建UI并在编辑器中预览它。在uGUI中，UI与附加到各个UI控件的任何逻辑脚本一起保存在预制件中。
在UI Toolkit中，UI布局在UI Builder中创建，然后另存为一个或多个UXML文件。在运行时，UIDocument组件加载可视化树在内存中组装的UXML文件。
对于类似于 uGUI 的方法，您可以直接从脚本创建 UI 控件，然后在运行时将它们添加到可视化树中。
预制件
uGUI 将游戏对象用于包含视觉效果和逻辑的单个 UI 控件和预制件。UI Toolkit 采用不同的方法来实现可重用性，因为它将逻辑和布局分开。你可以通过UXML和自定义控件创建可重用的UI组件。
要在 UI Toolkit 中创建与预制件类似的模板：
- 为部分UI元素创建一个UXML文件。
- 使用
UIDocument元件。 - 引用游戏对象中的 UXML 文件。
- 添加一个脚本来处理同一游戏对象的 UI 组件逻辑。
- 将游戏对象另存为预制件。
UI 布局
在 uGUI 中在屏幕上排列单个 UI 元素是一个手动过程。默认情况下，UI 控件是自由浮动的，仅受其直接父级的影响。同一父级下的其他 UI 控件不会影响其同级位置或大小。枢轴和锚点控制元素的位置和大小。
UI Toolkit 布局系统受网页设计的影响，并基于自动布局生成。默认情况下，自动布局系统会影响所有元素，一个元素的大小和位置将影响同一父元素下的其他元素。
UI Toolkit 中的默认行为类似于将所有元素放置在VerticalLayoutGroup在 uGUI 中，并添加一个LayoutElement组件到每个。
可以通过更改 IStyle 来禁用自动布局生成 position视觉元素的属性。所有视觉元素都具有此属性。有关代码示例，请参阅 Visual Tree。
UI Toolkit 没有直接等效的 UI 元素的锚定和枢轴，因为与 uGUI 相比存在根本布局差异。
元素的大小和位置由布局引擎控制。有关详细信息，请参阅布局引擎和坐标和位置系统。
渲染顺序
在 uGUI 中，层次结构中游戏对象的顺序决定了渲染顺序。层次结构中更靠后的对象最后呈现并显示在顶部。在具有多个 Canvas 的场景中，Sort Order在根部Canvas组件确定各个UI树的渲染顺序。
UI 工具包中可视化树中的呈现顺序以相同的方式运行。父元素在子元素之前渲染，子元素从第一个到最后一个渲染，因此最后一个元素出现在顶部。在具有多个UI文档的场景中，渲染顺序由Sort Order根上的设置UIDocument元件。
要更改 uGUI 中元素的渲染顺序，例如使元素出现在顶部，您可以调用Transform组件。这VisualElementclass 提供了类似的函数来控制渲染顺序。由于所有 UI 工具包控件都派生自此类，因此所有控件都可以访问此函数。
下表显示了用于控制渲染顺序的 uGUI 函数和 UI Toolkit 中的等效函数：
| 行动 | uGUI的 | UI 工具包 |
|---|---|---|
| 使元素渲染在所有其他兄弟姐妹的下面 | transform.SetAsFirstSibling(); |
myVisualElement.SendToBack(); |
| 使元素渲染在所有其他兄弟之上 | transform.SetAsLastSibling(); |
myVisualElement.BringToFront(); |
| 手动控制元素相对于其同级的渲染顺序 | transform.SetSiblingIndex(newIndex); |
myVisualElement.PlaceBehind(sibling);myVisualElement.PlaceInFront(sibling);
|
事件
就像在 uGUI 中一样，UI Toolkit 中的用户交互会触发事件。代码可以订阅以接收事件回调，例如按下按钮或移动滑块。
在uGUI中，所有UI元素都基于MonoBehaviour，并且可以在编辑器中公开其事件。这允许使用其他游戏对象设置逻辑，例如隐藏或显示其他 UI 元素，或分配回调函数。
在 UI Toolkit 中，逻辑和 UI 布局是分开存储的。回调不能再直接在游戏对象上设置或存储在预制件中。您必须在运行时设置所有回调，并通过脚本处理它们。
Button playButton = new Button("Play");
playButton.RegisterCallback<ClickEvent>(OnPlayButtonPressed);
...
private void OnPlayButtonPressed(ClickEvent evt)
{
// Handle button press
}
UI Toolkit中的事件调度系统与uGUI中的事件不同。根据事件类型，事件不仅发送到目标 UI 控件，还发送到所有父控件。
要了解更多信息，请参阅 Dispatch 事件。
在同一项目中使用 uGUI 和 UI Toolkit
您可能在同一个项目中使用 uGUI 和 UI Toolkit。
在当前版本中，UI Toolkit 不支持 3D 世界空间拾取和渲染。您应该使用 UI Toolkit 制作整个游戏菜单，并使用 uGUI 制作 3D 世界空间。
你也可以用 uGUI 制作整个项目，只用 UI Toolkit 制作一些菜单项。
您可以将 UI Toolkit 或 uGUI 用于任何不在其自身边界之外交互的项目。例如，对于运行时 UI，您可以使用 uGUI 创建屏幕按钮，例如移动端的纵杆，并使用 UI Toolkit 创建模态窗口。
但是，混合 UI 之间的高级交互不起作用：
- 您不能只使用键盘在 UI Toolkit 中的焦点元素和 uGUI 选定的对象之间自由导航。若要导航，必须使用 C# 脚本在边界元素上注册事件，并手动选择或聚焦其他域中的下一个元素。
- 您不能将 uGUI 嵌入到 UI Toolkit 层次结构中，也不能将 UI Toolkit 嵌入到 uGUI 层次结构中。您可以使用
RenderTexture抽签，但事件赶不上。 - UI Toolkit 中的样式和事件约定与 uGUI 不同。如果您使用 uGUI 和 UI Tookit 的分散混合，则很难制作一个具有统一 UI 的项目。