UIElements 开发者指南

画布组 (Canvas Group)*：​

画布中的一组 UI 元素。使用画布组 (Canvas Group) 可在整体上控制一组 UI 元素，而无需单独处理每个元素。更多信息

画布渲染器 (Canvas Renderer)*：​

渲染画布中包含的图形 UI 对象。更多信息

画布缩放器 (Canvas Scaler)*：​

控制画布中所有 UI 元素的整体比例和像素密度，包括字体大小和图像边框。更多信息

图像控件 (Image control)：​

图像控件向用户显示非交互式图像，比如装饰和图标。可以从脚本更改图像以反映其他控件中的更改。更多信息

可交互 (Interactable)：​

一个 UI 组件属性，用于确定组件是否可以接受输入。更多信息

UI 遮罩 (UI Mask)*：​

一种可视组件，可将图像从视图限制为仅图像的一小部分。例如，可以将遮罩应用于面板 UI 元素以阻止查看所有子图像。更多信息

原始图像 (Raw image)：​

一个可视化 UI 组件，向用户显示非交互式图像。此图像可用于装饰、图标等，也可以从脚本更改图像以便反映其他控件的更改。更多信息

ScrollView*：​

一个 UI 控件，在可查看区域中显示一组大量的控件，可以使用滚动条查看这些控件。更多信息

阴影 (Shadow)：​

一个 UI 组件，可为图形组件（如文本或图像）添加简单的轮廓效果。必须与图形组件位于同一游戏对象上。更多信息

文本 (Text)：​

与用户之间的非交互式文本。此控件可用于为其他 GUI 控件提供标题或标签，或显示说明或其他文本。更多信息

TextField 控件 (TextField control)*：​

TextField 控件可向用户显示非交互式文本，例如标题、其他 GUI 控件的标签或者指示信息。更多信息

文本输入字段 (Text Input Field)*：​

允许用户输入文本字符串的字段。更多信息

开关 (Toggle)：​

一个可让用户打开或关闭某个选项的复选框。更多信息

工具栏 (Toolbar)*：​

Unity Editor 顶部的一行按钮和基本控件，允许以各种方式与 Editor 进行交互（例如缩放、移动）。更多信息

UI*：​

（用户界面，User Interface）允许用户与您的应用程序进行交互。更多信息

可视组件 (Visual Component)*：​

一种组件，可方便创建特定于 GUI 的功能。更多信息

UIElements 包括一个布局引擎，可根据布局和样式属性定位视觉元素。该布局引擎是 Yoga 开源项目，实现了名为 Flexbox 的 HTML/CSS 布局系统的子集。

要开始使用 Yoga 和 Flexbox，请参阅以下外部资源：

• Yoga 官方文档：属性映射几乎是 1 比 1
• CSS-Tricks 的 Flexbox 指南：支持大多数属性，仅有一些细微差别

默认情况下，所有视觉元素都是布局的一部分。布局具有以下默认行为：

• 容器垂直分配其子项。
• 容器矩形的位置包括其子矩形。其他布局属性可能限制此行为。
• 带文本的视觉元素在其大小计算中使用文本大小。其他布局属性可能限制此行为。

UIElements 包括标准 UI 控件的内置控件，如按钮、开关、文本字段或标签。这些内置控件具有影响其布局的样式。

下面列出了有关如何使用布局引擎的技巧：

• 设置 width 和 height 来定义元素的大小。
• 使用 flexGrow 属性（USS 格式为：flex-grow: <value>;）为元素分配灵活的大小。当元素的大小由其同级决定时，flexGrow 属性的值用作加权。
• 将 flexDirection 属性设置为 row（USS 格式为：flex-direction: row;）以切换到水平布局。
• 使用相对定位根据元素的原始布局位置来偏移元素。
• 将 position 属性设置为 absolute 以便相对于父位置矩形来放置某个元素。在这种情况下不会影响其同级和父项的布局。

---

• 2018–11–02 页面已修订

视觉树保存窗口中的所有视觉元素。它是由称为视觉元素的轻量级节点组成的对象图。​

这些节点在 C# 堆上分配（手动进行分配或通过从 UXML 模板文件加载 UXML 资源的方式进行分配）。

每个节点都包含布局信息、其绘制和重绘选项以及节点如何响应事件。

VisualElement​

VisualElement 是视觉树中所有节点的公共基类。VisualElement 基类包含样式、布局数据、本地变换、事件处理程序等的属性。

VisualElement 有若干子类，包括专门的控件，它们定义了其他行为和功能。VisualElement 可包含子元素。

不需要从 VisualElement 基类进行派生来使用 UIElements。可以通过样式表和事件回调来自定义 VisualElement 的外观和行为。

连接​

视觉树的根对象称为面板。新元素在连接到面板之前将被忽略。可以向现有元素添加元素来将用户界面连接到面板。

为了验证 VisualElement 是否已连接到面板，可以测试此元素的 panel 属性。未连接视觉元素时，测试将返回 null。

可在 UnityEditor.UIElements 命名空间中使用容器对象的 rootVisualElement 元素将新元素添加到树中。

绘制顺序​

按以下顺序绘制视觉树中的元素：

• 先绘制父项，再绘制子项
• 根据同级名单绘制子项

更改绘制顺序的唯一方法是在父项中重新排序 VisualElement 对象。

位置、变换和坐标系​

不同的坐标系定义如下：

• 世界坐标系：坐标相对于面板空间。面板是视觉树中的最高层级元素。
• 局部坐标系：坐标相对于元素本身。

布局系统会计算每个元素 VisualElement.layout 属性（Rect 类型）。

layout.position 表示为相对于其父项坐标空间的像素。虽然可以直接为 layout.position 赋值，但建议您使用样式表和布局系统来定位元素。

每个 VisualElement 也有一个 layout.transform 属性（ITransform 类型）可相对于父元素对元素进行定位。默认情况下，transform 是标识。

VisualElement.layout.position 和 VisualElement.layout.transform 属性用于定义如何在局部坐标系和父坐标系之间进行转换。

VisualElementExtensions 静态类提供了以下扩展方法在坐标系之间转换点和矩形：

• WorldToLocal 将 Vector2 或 Rect 从 Panel 空间转换为元素内的参照。
• LocalToWorld 将 Vector2 或 Rect 转换为 Panel 空间参照。
• ChangeCoordinatesTo 将 Vector2 或 Rect 从一个元素的局部空间转换为另一个元素的局部空间。

视觉树层级视图
例如，在上图中，树的排列如下：

• Panel
  • 标签部分（称为 DockArea 并标记为“Coordinates”）
  • 蓝色 VisualElement 充当根（称为“rootVisualContainer”）
    • 红色 VisualElement 充当按钮的父级（“red container”，即红色容器）
      • Button

从面板的角度来看：

• 无论参照如何，面板的原点都是 (0, 0)
• 根的原点在世界空间中为 (0, 22)
• 红色容器的原点在世界空间中为 (100, 122)。它的 position 属性（在 layout 属性中定义）设置为 (100, 100)，因为它相对于它的父项：根容器。
• 按钮的原点在世界空间中为 (100, 122)。它的 position 属性（在 layout 属性中定义）设置为 (0, 0)，因为它相对于它的父项：红色容器。

元素的原点是其左上角。

使用 worldBound 属性，同时考虑 VisualElement 的祖先的变换和位置，可以检索该元素的窗口空间坐标。

---

• 2018–11–02 页面已修订