列表框

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

安装

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

导入

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

• Listbox：主组件，是其他组件的包装器。
• ListboxSection：包含一组列表框项目的组件。
• ListboxItem：表示列表框项目的组件。

用法

动态项目

Listbox 遵循 Collection Components API，接受静态和动态集合。

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

禁用键

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

注意：为每个项目设置唯一的 key 非常重要，否则禁用的 key 将无法工作。

变体

你可以使用 Listbox 组件中的 variant 属性来更改列表框项目的 hover 样式。

单选

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

多选

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

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

带图标

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

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

带描述

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

带顶部和底部内容

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

带 Sections

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

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

路由

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

虚拟化

Select 支持虚拟化，这可以通过仅渲染视口中可见的项目来高效渲染大型列表。 你可以通过将 isVirtualized 属性设置为 true 来启用虚拟化。

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

一万个项目

这是一个使用虚拟化处理 10,000 个项目的示例。

插槽

Listbox 有 3 个带有插槽的组件：基础组件 Listbox、ListboxItem 和 ListboxSection 组件。

Listbox

• base：listbox 组件的主要包装器。此插槽包装了 topContent、bottomContent 和 list 插槽。
• list：listbox 组件的插槽。你可以将此插槽视为 ul 插槽。
• emptyContent：当集合为空时要显示的插槽内容。

ListboxItem

• base：listbox 项目的主要插槽。它包装了所有其他插槽。
• wrapper：title 和 description 的包装器。
• title：listbox 项目的标题。
• description：listbox 项目的描述。
• selectedIcon：选定图标插槽。仅当项目被选中时才可见。

ListboxSection

• base：listbox section 的主要插槽。它包装了所有其他插槽。
• heading：渲染在 section 组顶部的标题。
• group：listbox 项目组。
• divider：渲染在组之间的分隔线。仅当 showDivider 为 true 时才可见。

自定义 listbox

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

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

键盘交互

数据属性

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

• data-disabled：当 listbox 项目被禁用时。基于 listbox 的 disabledKeys 属性。
• data-selected：当 listbox 项目被选中时。基于 listbox 的 selectedKeys 属性。
• data-selectable：当 listbox 项目可选择时。基于 listbox 的 selectionMode 属性。
• data-hover：当 listbox 项目被悬停时。基于 useHover
• data-pressed：当 listbox 项目被按下时。基于 usePress
• data-focus：当 listbox 项目被聚焦时。基于 useFocusRing。
• data-focus-visible：当 listbox 项目通过键盘聚焦时。基于 useFocusRing。

可访问性

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

API

Listbox 属性

Listbox 事件

ListboxSection 属性

ListboxItem 属性

ListboxItem 事件

类型

Listbox Item Selected Icon 属性