Listbox 列表框

列表框用于显示选项列表并允许用户选择一个或多个选项。

安装

The above command is for individual installation only. You may skip this step if @heroui/react is already installed globally.

导入

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

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

用法

动态项目

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

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

禁用键

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

注意：必须为每个项目设置唯一键，否则禁用键将无法正常工作。

变体

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

单选

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

多选

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

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

带图标

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

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

带描述

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

带顶部和底部内容

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

带分组

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

注意：没有 title 的分组必须提供 aria-label 以确保可访问性。

路由

<ListboxItem> 组件可与 Next.js 和 React Router 等框架和客户端路由器配合使用。请参阅 路由 指南了解如何设置。

虚拟化

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

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

一万个项目

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

插槽

Listbox 有 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 属性

Listbox 事件

ListboxSection 属性

ListboxItem 属性

ListboxItem 事件

类型

Listbox Item 选中图标属性