列表视图

ListView 是一个垂直滚动的区域，它链接到并显示项列表。

注意：水平和垂直滚动器元素是标准的 UI 工具包滚动器。

创建列表视图

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

var listView = new ListView();

ListView 与 ScrollView

您可以使用ScrollView一种 UI 控件，用于在可视区域中显示大量控件，您可以使用滚动条查看这些控件。更多信息
请参阅术语表控件创建与使用 ListView 相同的功能。但是，执行以下作时，ListView 比 ScrollView 更有效：

• 填充列表项
• 管理项目高度
• 绑定和取消绑定到对象
• 实例化视觉元素实例化或派生自 C# 的可视化树的节点VisualElement类。您可以设置外观样式、定义行为并将其作为 UI 的一部分显示在屏幕上。更多信息
  请参阅术语表填写页面所需
• 回收视觉元素以优化内存处理

刷新集合视图

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

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

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

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

设置项目高度

若要更改项高度用于驱动内容的方式，请使用 VirtualizationMethod：

• VirtualizationMethod.FixedHeight将所有项目设置为相同的高度。
• VirtualizationMethod.DynamicHeight允许项目具有不同的高度。

控制滚动速度

ListView 具有内置的子 ScrollView 元素，允许用户滚动浏览列表。您可以通过以下方式控制滚动速度覆盖mouseWheelScrollSize,horizontalPageSize和verticalPageSize使用 C 的 ScrollView 属性#.

使列表可重新排序

默认情况下，ListView 控件不可重新排序。要使其可重新排序，请将reorderable属性设置为true在UI Builder、UXML或C#中。

listView.reorderable = true;

实现 ListView 的拖放作

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

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

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

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

ListView 常见问题解答

下面是有关 ListView 控件的一些常见问题。

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

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

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

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

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

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

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

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

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

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

我可以有一个水平 ListView 吗？

ListView 控件不支持水平布局和虚拟化。建议将 ScrollView 与flex-direction: row水平布局元素。但是，将其应用于 ListView 会破坏虚拟化。

例子

以下UXML示例创建ListView：

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

以下 C# 示例演示了 ListView 的一些可自定义功能：

/// <sample>
// Create some list of data, here simply numbers in interval [1, 1000]
const int itemCount = 1000;
var items = new List<string>(itemCount);
for (var i = 0; i < itemCount; i++)
    items.Add(i.ToString());

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

// As the user scrolls through the list, the ListView 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) => ((Label)e).text = items[i];

var listView = container.Q<ListView>();
listView.makeItem = makeItem;
listView.bindItem = bindItem;
listView.itemsSource = items;
listView.selectionType = SelectionType.Multiple;

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

// Callback invoked when the user changes the selection inside the ListView
listView.selectedIndicesChanged += (selectedIndices) =>
{
    Debug.Log("Index selected: " + string.Join(", ", selectedIndices));

    // Note: selectedIndices can also be used to get the selected items from the itemsSource directly or
    // by using listView.viewController.GetItemForIndex(index).
};
/// </sample>

若要在 Unity 中实时试用此示例，请转到 Window > UI 工具包>示例。 ​ 有关更多示例，请参阅以下内容：

• 创建列表视图和树视图：使用 ListView、TreeView、MultiColumnListView 和 MultiColumnTreeView 创建列表视图和树视图。
• 创建复杂的列表视图：使用 ListView 创建包含字符列表的自定义编辑器窗口。
• 使用 ListView 绑定到列表：创建切换列表并将列表绑定到GameSwitch对象。
• 在窗口之间创建拖放列表和树视图：使用 ListView、TreeView 和 MultiColumnListView 在窗口之间创建拖放 UI。

C# 基类和命名空间

C# 类：ListView
命名空间：UnityEngine.UIElements
基类：BaseListView

成员 UXML 属性

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

继承的UXML属性

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

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

USS 级

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

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

其他资源

• 多列列表视图
• 多列树视图
• 滚动视图
• 树视图