MultiColumnListView

ObjectField

MultiColumnTreeView

MultiColumnTreeView 是一个__ UI__（即用户界面，User Interface）让用户能够与您的应用程序进行交互。Unity 目前支持三种 UI 系统。更多信息
See in Glossary 控件，通常用于显示具有多个列的表格或网格类数据。使用 MultiColumnTreeView 以结构化的格式呈现数据，每一行代表一个项或条目，每一列代表该项的特定属性或特征。

创建 MultiColumnTreeView

您可以使用 UXML 和 C# 创建 MultiColumnTreeView。以下 C# 示例将创建具有两列的 MultiColumnTreeView：

var multiColumnTreeView = new MultiColumnTreeView();
multiColumnTreeView.columns.Add(new Column { title = "Name", width = 20 });
multiColumnTreeView.columns.Add(new Column { title = "Power", width = 80 });

刷新集合视图

要刷新集合视图，通常应调用 RefreshItems 或 RefreshItem 方法。但是，在以下情况下，请改为调用 Rebuild 来刷新收集视图：

您可以更改数据源的类型，例如从 List<float> 更改为 List<Vector3>。
您可以更改为 makeItem 或 destroyItem。

注意：如果调用 Rebuild，则会重新构建集合视图，因此成本可能很高。如果调用 RefreshItems 或 RefreshItem，则仅刷新集合视图，因此成本较低。

将 MultiColumnTreeView 绑定到数据

您可以将 MultiColumnTreeView 绑定到数据源，并根据提供的数据自动填充行和列。请参阅创建列表和树视图以查看示例。

对 MultiColumnTreeView 进行排序

您可以通过默认算法启用 MultiColumnTreeView 的排序功能，或者在默认排序操作无法满足需求时，实施自定义算法。

启用排序后，要按单个列排序，请单击列标题。要对多个列进行排序，请按住 Ctrl 键（macOS：Cmd）并单击。要禁用排序，请按住 Shift 键并单击。

默认排序

要使用默认算法启用排序，请将 sortingMode 属性设置为 ColumnSortingMode.Default，并实现 Column.comparison 以通过源中的索引比较两个项。

有关示例，请参阅 MultiColumnTreeView 默认排序示例。

自定义排序

要实现自定义排序，请将 sortingMode 属性设置为 ColumnSortingMode.Custom，并实现 columnSortingChanged 回调。在回调中，使用 sortColumns 相应重新排序列表，并在项的源更新后触发 RefreshItems()。

sortColumns 属性是列在排序后的当前状态：它列出了按照排序顺序排列的列。如果按第 1 列、第 2 列和第 3 列的先后顺序排序，则 sortedColumns 列表为 [1, 2, 3]。如果按第 3 列、第 2 列和第 1 列的先后顺序排序，则 sortedColumns 列表为 [3, 2, 1]。

为 MultiColumnTreeView 实现拖放操作

拖放是 UI 设计中的一种常见功能。要实现拖放操作，请覆盖以下方法：

要启用拖动项，请覆盖 canStartDrag。
要设置拖动哪些项，请覆盖 setupDragAndDrop。
要获取项状态更改，请覆盖 dragAndDropUpdate。您可以根据拖动位置或其他条件执行特定操作。
要控制拖放行为，请覆盖 handleDrop。

在拖放操作期间，您可以通过拖动启用项的重新排序。要启用，请在 UI Builder、UXML 和 C# 中将 reorderable 属性设置为 true。

有关示例，请参阅在窗口之间创建拖放列表和树视图。

MultiColumnTreeView 常见问题

以下是有关 MultiColumnTreeView 控件的一些常见问题：

我可以获取屏幕上可见行的索引吗？

没有专门用于实现该功能的 API。您可以使用 bindItem 和 unbindItem 回调来跟踪这些索引。

我可以获取视图中可见的行列表吗？

没有专门用于实现该功能的 API。您可以使用 UQuery 检索感兴趣的元素。

视图控制器的任何覆写的函数都必须调用 base.Method 吗？

仅当希望扩展其默认行为时才调用此方法。

我已经在我的行中添加了一个开关 (Toggle)。为什么用户选择该行时，选择项不会跳转到该行？

