列表框

列表框显示一系列选项，并允许用户选择其中一个或多个。

安装

以上命令仅用于单独安装。如果已全局安装 @nextui-org/react ，则可以跳过此步骤。

导入

NextUI 导出 3 个与列表框相关的组件

• Listbox: 主要组件，是其他组件的包装器。
• ListboxSection: 包含一组列表框项的组件。
• ListboxItem: 代表一个列表框项的组件。

用法

动态项

Listbox 遵循 集合组件 API，接受静态和动态集合。

• 静态：上面的使用示例展示了静态实现，当提前知道完整的选项列表时可以使用。
• 动态：当选项来自外部数据源（例如 API 调用）或随时间更新时，可以使用下面的示例。

禁用键

可以使用 disabledKeys 属性来禁用 Listbox 组件中的列表框项。

注意：每个项目都有一个唯一的键非常重要，否则禁用键将不起作用。

变体

您可以在 Listbox 组件中使用 variant 来更改列表框项的 hover 样式。

单项选择

您可以将 selectionMode 属性设置为 single，以允许用户一次只选择一个项目。

多项选择

您可以将 selectionMode 属性设置为 multiple，以允许用户一次选择多个项目。

注意：要允许空选择，您可以将 disallowEmptySelection 属性设置为 false。

带有图标

可以使用 startContent / endContent 属性向列表框项目添加图标。

注意：如果您使用 currentColor 作为图标颜色，则图标将与项目文本的颜色相同。

带有描述

您可以使用 description 属性向列表框项目添加描述。

带有顶部和底部内容

您可以使用 topContent 和 bottomContent 属性在列表框项目上方和下方添加内容。

带有部分

您可以使用 ListboxSection 组件对列表框项目进行分组。

注意：没有 title 的部分必须提供一个 aria-label 以提高可访问性。

路由

<ListboxItem> 组件可与框架和客户端路由（如 Next.js 和 React Router）一起使用。 请参阅路由指南，了解如何设置此功能。

虚拟化

Select 支持虚拟化，它允许仅渲染视口中可见的项目，从而有效地渲染大型列表。 您可以通过将 isVirtualized 属性设置为 true 来启用虚拟化。

注意：虚拟化策略基于 @tanstack/react-virtual 包，该包通过仅渲染视口中可见的项目来提供大型列表的高效渲染。

一万个项目

以下是使用 10,000 个项目进行虚拟化的示例。

插槽

列表框组件包含 3 个带有插槽的组件：基础组件 Listbox、ListboxItem 和 ListboxSection 组件。

Listbox

• base: 列表框组件的主要包装器。此插槽包裹 topContent、bottomContent 和 list 插槽。
• list: 列表框组件的列表插槽。您可以将此插槽视为 ul 插槽。
• emptyContent: 当集合为空时显示的插槽内容。

ListboxItem

• base: 列表框项目的主要插槽。它包裹所有其他插槽。
• wrapper: title 和 description 的包装器。
• title: 列表框项目的标题。
• description: 列表框项目的描述。
• selectedIcon: 选中的图标插槽。仅当选中该项目时才可见。

ListboxSection

• base: 列表框部分的主要插槽。它包裹所有其他插槽。
• heading: 渲染在部分组顶部的标题。
• group: 列表框项目的组。
• divider: 渲染在组之间的分隔符。仅当 showDivider 为 true 时才可见。

自定义列表框

您可以使用 itemClasses 属性并传递自定义 Tailwind CSS 类来自定义 Listbox 项目的样式。

注意：在上面的示例中，我们使用了 Boxicons 图标集合。

键盘交互

数据属性

ListboxItem 的 base 元素上具有以下属性

• data-disabled：当列表框项目被禁用时。基于列表框的 disabledKeys 属性。
• data-selected：当列表框项目被选中时。基于列表框的 selectedKeys 属性。
• data-selectable：当列表框项目可选时。基于列表框的 selectionMode 属性。
• data-hover：当鼠标悬停在列表框项目上时。基于 useHover
• data-pressed：当列表框项目被按下时。基于 usePress
• data-focus：当列表框项目被聚焦时。基于 useFocusRing。
• data-focus-visible：当使用键盘聚焦列表框项目时。基于 useFocusRing。

可访问性

• 使用 ARIA 作为 listbox 暴露给辅助技术。
• 支持单选、多选或不选。
• 支持禁用项。
• 支持分组。
• 为可访问性提供标签支持。
• 支持鼠标、触摸和键盘交互。
• 标签页停止焦点管理。
• 支持键盘导航，包括箭头键、Home/End、Page Up/Down、全选和清除。
• 键盘导航期间自动滚动支持。
• 允许通过键入文本来聚焦选项的键入提前查找。

API

Listbox Props

Listbox Events

ListboxSection Props

ListboxItem Props

ListboxItem Events

Types

Listbox Item Selected Icon Props