TreeView

使用 TreeView 以树状结构显示层级数据。这是一个功能强大且灵活的控件，通常用于呈现具有父子关系或嵌套结构的数据。

如果需要一个简单的项列表（不是层级树），请考虑使用 ListView 控件。

创建 TreeView

您可以使用__ UI__（即用户界面，User Interface）让用户能够与您的应用程序进行交互。Unity 目前支持三种 UI 系统。更多信息
See in Glossary Builder、UXML 和 C# 创建 TreeView。以下 C# 示例将创建 TreeView：

var treeView = new TreeView();

刷新集合视图

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

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

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

将 TreeView 绑定到数据

您可以将 TreeView 绑定到数据源。数据源可以是对象列表或字符串列表。

以下示例将 TreeView 绑定到自定义类型。

treeView.makeItem = () => new VisualElement();
treeView.bindItem = (i) =>
{
    var c = treeView.GetItemDataForIndex<MyCustomType>(i);
};

注意：在上面的示例中，TreeView.bindItem 接收 Index。必须将 Index（而不是 ID）与 GetItemDataForIndex<T> 结合使用。

为 TreeView 实现拖放操作

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

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

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

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

设置 TreeView 的层级视图

要设置 TreeView 的层级结构，请声明 TreeViewItemData<T>，其中 T 是树的数据类型，然后通过 SetRootItems API 设置数据源。例如，假设具有以下 UXML 结构：

<UXML xmlns="UnityEngine.UIElements">
    <TreeView class="the-uxml-treeview" fixed-item-height="20" />
</UXML>

您可以按以下方式设置 TreeView 的层级视图：

/// <sample>
// Create some list of data, here simply numbers in a few foldouts
var items = new List<TreeViewItemData<string>>(10);
for (var i = 0; i < 10; i++)
{
    var itemIndex = i * 10 + i;

    var treeViewSubItemsData = new List<TreeViewItemData<string>>(10);
    for (var j = 0; j < 10; j++)
        treeViewSubItemsData.Add(new TreeViewItemData<string>(itemIndex + j + 1, $"Data {i+1}-{j+1}"));

    var treeViewItemData = new TreeViewItemData<string>(itemIndex, $"Data {i+1}", treeViewSubItemsData);
    items.Add(treeViewItemData);
};

// The "makeItem" function will be called as needed
// when the TreeView needs more items to render
Func<VisualElement> makeItem = () => new Label();

// As the user scrolls through the list, the TreeView object
// will recycle elements created by the "makeItem"
// and invoke the "bindItem" callback to associate
// the element with the matching data item (specified as an index in the list)
Action<VisualElement, int> bindItem = (e, i) =>
{
    var item = treeView.GetItemDataForIndex<string>(i);
    var id = treeView.GetIdForIndex(i);
    ((Label)e).text = $"ID {id} - {item}";
};

treeView.SetRootItems(items);
treeView.makeItem = makeItem;
treeView.bindItem = bindItem;
treeView.selectionType = SelectionType.Multiple;
treeView.Rebuild();

// Callback invoked when the user double clicks an item
treeView.itemsChosen += (selectedItems) =>
{
    Debug.Log("Items chosen: " + string.Join(", ", selectedItems));
};

// Callback invoked when the user changes the selection inside the TreeView
treeView.selectedIndicesChanged += (selectedIndices) =>
{
    var log = "IDs selected: ";
    foreach (var index in selectedIndices)
    {
        log += $"{treeView.GetIdForIndex(index)}, ";
    }
    Debug.Log(log.TrimEnd(',', ' '));
};
/// </sample>

要在 Unity 中实时试用此示例，请转到窗口 (Window) > UI 工具包 (UI Toolkit) > 示例 (Samples)。

关于 TreeView 的常见问题

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

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

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

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

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

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

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

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

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

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

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

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

使用 BaseTreeViewController.GetIndexForId 和 BaseTreeViewController.GetIdForIndex。

我可以使用水平 TreeView 吗？

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

示例

• 创建列表和树视图：使用 ListView、TreeView、MultiColumnListView 和 MultiColumnTreeView 可创建列表视图和树视图。
• 在窗口之间创建拖放列表和树视图：使用 ListView、TreeView 和 MultiColumnListView 可在窗口之间创建拖放式 UI。

C# 基类和命名空间

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

成员 UXML 属性

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

名称	类型	描述
item-template	UIElements.VisualTreeAsset	用于构造树中每个回收和反弹元素的 UXML 模板。此模板旨在替换 makeItem 定义。

继承 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 的组件。

其他资源

• MultiColumnTreeView
• MultiColumnListView
• 滚动视图 (ScrollView)
• ListView