默认情况下，只有在鼠标按下事件没有被该行的内容占用时才会选中该行。在这种情况下，您的开关 (Toggle) 会阻止事件传播。要解决此问题，可在 Toggle 上用 TrickleDown 注册 PointerDownEvent 回调，以调用 SetSelection。

当用户在视图中更改其选择时，我如何收到回调？

建议在需要时使用 selectedIndicesChanged 回调按索引检索数据。虽然也可以使用 selectionChanged，但请注意，它会返回一个对象列表，在与值类型一起使用时，这可能会导致装箱分配。

如何从 ID 转换为索引，反之亦然？

使用 BaseTreeViewController.GetIndexForId 和 BaseTreeViewController.GetIdForIndex。

我可以使用水平 MultiColumnTreeView 吗？

MultiColumnTreeView 控件不支持水平布局和虚拟化。建议使用带有 flex-direction: row 的__ ScrollView__一种 UI 控件，可在可视区域内显示一大组控件，可以使用滚动条查看这些控件。更多信息
See in Glossary 来水平布局元素。

示例

创建列表和树视图：使用 ListView、TreeView、MultiColumnListView 和 MultiColumnTreeView 可创建列表视图和树视图。

C# 基类和命名空间

C# 类：MultiColumnTreeView
命名空间：UnityEngine.UIElements
基类：BaseTreeView

成员 UXML 属性

此元素具有以下成员属性：

名称	类型	描述
`columns`	`UIElements.Columns+UxmlSerializedData`	多列标题的列集合。
`sort-column-descriptions`	`UIElements.SortColumnDescriptions+UxmlSerializedData`	默认情况下是已排序列的集合。
`sorting-enabled`	`boolean`	是否在多列标题中启用了排序。这已弃用。请改用 `sortingMode`。
`sorting-mode`	`UIElements.ColumnSortingMode`	指示如何对列进行排序。要启用排序，请将其设置为 `ColumnSortingMode.Default` 或 `ColumnSortingMode.Custom`。`Default` 模式使用 `MultiColumnController` 提供的排序算法，作用于索引。您还可以通过响应 `columnSortingChanged` 事件，使用 `Custom` 模式实现自己的排序。 __注意__：如果至少有一个已排序的列，则会暂时禁用重新排序。

继承 UXML 属性

此元素从其基类继承以下属性：

名称	类型	描述
`auto-expand`	`boolean`	设置为 true 时，项在添加到 TreeView 时会自动展开。
`binding-path`	`string`	要绑定的目标属性的路径。
`fixed-item-height`	`float`	列表中单个项的高度（单位：像素）。此属性必须在使用 `virtualizationMethod` 设置为 `FixedHeight` 时设置，以便集合视图正常工作。如果在 `virtualizationMethod` 为 `DynamicHeight` 时设置，则用作默认高度，以便在布局项之前计算所需的项数量和可滚动区域。应将其设置为项的最小预期高度。
`focusable`	`boolean`	如果元素可以获得焦点，则为 true。
`reorderable`	`boolean`	获取或设置一个值，指示用户是否可以拖动列表项来重新排序。默认值为 `false`，这样允许用户在实现 `canStartDrag`、`setupDragAndDrop`、`dragAndDropUpdate` 和 `handleDrop` 时拖动项到其他视图或从其他视图拖动项。将此值设置为 `true` 可允许用户对列表中的项重新排序。
`selection-type`	`UIElements.SelectionType`	控制选择类型。默认值为 `SelectionType.Single`。将集合视图设置为禁用选择时，将清除所有当前选择。
`show-alternating-row-backgrounds`	`UIElements.AlternatingRowBackground`	此属性控制集合视图行的背景颜色是否交替。从 `AlternatingRowBackground` 枚举中获取值。
`show-border`	`boolean`	启用此属性可在集合视图周围显示边框。如果设置为 true，则集合视图内部使用的 ScrollView 周围会出现一个边框。
`tabindex`	`int`	用于对焦点环中可获得焦点的元素排序的整数。必须大于或等于零。
`virtualization-method`	`UIElements.CollectionVirtualizationMethod`	滚动条可见时用于此集合的虚拟化方法。从 `CollectionVirtualizationMethod` 枚举中获取值。默认值为 `FixedHeight`。使用固定高度时，请指定 `fixedItemHeight` 属性。固定高度性能更好，但在内容上提供的灵活性较少。使用 `DynamicHeight` 时，集合将等待计算实际高度。动态高度更加灵活，但性能较低。

