选择

The renderValue function receives the selected items as a parameter and must return a ReactNode. Check the Render Value Function section for more details.

异步加载

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

The isLoading prop is used to show a loading indicator instead of the selector icon when the data is being fetched.

npm install @nextui-org/use-infinite-scroll

import {useInfiniteScroll} from "@nextui-org/use-infinite-scroll";

带节

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

自定义部分样式

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

多选控制

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

使用 onSelectionChange

使用 onChange

带芯片的多选

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

注意: 确保将 isMultiline 属性传递给 Select 组件以允许芯片换行。

The renderValue function receives the selected items as a parameter and must return a ReactNode. Check the Render Value Function section for more details.

自定义选择

您可以使用 classNames 属性自定义选择的任何插槽。Select 组件还提供 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

Select 属性

属性	类型	描述	默认值
children*	`ReactNode[]`	要渲染的子元素。通常是 `SelectItem` 和 `SelectSection` 元素的列表。	-
items	`Iterable<T>`	选择中的项目对象。（动态）	-
selectionMode	`single` \| `multiple`	集合中允许的选择类型。	-
selectedKeys	`all` \| `React.Key[]`	集合中当前选中的键（受控）。	-
disabledKeys	`all` \| `React.Key[]`	被禁用的项目键。这些项目不能被选中、聚焦或以其他方式交互。	-
defaultSelectedKeys	`all` \| `React.Key[]`	集合中最初选中的键（不受控）。	-
variant	`flat` \| `bordered` \| `faded` \| `underlined`	选择的变体。	`flat`
color	`default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger`	选择框的颜色。	`default`
大小	`sm` \| `md` \| `lg`	选择框的大小。	`md`
圆角	`none` \| `sm` \| `md` \| `lg` \| `full`	选择框的圆角。	-
占位符	`string`	选择框的占位符。	`选择一个选项`
标签位置	`inside` \| `outside` \| `outside-left`	标签的位置。	`inside`
标签	`ReactNode`	作为标签显示的内容。	-
描述	`ReactNode`	选择框的描述。提供提示，例如对选择内容的具体要求。	-
错误信息	`ReactNode` \| `((v: ValidationResult) => ReactNode)`	选择框的错误信息。	-
开始内容	`ReactNode`	渲染在选择框左侧的元素。	-
结束内容	`ReactNode`	渲染在选择框右侧的元素。	-
选择器图标	`ReactNode`	渲染为选择器图标的元素。	-
scrollRef	`React.RefObject<HTMLElement>`	可滚动元素的引用。	-
spinnerRef	`React.RefObject<HTMLElement>`	加载动画元素的引用。	-
fullWidth	`boolean`	选择器是否应占据其父元素的宽度。	`true`
isOpen	`boolean`	选择器是否默认打开（受控）。	-
defaultOpen	`boolean`	选择器是否默认打开（非受控）。	-
isRequired	`boolean`	在提交表单之前，是否需要用户在选择器中进行选择。	`false`
isDisabled	`boolean`	选择器是否被禁用。	`false`
isMultiline	`boolean`	选择器是否应允许多行文本。	`false`
isInvalid	`boolean`	选择器是否无效。	`false`
validationState	`valid` \| `invalid`	选择器是否应显示其“有效”或“无效”的视觉样式。（已弃用）请使用 isInvalid 代替。	-
showScrollIndicators	`boolean`	选择器在列表框可滚动时是否应显示滚动指示器。	`true`
autoFocus	`boolean`	选择器是否应在首次挂载时获得焦点。	`false`
disallowEmptySelection	`boolean`	集合是否允许空选择。	`false`
disableAnimation	`boolean`	选择器是否应进行动画。	`true`
disableSelectorIconRotation	`boolean`	选择器是否应禁用选择器图标的旋转。	`false`
popoverProps	PopoverProps	要传递给弹出框组件的属性。	-
listboxProps	ListboxProps	要传递给列表框组件的属性。	-
scrollShadowProps	ScrollShadowProps	要传递给滚动阴影组件的属性。	-
classNames	`Record<"base"｜ "label"｜ "trigger"｜ "mainWrapper" ｜ "innerWrapper"｜ "selectorIcon" ｜ "value" ｜ "listboxWrapper"｜ "listbox" ｜ "popoverContent" ｜ "helperWrapper" ｜ "description" ｜ "errorMessage", string>`	允许为选择器插槽设置自定义类名。	-

选择器事件

属性	类型	描述
onClose	`() => void`	选择弹出框关闭时触发的回调函数。
onOpenChange	`(isOpen: boolean) => void`	选择弹出框打开或关闭时触发的回调函数。
onSelectionChange	`(keys: React.Key[]) => void`	选中键值改变时触发的回调函数。
onChange	`React.ChangeEvent<HTMLSelectElement>`	原生选择改变事件，在选中值改变时触发。
renderValue	RenderValueFunction	用于渲染选择框值的函数。默认情况下，它渲染选中的项目。

SelectItem Props

查看 ListboxItem 属性。

SelectItem Events

查看 ListboxItem 事件。

SelectSection Props

查看 ListboxSection 属性。

类型

渲染值函数

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

export type SelectedItemProps<T> = {
  /** A unique key for the item. */
  key?: Key;
  /** The props passed to the item. */
  props?: Record<string, any>;
  /** The item data. */
  data?: T | null;
  /** An accessibility label for this item. */
  "aria-label"?: string;
  /** The rendered contents of this item (e.g. JSX). */
  rendered?: ReactNode;
  /** A string value for this item, used for features like typeahead. */
  textValue?: string;
  /** The type of item this item represents. */
  type?: string;
};

type SelectedItems<T> = Array<SelectedItemProps<T>>;

renderValue: (items: SelectedItems<T>) => ReactNode;