Select

Select 组件显示可折叠的选项列表，并允许用户选择一个或多个选项。

安装

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

导入

HeroUI 导出 3 个与 Select 相关的组件

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

用法

动态项目

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

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

多选

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

禁用

禁用项目

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

必填

如果您将 isRequired 属性传递给 select 组件，则标签末尾将显示一个 danger 星号，并且该 select 组件将变为必填。

尺寸

颜色

变体

圆角

标签位置

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

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

启动内容

您可以使用 startContent 和 endContent 属性向 select 组件的开头和结尾添加内容。

列表项开头和结尾内容

由于 Select 组件底层使用了 Listbox 组件，因此您可以使用 SelectItem 组件的 startContent 和 endContent 属性向 select 列表项的开头和结尾添加内容。

自定义选择器图标

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

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

没有滚动阴影

Select 组件底层使用了 ScrollShadow 组件，以便在 select 内容可滚动时显示阴影。您可以使用 scrollShadowProps 属性禁用此阴影。

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

带有描述

您可以通过传递 description 属性向 select 组件添加描述。

带有错误消息

您可以结合使用 isInvalid 和 errorMessage 属性来显示无效的 select 组件。

受控

您可以使用 selectedKeys 和 onSelectionChange / onChange 属性来控制 select 组件的值。

使用 onSelectionChange

使用 onChange

控制打开状态

您可以使用 isOpen 和 onOpenChange / onClose 属性来控制 select 组件的打开状态。

自定义列表项

您可以通过修改 SelectItem 的子元素来自定义 select 列表项。

自定义渲染值

默认情况下，select 组件将渲染所选列表项的文本值，但是您可以通过传递 renderValue 函数来自定义此行为。

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

异步加载

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

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

虚拟化

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

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

一万个列表项

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

列表框最大高度

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

自定义列表项高度

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

带有 sections

您可以使用 SelectSection 组件对 select 列表项进行分组。

自定义 sections 样式

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

多选受控

您可以使用与单选 select 相同的属性来控制多选 select，即 selectedKeys 和 onSelectionChange / onChange。

使用 onSelectionChange

使用 onChange

多选带 Chips

您可以使用 renderValue 属性将任何组件渲染为 select 的值。在此示例中，我们使用 Chip 组件来渲染所选的列表项。

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

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

自定义 select 组件

您可以使用 classNames 属性来自定义 select 组件的任何 slot。Select 组件还提供了 popoverProps 和 listboxProps 属性来自定义 popover 和 listbox 组件。

Slots

• base：select 组件的主包装器。它包装了其余的 slots。
• label：select 组件的标签。
• mainWrapper：包装了 helperWrapper 和 trigger slots。
• trigger：select 组件的触发器。它包装了标签、内部包装器和选择器图标。
• innerWrapper：select 内容的包装器。它包装了开头/结尾内容和 select 值。
• selectorIcon：select 组件的选择器图标。这是在 select 打开时旋转的图标 (data-open)。
• value：select 的值。这也是包装 renderValue 函数结果的 slot。
• listboxWrapper：listbox 的包装器。它包装了 listbox 组件，此 slot 用于滚动阴影组件之上。
• listbox：listbox 组件。这是包装 select 列表项的组件。
• popoverContent：popover 内容 slot。使用此 slot 修改 popover 内容的样式。
• helperWrapper：辅助文本的包装器。它包装了辅助文本和错误消息。
• description：select 组件的描述。
• errorMessage：select 组件的错误消息。

数据属性

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

• data-filled：指示 select 组件是否具有值、是否聚焦、是否具有开头/结尾内容或是否打开。
• data-has-value：指示 select 组件是否已选择列表项。
• data-has-label：指示 select 组件是否具有标签。基于 label 属性。
• data-has-helper：指示 select 组件是否具有辅助文本。基于 errorMessage 或 description 属性。
• data-invalid：指示 select 组件是否无效。基于 isInvalid 属性。

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

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

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

• data-open：指示 select 组件是否打开。

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

• data-disabled: 当选择项被禁用时。基于 select disabledKeys 属性。
• data-selected: 当选择项被选中时。基于 select selectedKeys 属性。
• data-hover: 当鼠标悬停在选择项上时。基于 useHover
• data-pressed: 当选择项被按下时。基于 usePress
• data-focus: 当选择项被聚焦时。基于 useFocusRing。
• data-focus-visible: 当使用键盘聚焦选择项时。基于 useFocusRing。

无障碍性

• 作为带有 ARIA 的列表框弹出按钮暴露给辅助技术（结合 Listbox）。
• 支持选择单个选项。
• 支持选择多个选项。
• 支持禁用选项。
• 支持分 sections。
• 标签支持无障碍性。
• 支持通过 ARIA 链接到输入框的描述和错误消息帮助文本。
• 支持鼠标、触摸和键盘交互。
• Tab 键焦点管理。
• 键盘支持使用箭头键打开列表框，包括自动聚焦第一个或最后一个项目。
• Typeahead 允许通过输入文本来选择选项，即使不打开列表框。
• 通过隐藏的原生 <select> 元素集成浏览器自动填充。
• 移动端屏幕阅读器列表框关闭支持。

API

Select Props

Select Events

SelectItem Props

查看 ListboxItem props。

SelectItem Events

查看 ListboxItem events。

SelectSection Props

查看 ListboxSection props。

类型

Render Value Function

T 类型是传递给 select items 的数据类型。