Version: Unity 6.0 (6000.0)
语言 : 中文
LongField
MaskField

ListView

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

注意：水平和垂直 Scroller 元素是标准__ UI__（即用户界面，User Interface）让用户能够与您的应用程序进行交互。Unity 目前支持三种 UI 系统。更多信息
See in Glossary 工具包 Scroller。

创建 ListView

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

var listView = new ListView();

ListView 与 ScrollView

您可以使用 ScrollView 控件来实现与使用 ListView 时相同的功能。但是，执行以下操作时，ListView 比__ ScrollView__一种 UI 控件，可在可视区域内显示一大组控件，可以使用滚动条查看这些控件。更多信息
See in Glossary 更高效：

  • 填充列表项
  • 管理项高度
  • 绑定和取消绑定到对象
  • 实例化填充页面所需的视觉元素数量
  • 回收视觉元素以优化内存处理

刷新集合视图

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

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

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

设置项高度

要更改项高度影响内容的方式，请使用 VirtualizationMethod：

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

控制滚动速度

ListView 有一个内置的子 ScrollView 元素，允许用户对列表执行滚动操作。您可以使用 C# 覆盖 ScrollView 的 mouseWheelScrollSize、horizontalPageSize 和 verticalPageSize 属性来控制滚动速度 。

为 ListView 实现拖放操作

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

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

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

ListView 常见问题

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

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

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

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

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

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

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

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

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

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

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

我可以使用水平 ListView 吗？

ListView 控件不支持水平布局和虚拟化。建议使用带有 flex-direction: row 的 ScrollView 来水平布局元素。但是，将此属性应用于 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 工具包 (UI Toolkit) > 示例 (Samples)。 ​ 有关更多示例，请参阅以下内容：

C# 基类和命名空间

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

成员 UXML 属性

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

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

您可以将其与 BaseListView.bindingSourceSelectionMode 和绑定一起使用，以实现完全无代码的工作流程。

继承 UXML 属性

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

名称 类型 描述
allow-add boolean 此属性允许用户在单击添加 (Add) 按钮时允许或阻止添加项。必须返回 true 或 false。

如果未将回调设置为 false，则将允许任何添加操作。
allow-remove boolean 此属性允许用户在单击删除 (Remove) 按钮时允许或阻止删除项。必须返回 true 或 false。

如果未将该属性设置为 false，则将允许任何删除操作。
binding-path string 要绑定的目标属性的路径。
binding-source-selection-mode UIElements.BindingSourceSelectionMode 此属性控制列表中的每个元素是否会自动将其数据源设置为集合源中的正确项目。

设置为 AutoAssign 时，无需指定绑定回调，因为绑定可用于填充元素。
fixed-item-height float 列表中单个项的高度（以像素为单位）。

此属性必须在使用 virtualizationMethod 设置为 FixedHeight 时设置，以便集合视图正常工作。如果在 virtualizationMethod 为 DynamicHeight 时设置，则用作默认高度，以便在布局项之前计算所需的项数量和可滚动区域。应将其设置为项的最小预期高度。
focusable boolean 如果元素可以获得焦点，则为 true。
header-title string 使用 showFoldoutHeader 时，此属性控制折叠标题的文本。

如果设置了 makeHeader 回调，则会覆盖此属性，且不显示标题。
reorder-mode UIElements.ListViewReorderMode 此属性控制列表视图的拖放模式。

默认值为 Simple。当此属性设置为 Animated 时，Unity 会在每个项前面添加拖动手柄，并在发生重新排序时通过拖放操作以动画的方式推动项。仅在 Simple 拖动模式下才支持多个项重新排序。
reorderable boolean 获取或设置一个值，指示用户是否可以拖动列表项来重新排序。

默认值为 false，这样允许用户在实现 canStartDrag、setupDragAndDrop、dragAndDropUpdate 和 handleDrop 时拖动项到其他视图或从其他视图拖动项。将此值设置为 true 可允许用户对列表中的项重新排序。
selection-type UIElements.SelectionType 控制选择类型。

默认值为 SelectionType.Single。将集合视图设置为禁用选择时，将清除所有当前选择。
show-add-remove-footer boolean 此属性控制是否将页脚添加到列表视图。

默认值为 false。当此属性设置为 true 时，Unity 会在滚动视图下添加一个页脚。此页脚包含两个按钮：一个“+”按钮。单击时，它会在列表视图末尾添加一个项。一个“-”按钮。单击时，它会删除所有选定项，如果未选择任何项，则会删除最后一项。如果设置了 makeFooter 回调，则将覆盖此属性。
show-alternating-row-backgrounds UIElements.AlternatingRowBackground 此属性控制集合视图行的背景颜色是否交替。从 AlternatingRowBackground 枚举中获取值。
show-border boolean 启用此属性可在集合视图周围显示边框。

如果设置为 true，则集合视图内部使用的 ScrollView 周围会出现边框。
show-bound-collection-size boolean 此属性控制列表视图是否显示集合大小（项数）。

