版本: Unity 6 (6000.0)
语言 : 英语
UXML 元素 LongField
UXML 元素 MaskField

UXML 元素 ListView

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

注意：水平和垂直滚动条元素是标准的 UI(用户界面) 允许用户与您的应用程序交互。Unity 目前支持三种 UI 系统。 更多信息
查看 词汇表 工具包滚动条。

创建 ListView

可以使用 UI 构建器、UXML 和 C# 创建 ListView。以下 C# 示例创建了一个 ListView

var listView = new ListView();

ListView 与 ScrollView 的区别

可以使用 ScrollView一个 UI 控件，它在可视区域内显示一组大型控件，您可以使用滚动条查看这些控件。 更多信息
查看 词汇表 控件创建与使用 ListView 相同的功能。但是，当执行以下操作时，ListView 比 ScrollView 更有效率

  • 填充列表项
  • 管理项高度
  • 绑定和解除绑定到对象
  • 实例化填充页面所需的 视觉元素视觉树中的一个节点，它实例化或派生自 C# VisualElement 类。您可以设置外观、定义行为并将其显示在屏幕上作为 UI 的一部分。 更多信息
    查看 词汇表     数目
  • 回收视觉元素以优化内存处理

刷新集合视图

要刷新集合视图，通常调用 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 设计中的常见功能。要实现拖放操作，请覆盖以下方法

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

在拖放操作期间，可以通过拖动启用项目的重新排序。要启用，请在 UI 构建器、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 (int i = 1; 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) => (e as Label).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.selectionChanged += (selectedItems) =>
{
    Debug.Log("Items selected: " + string.Join(", ", selectedItems));
};
/// </sample>

要尝试在 Unity 中实时使用此示例，请转到 窗口 > UI 工具包 > 示例。有关更多示例，请参阅以下内容

C# 基类和命名空间

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

成员 UXML 属性

此元素具有以下成员属性

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

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

继承的 UXML 属性

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

名称 类型 描述
allow-add 布尔值 此属性允许用户在单击“添加”按钮时允许或阻止添加项目。它必须返回 true 或 false。

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

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

当设置为 AutoAssign 时，不需要指定绑定回调，因为可以使用绑定来填充元素。
fixed-item-height 浮点数 列表中单个项目的像素高度。

当使用 virtualizationMethod 设置为 FixedHeight 时，必须设置此属性才能使集合视图正常工作。如果在 virtualizationMethod 为 DynamicHeight 时设置，它将作为默认高度，以帮助在项目布局之前计算必要的项目数量和可滚动区域。它应设置为项目的最小预期高度。
focusable 布尔值 如果元素可以获得焦点，则为真。
header-title 字符串 此属性控制使用 showFoldoutHeader 时折叠框标题的文本。

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

默认值为 Simple。当此属性设置为 Animated 时，Unity 会在每个项目前面添加拖动句柄，并且当重新排序发生时，拖放操作会以动画方式推动项目。仅 Simple 拖动模式支持多项目重新排序。
reorderable 布尔值 获取或设置一个值，该值指示用户是否可以拖动列表项以重新排序它们。

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

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

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

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

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

SA: UnityEditor.UIElements.BindingExtensions.Bind
show-foldout-header 布尔值 此属性控制列表视图是否显示标题，标题以可展开或折叠的折叠形式呈现。

默认值为 false。将此属性设置为 true 时，Unity 会在列表视图的层次结构中添加一个折叠，并将滚动视图移动到新创建的折叠中。您可以使用 ListView 上的 headerTitle 属性更改此折叠的文本。如果 showBoundCollectionSize 设置为 true，ListView 会包含一个用于控制数组大小的文本字段。如果设置了 makeHeader 回调，则不会显示折叠。
tabindex int 用于在焦点环中对可聚焦元素进行排序的整数。必须大于或等于零。
virtualization-method UIElements.CollectionVirtualizationMethod 当滚动条可见时，此集合要使用的虚拟化方法。从 CollectionVirtualizationMethod 枚举中获取一个值。