此元素还从 VisualElement 继承以下属性：

名称	类型	描述
`content-container`	`string`	向其添加子元素，通常与元素本身相同。
`data-source`	`Object`	为此 VisualElement 分配一个数据源，此数据源将覆盖任何已继承的数据源。此数据源由所有子项继承。
`data-source-path`	`string`	从数据源到值的路径。
`data-source-type`	`System.Type`	可分配给此 VisualElement 的可能数据源的类型。仅当在设计时无法指定有效数据源时，UI Builder 才使用此信息作为补全数据源路径字段的提示。
`language-direction`	`UIElements.LanguageDirection`	指示元素文本的方向性。该值将传播到元素的子项。将 languageDirection 设置为 RTL，即可通过反转文本、处理换行和单词自动换行的方式，提供对从右到左 (RTL) 语言的基本支持。但是，它不提供全面的 RTL 支持，因为这需要文本整形（包括字符重新排序）和 OpenType 字体功能支持。未来更新计划提供全面的 RTL 支持，这将涉及额外的 API 来处理语言、脚本和字体功能规范。要增强此属性的 RTL 功能，用户可以在 Unity 资源商店中探索可用的第三方插件，并使用 `ITextElementExperimentalFeatures.renderedText`	`name`	`string`	此 VisualElement 的名称。使用此属性可编写针对特定元素的 USS 选择器。标准做法是为元素指定唯一名称。
`picking-mode`	`UIElements.PickingMode`	确定是否可以在 mouseEvents 或 `IPanel.Pick` 查询期间选择此元素。
`style`	`string`	设置 `VisualElement` 样式值。
`tooltip`	`string`	用户将光标悬停在元素上一小段时间后信息框内显示的文本。仅在编辑器 UI 中受支持。
`usage-hints`	`UIElements.UsageHints`	用于指定 `VisualElement` 高级预期使用模式的提示值组合。仅当 `VisualElement` 还不属于 `Panel` 的一部分时，才能设置此属性。一旦成为 `Panel` 的一部分，此属性实际上就变为只读，尝试更改此属性将显示异常。适当的 `UsageHints` 规范会促使系统根据预期的使用模式，做出更好的决策，以处理或加速某些操作。请注意，这些提示不会影响行为或视觉效果，只会影响面板及其元素的整体性能。建议始终考虑指定适当的 `UsageHints`，但请记住，在某些情况下（例如，由于目标平台上的硬件限制），某些 `UsageHints` 可能会在内部被忽略。
`view-data-key`	`string`	用于 View Data 持久性，例如树展开状态、滚动位置或缩放级别。此键用于保存和加载 View Data 存储中的视图数据。如果未设置此键，则会对关联的 `VisualElement` 禁用持久性。有关更多信息，请参阅 View Data 持久性。

USS 类

下表列出了所有 C# 公共属性名称及其相关的 USS 选择器。

