列表框

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

安装

npx nextui-cli@latest add listbox

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

导入

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

• 列表框: 主要组件，它是其他组件的包装器。
• 列表框节: 包含一组列表框项目的组件。
• 列表框项: 代表列表框项目的组件。

用法

动态项目

列表框遵循 集合组件 API，接受静态和动态集合。

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

禁用键

列表框项目可以使用 disabledKeys 属性禁用，该属性应用于 Listbox 组件。

注意：每个项目都必须具有唯一的键，否则禁用键将不起作用。

变体

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

单选

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

多选

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

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

带图标

可以使用 startContent / endContent 属性将图标添加到列表框项中。

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

带描述

您可以使用 description 道具为列表框项添加描述。

带顶部和底部内容

您可以使用 topContent 和 bottomContent 道具在列表框项的上面和下面添加内容。

带部分

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

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

路由

The <ListboxItem> 组件与框架和客户端路由器（如 Next.js 和 React Router）一起工作。请参阅 路由 指南，了解如何设置它。

import {Listbox, ListboxItem} from "@nextui-org/react";

function App() {
  return (
    <Listbox>
      <ListboxItem key="home" href="/home">
        Home
      </ListboxItem>
      <ListboxItem key="about" href="/about">
        About
      </ListboxItem>
    </Listbox>
  );
}

插槽

Listbox 有 3 个组件，它们有插槽，基本组件是 Listbox、ListboxItem 和 ListboxSection 组件。

Listbox

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

ListboxItem

• base: Listbox 项的主要插槽。它包装了所有其他插槽。
• 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 事件

类型

列表框项目选中图标属性

export type ListboxItemSelectedIconProps = {
  /**
   * The current icon, usually an checkmark icon.
   */
  icon?: ReactNode;
  /**
   * The current selected status.
   */
  isSelected?: boolean;
  /**
   * The current disabled status.
   * @default false
   */
  isDisabled?: boolean;
};

type selectedIcon?: ReactNode | ((props: ListboxItemSelectedIconProps) => ReactNode) | null;