默认值为 true。当此属性设置为 true 时，ListView 包含一个 TextField 来控制数组大小。

另请参阅：UnityEditor.UIElements.BindingExtensions.Bind
show-foldout-header boolean 此属性控制列表视图是否以折叠形式（可以展开或折叠）显示标题。

默认值为 false。当此属性设置为 true 时，Unity 会在列表视图的层级视图中添加一个折叠，并将滚动视图移动到该新创建的折叠中。您可以使用 ListView 上的 headerTitle 属性更改此折叠的文本。如果 showBoundCollectionSize 设置为 true，ListView 包含一个 TextField 来控制数组大小。如果设置了 makeHeader 回调，则不显示折叠。
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-list-view ListView 元素的 USS 类名称。

Unity 将此 USS 类添加到 ListView 元素的每个实例。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个 ListView。
itemUssClassName .unity-list-view__item ListView 元素中项元素的 USS 类名称。

Unity 将此 USS 类添加到 ListView 包含的每个项元素。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个项元素。
emptyLabelUssClassName .unity-list-view__empty-label 当 ListView 为空时，显示的标签的 USS 类名称。

Unity 将此 USS 类添加到 ListView 为空时显示的标签中。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个空标签。
reorderableUssClassName .unity-list-view__reorderable 可重新排序的动画 ListView 元素的 USS 类名称。

当 reorderMode 设置为 Animated 时，Unity 将此 USS 类添加到 ListView 元素的每个实例。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个 ListView。
reorderableItemUssClassName .unity-list-view__reorderable-item 可重新排序的动画 ListView 中项元素的 USS 类名称。

当 reorderMode 设置为 Animated 时，Unity 将此 USS 类添加到 ListView 中的每个元素。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个元素。
reorderableItemContainerUssClassName .unity-list-view__reorderable-item__container 可重新排序的动画 ListView 中项容器的 USS 类名称。

当 reorderMode 设置为 Animated 时，Unity 将此 USS 类添加到 ListView 中的每个项容器。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个项容器。
reorderableItemHandleUssClassName .unity-list-view__reorderable-handle 可重新排序的动画 ListView 中拖动手柄的 USS 类名称。

当 reorderMode 设置为 Animated 时，Unity 会将此 USS 类添加到 ListView 中的拖动手柄。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个拖动手柄。
reorderableItemHandleBarUssClassName .unity-list-view__reorderable-handle-bar 可重新排序的动画 ListView 中拖动手柄条的 USS 类名称。

当 reorderMode 设置为 Animated 时，Unity 将此 USS 类添加到 ListView 中的每个拖动手柄。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个拖动手柄条。
footerUssClassName .unity-list-view__footer ListView 页脚的 USS 类名称。

Unity 将此 USS 类添加到 ListView 中的页脚元素。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个 ListView。
foldoutHeaderUssClassName .unity-list-view__foldout-header ListView 折叠标题的 USS 类名称。

Unity 将此 USS 类添加到 ListView 中的折叠元素。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个折叠。
arraySizeFieldUssClassName .unity-list-view__size-field 启用显示绑定集合大小时 ListView 的大小字段的 USS 类名称

当 showBoundCollectionSize 设置为 true 时，Unity 会将此 USS 类添加到 ListView 中的大小字段元素。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个大小字段。
arraySizeFieldWithHeaderUssClassName .unity-list-view__size-field--with-header 启用折叠标题时 ListView 的大小字段的 USS 类名称。

当 showBoundCollectionSize 设置为 true 时，Unity 会将此 USS 类添加到 ListView 中的大小字段元素。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个大小字段。
arraySizeFieldWithFooterUssClassName .unity-list-view__size-field--with-footer 启用页脚时 ListView 的大小字段的 USS 类名称。

当 showBoundCollectionSize 设置为 true 时，Unity 会将此 USS 类添加到 ListView 中的大小字段元素。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个大小字段。
listViewWithHeaderUssClassName .unity-list-view--with-header 启用折叠标题时 ListView 的 USS 类名称。

当 showFoldoutHeader 设置为 true 时，Unity 会将此 USS 类添加到 ListView。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个列表。
listViewWithFooterUssClassName .unity-list-view--with-footer 启用添加/删除页脚时 ListView 的 USS 类名称。

当 showAddRemoveFooter 设置为 true 时，Unity 会将此 USS 类添加到 ListView。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个列表。
scrollViewWithFooterUssClassName .unity-list-view__scroll-view--with-footer 启用添加/删除页脚时滚动视图的 USS 类名称。

当 showAddRemoveFooter 设置为 true 时，Unity 会将此 USS 类添加到 BaseListView 的滚动视图。应用于此类的任何样式都会影响位于视觉树中样式表旁边或下方的每个列表。
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 的组件。

其他资源

LongField
MaskField
版权所有 ©2005-2025 Unity Technologies. All rights reserved. Built from 6000.0.65f1 (f34bf41fecc5). Built on: 2025-12-15.
教程社区答案知识库论坛资源商店使用条款法律信息隐私政策Cookie禁止出售或共享我的个人信息