C# 属性	USS 选择器	描述
`ussClassName`	`.unity-tree-view`	TreeView 元素的 USS 类名称。 Unity 将此 USS 类添加到 TreeView 元素的每个实例。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个 TreeView。
`itemUssClassName`	`.unity-tree-view__item`	TreeView 项元素的 USS 类名称。 Unity 将此 USS 类添加到 TreeView 的每个项元素。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个项。
`itemToggleUssClassName`	`.unity-tree-view__item-toggle`	TreeView 项切换元素的 USS 类名称。 Unity 将此 USS 类添加到 TreeView 的每个项切换元素。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个项。
`itemIndentsContainerUssClassName`	`.unity-tree-view__item-indents`	TreeView 缩进容器元素的 USS 类名称。 Unity 将此 USS 类添加到 TreeView 的每个缩进容器元素。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个项。
`itemIndentUssClassName`	`.unity-tree-view__item-indent`	TreeView 缩进元素的 USS 类名称。 Unity 将此 USS 类添加到 TreeView 的每个缩进元素。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个项。
`itemContentContainerUssClassName`	`.unity-tree-view__item-content`	TreeView 项容器元素的 USS 类名称。 Unity 将此 USS 类添加到 TreeView 的每个项容器元素。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个项。
`ussClassName`	`.unity-collection-view`	BaseVerticalCollectionView 元素的 USS 类名称。 Unity 将此 USS 类添加到 BaseVerticalCollectionView 元素的每个实例。应用于此类的任何样式都会影响位于视觉树样式表旁边或下方的每个 BaseVerticalCollectionView。
`borderUssClassName`	`.unity-collection-view--with-border`	带边框的 BaseVerticalCollectionView 元素的 USS 类名称。如果 BaseVerticalCollectionView 元素实例的 `BaseVerticalCollectionView.showBorder` 属性设置为 true，Unity 会将此 USS 类添加到该实例中。应用于此类的任何样式都会影响位于视觉树样式表旁边或下方的每个此类 BaseVerticalCollectionView。
`itemUssClassName`	`.unity-collection-view__item`	BaseVerticalCollectionView 元素中项元素的 USS 类名称。 Unity 将此 USS 类添加到 BaseVerticalCollectionView 包含的每个项元素。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个项元素。
`dragHoverBarUssClassName`	`.unity-collection-view__drag-hover-bar`	拖动悬停条的 USS 类名称。 Unity 将此 USS 类添加到用户拖动列表中的某个项时显示的栏中。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个 BaseVerticalCollectionView。
`dragHoverMarkerUssClassName`	`.unity-collection-view__drag-hover-marker`	用于指示深度的拖动悬停圆形标记的 USS 类名称。 Unity 将此 USS 类添加到用户拖动列表中的某个项时显示的栏中。应用于此类的任何样式都会影响位于视觉树样式表旁边或下方的每个 BaseVerticalCollectionView。
`itemDragHoverUssClassName`	`.unity-collection-view__item--drag-hover`	拖动悬停时应用于项元素的 USS 类名称。 Unity 在拖动时将此 USS 类添加到项元素中。应用于此类的任何样式都会影响位于视觉树样式表旁边或下方的每个 BaseVerticalCollectionView 项。
`itemSelectedVariantUssClassName`	`.unity-collection-view__item--selected`	BaseVerticalCollectionView 中选定项元素的 USS 类名称。 Unity 将此 USS 类添加到 BaseVerticalCollectionView 中的每个选定元素。`BaseVerticalCollectionView.selectionType` 属性决定了是否可以选择零个、一个或多个元素。应用于此类的任何样式都会影响位于视觉树样式表旁边或下方的每个 BaseVerticalCollectionView 项。
`itemAlternativeBackgroundUssClassName`	`.unity-collection-view__item--alternative-background`	BaseVerticalCollectionView 中奇数行的 USS 类名称。当 `BaseVerticalCollectionView.showAlternatingRowBackgrounds` 属性设置为 `ContentOnly` 或 `All` 时，Unity 会将此 USS 类添加到 BaseVerticalCollectionView 中的每个奇数项。当 `showAlternatingRowBackgrounds` 属性设置为这些值之一时，奇数项显示的背景颜色与偶数项不同。此 USS 类用于将奇数项与偶数项区分开来。当 `showAlternatingRowBackgrounds` 属性设置为 `None` 时，不会添加 USS 类，并且任何依赖于该类的样式或行为都将失效。
`listScrollViewUssClassName`	`.unity-collection-view__scroll-view`	BaseVerticalCollectionView 中滚动视图的 USS 类名称。 Unity 将此 USS 类添加到 BaseVerticalCollectionView 的滚动视图中。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个 BaseVerticalCollectionView 滚动视图。
`disabledUssClassName`	`.unity-disabled`	本地被禁用元素的 USS 类名称。

还可以使用检视器中的匹配选择器 (Matching Selectors) 部分或 UI 工具包调试器来查看哪些 USS 选择器在其层级视图的每个级别上影响 VisualElement 的组件。

其他资源