树视图

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

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

创建树视图

你可以使用 UI Builder、UXML 和 C# 创建 TreeView。以下 C# 示例创建 TreeView：

var treeView = new TreeView();

刷新集合视图

若要刷新集合视图，可以调用RefreshItems/RefreshItem或Rebuild.

通常，调用RefreshItems或RefreshItem方法——这些方法仅刷新集合视图，并且成本较低。如果您调用Rebuild，则集合视图将完全重建，这可能会很昂贵。

但是，您必须调用Rebuild在以下情况下：

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

将 TreeView 绑定到数据

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

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

treeView.makeItem = () => new VisualElement();

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

注意：在前面的示例中，TreeView.bindItem 接收 Index。您必须将索引（而不是 ID）与GetItemDataForIndex<T>.

实现 TreeView 的拖放作

拖放是 UI 设计中的常见功能。若要实现拖放作，请重写以下方法：

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

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

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

设置 TreeView 的层次结构

要设置 TreeView 的层次结构，请声明TreeViewItemData<T>哪里T是树的数据类型，然后通过SetRootItems应用程序接口。例如，假设你有以下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 工具包>示例。

TreeView 常见问题解答

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

是否可以获取视图中可见的行列表？

没有专用的 API。您可以使用 UQuery 检索感兴趣的元素。

视图控制器的任何被覆盖函数是否必须调用base.Method?

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

我已向我的行添加了一个 Toggle。为什么当用户选择选择时，选择不跳转到该行？

默认情况下，仅当行的内容未使用鼠标向下事件时，才会选择该行。在这种情况下，您的 Toggle 会停止事件传播。要解决此问题，请注册一个PointerDownEvent回调为TrickleDown在切换调用SetSelection.

当用户更改视图中的选择时，如何接收回调？

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

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

没有专用的 API。您可以使用bindItem和unbindItem回调来跟踪这些索引userData.

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

用BaseTreeViewController.GetIndexForId和BaseTreeViewController.GetIdForIndex.

我可以有一个水平的 TreeView 吗？

TreeView 控件不支持水平布局和虚拟化。建议将 ScrollView 与flex-direction: row水平布局元素。

例子

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

C# 基类和命名空间

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

成员 UXML 属性

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

继承的UXML属性

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

此元素还继承了以下属性VisualElement:

USS 级

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

您还可以使用 Inspector 或 UI Toolkit Debugger 中的 Matching Selectors 部分来查看哪些 USS 选择器会影响VisualElement在其层次结构的各个层面。

其他资源

• 多列树视图
• 多列列表视图
• ScrollView一种 UI 控件，用于在可视区域中显示大量控件，您可以使用滚动条查看这些控件。更多信息
  请参阅术语表
• 列表视图