选择

选择器显示一个可折叠的选项列表，并允许用户选择其中一个或多个。

安装

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

导入

NextUI 导出了 3 个与选择相关的组件

• Select: 主要组件，是其他组件的包装器。
• SelectSection: 包含一组选择项的组件。
• SelectItem: 表示一个选择项的组件。

用法

动态项

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

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

多选

您可以使用 selectionMode="multiple" 属性允许多选。

禁用

禁用项

您可以使用 disabledKeys 属性禁用特定项。

必填

如果将 isRequired 属性传递给选择器，则标签末尾将有一个 danger 星号，并且该选择器将为必填项。

尺寸

颜色

变体

圆角

标签位置

您可以通过将 labelPlacement 属性设置为 inside、 outside 或 outside-left 来更改标签的位置。

注意：如果未传递 label，则 labelPlacement 属性将默认为 outside。

起始内容

您可以使用 startContent 和 endContent 属性来在选择器的开头和结尾添加内容。

项目起始和结束内容

由于 Select 组件在底层使用了 Listbox 组件，您可以使用 SelectItem 组件的 startContent 和 endContent 属性来在选择项的开头和结尾添加内容。

自定义选择器图标

默认情况下，选择器使用 chevron-down 图标作为选择器图标，该图标在选择器打开时会旋转。您可以通过将自定义图标传递给 selectorIcon 属性来自定义此图标。

注意：使用 disableSelectorIconRotation 属性来禁用图标的旋转。

无滚动阴影

选择器组件在底层使用 ScrollShadow，当选择器内容可滚动时显示阴影。您可以使用 scrollShadowProps 属性来禁用此阴影。

注意：您还可以使用 showScrollIndicators 属性来禁用滚动指示器。

带描述

您可以通过传递 description 属性来为选择器添加描述。

带错误消息

您可以组合使用 isInvalid 和 errorMessage 属性来显示无效的选择器。

受控

您可以使用 selectedKeys 和 onSelectionChange / onChange 属性来控制选择值。

使用 onSelectionChange

使用 onChange

控制打开状态

您可以使用 isOpen 和 onOpenChange / onClose 属性来控制选择器的打开状态。

自定义项

您可以通过修改 SelectItem 子元素来自定义选择项。

自定义渲染值

默认情况下，选择器将渲染所选项的文本值，但您可以通过传递一个 renderValue 函数来自定义此行为。

renderValue 函数接收所选项作为参数，并且必须返回一个 ReactNode。有关更多详细信息，请查看 渲染值函数 部分。

异步加载

选择器支持异步加载，在下面的示例中，我们使用自定义 Hook 来获取 Pokemon API 数据，并结合 useInfiniteScroll Hook 在用户到达列表末尾时加载更多数据。

当数据正在获取时，isLoading 属性用于显示加载指示器，而不是选择器图标。

虚拟化

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

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

一万个项目

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

最大列表框高度

maxListboxHeight 属性用于设置列表框的最大高度。使用虚拟化时，这是必需的。默认情况下，它设置为 256。

自定义项目高度

itemHeight 属性用于设置列表框中每个项目的高度。使用虚拟化时，这是必需的。默认情况下，它设置为 32。

带分区

您可以使用 SelectSection 组件对选择项进行分组。

自定义分区样式

您可以使用 SelectSection 组件的 classNames 属性来自定义分区样式。

多选控制

你可以使用与单选相同的属性来控制多选，例如 selectedKeys 和 onSelectionChange / onChange。

使用 onSelectionChange

使用 onChange

带有标签的多选

你可以通过使用 renderValue 属性将任何组件渲染为选择的值。 在此示例中，我们使用 Chip 组件来渲染选定的项目。

注意：请确保将 isMultiline 属性传递给 Select 组件，以允许标签换行。

renderValue 函数接收所选项作为参数，并且必须返回一个 ReactNode。有关更多详细信息，请查看 渲染值函数 部分。

自定义选择器

你可以使用 classNames 属性自定义选择器的任何插槽。选择器组件还提供了 popoverProps 和 listboxProps 属性来自定义弹出框和列表框组件。

插槽

• base: 选择器的主要包装器。它包裹着其余的插槽。
• label: 选择器的标签。
• mainWrapper: 包裹 helperWrapper 和 trigger 插槽。
• trigger: 选择器的触发器。它包裹标签、内部包装器和选择器图标。
• innerWrapper: 选择器内容的包装器。它包裹开始/结束内容和选择值。
• selectorIcon: 选择器的选择器图标。这是当选择器打开时旋转的图标（data-open）。
• value: 选择值。这也是包裹 renderValue 函数结果的插槽。
• listboxWrapper: 列表框的包装器。它包裹列表框组件，此插槽在滚动阴影组件之上使用。
• listbox: 列表框组件。这是包裹选择项的组件。
• popoverContent: 弹出框内容插槽。使用此项来修改弹出框内容的样式。
• helperWrapper: 辅助文本的包装器。它包裹辅助文本和错误消息。
• description: 选择器的描述。
• errorMessage: 选择器的错误消息。

数据属性

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

• data-filled: 指示选择器是否有值、是否聚焦、是否有开始/结束内容或是否打开。
• data-has-value: 指示选择器是否已选择项目。
• data-has-label: 指示选择器是否具有标签。基于 label 属性。
• data-has-helper: 指示选择器是否具有辅助文本。基于 errorMessage 或 description 属性。
• data-invalid: 指示选择器是否无效。基于 isInvalid 属性。

Select 在 trigger 元素上具有以下属性

• data-open: 指示选择器是否打开。
• data-disabled: 当选择器触发器被禁用时。基于选择器 isDisabled 属性。
• data-focus: 当选择器触发器正在被聚焦时。基于 useFocusRing。
• data-focus-visible: 当选择器触发器正在使用键盘聚焦时。基于 useFocusRing。
• data-pressed: 当选择器触发器被按下时。基于 usePress
• data-hover: 当选择触发器被悬停时。基于 useHover

Select 在 selectorIcon 元素上具有以下属性

• data-open: 指示选择器是否打开。

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

• data-disabled: 当选择项被禁用时。基于选择器的 disabledKeys 属性。
• data-selected: 当选择项被选中时。基于选择器的 selectedKeys 属性。
• data-hover: 当选择项被悬停时。基于 useHover
• data-pressed: 当选择项被按下时。基于 usePress
• data-focus: 当选择项获得焦点时。基于 useFocusRing。
• data-focus-visible: 当使用键盘使选择项获得焦点时。基于 useFocusRing。

可访问性

• 作为带有列表框弹出窗口的按钮，使用 ARIA (与 Listbox 结合使用) 暴露给辅助技术。
• 支持选择单个选项。
• 支持选择多个选项。
• 支持禁用选项。
• 支持节。
• 支持用于辅助功能的标签。
• 支持通过 ARIA 链接到输入的描述和错误消息帮助文本。
• 支持鼠标、触摸和键盘交互。
• 制表符焦点管理。
• 支持使用箭头键打开列表框的键盘支持，包括自动聚焦第一个或最后一个项目。
• 允许通过键入文本选择选项的预键入功能，即使不打开列表框也可以。
• 通过隐藏的本地 <select> 元素集成浏览器自动填充。
• 支持移动屏幕阅读器列表框关闭。

API

选择属性

选择事件

选择项属性

查看 ListboxItem 属性。

选择项事件

查看 ListboxItem 事件。

选择节属性

查看 ListboxSection 的属性。

类型

渲染值函数

T 类型是传递给选择器 items 的数据类型。