默认值为 FixedHeight。使用固定高度时，请指定 fixedItemHeight 属性。固定高度的性能更高，但在内容方面灵活性较低。使用 DynamicHeight 时，集合将等待实际高度计算完成。动态高度的灵活性更高，但性能较低。

此元素还继承了以下属性，这些属性来自 VisualElement

名称 类型 描述
content-container 字符串 子元素被添加到其中，通常与元素本身相同。
data-source Object 为该 VisualElement 指定一个数据源，该数据源将覆盖任何继承的数据源。此数据源由所有子元素继承。
data-source-path 字符串 从数据源到值的路径。
data-source-type System.Type 可分配给该 VisualElement 的数据源的可能类型。

此信息仅供 UI Builder 使用，作为提示，当在设计时无法指定有效数据源时，为数据源路径字段提供一些自动补全功能。
language-direction UIElements.LanguageDirection 指示元素文本的方向。该值将传播到元素的子元素。

将 languageDirection 设置为 RTL 会通过反转文本并适当地处理换行和自动换行来添加对从右到左 (RTL) 的基本支持。但是，它不提供全面的 RTL 支持，因为这需要文本整形，其中包括字符的重新排序，以及 OpenType 字体功能支持。全面的 RTL 支持计划在将来的更新中提供，这将涉及处理语言、脚本和字体功能规范的其他 API。

为了增强此属性的 RTL 功能，用户可以探索 Unity Asset Store 中可用的第三方插件，并使用 ITextElementExperimentalFeatures.renderedText
name 字符串 该 VisualElement 的名称。

使用此属性编写针对特定元素的 USS 选择器。标准做法是给元素一个唯一的名称。
picking-mode UIElements.PickingMode 确定该元素在鼠标事件或 IPanel.Pick 查询期间是否可以被拾取。
style 字符串 设置 VisualElement 样式值。
tooltip 字符串 在用户将鼠标悬停在元素上一段时间后，在信息框中显示的文本。这仅在编辑器 UI 中受支持。
usage-hints UIElements.UsageHints 指定 VisualElement 的高级预期使用模式的提示值组合。仅当 VisualElement 尚未成为 Panel 的一部分时，才能设置此属性。一旦成为 Panel 的一部分，此属性将有效地变为只读，尝试更改它将引发异常。指定适当的 UsageHints 会促使系统根据预期的使用模式，对如何处理或加速某些操作做出更好的决策。请注意，这些提示不会影响行为或视觉结果，只会影响面板及其内部元素的整体性能。建议始终考虑指定适当的 UsageHints，但请记住，某些 UsageHints 可能会在某些情况下被内部忽略（例如，由于目标平台上的硬件限制）。
view-data-key 字符串 用于视图数据持久性，例如树展开状态、滚动位置或缩放级别。

此密钥用于从视图数据存储中保存和加载视图数据。如果未设置此密钥，则关联的 VisualElement 的持久性将被禁用。有关更多信息，请参阅 视图数据持久性。

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.showBorder 属性设置为 true，则 Unity 会将此 USS 类添加到 BaseVerticalCollectionView 元素的实例。应用于此类的任何样式都会影响位于样式表旁边的或其下方视觉树中的每个此类 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 类名。

您也可以使用 检查器或 UI 工具包调试器中的匹配选择器部分 查看哪些 USS 选择器影响 VisualElement 及其层次结构中每个级别的组件。

其他资源

UXML 元素 LongField
UXML 元素 MaskField
版权所有 ©2005-2024 Unity Technologies。保留所有权利。由 6000.0.25f1 (91cbff7fd174) 构建。构建于：2024-10-19。
教程社区解答知识库论坛资源商店使用条款法律隐私政策Cookie不要出售或分享我的个人信息