Dropdown

Dropdown 是一个用于显示一组选项或操作的浮层组件。

Anatomy

NexUI 导出了 14 个 Dropdown 相关组件:

Dropdown: 用于显示 Dropdown 的根组件。
DropdownTrigger: 用于触发 Dropdown 打开的组件。
DropdownContent: 用于显示 Dropdown 内容的组件。
DropdownItem: 用于显示 Dropdown 选项的组件。
DropdownItemGroup: 用于分组 Dropdown 选项的组件。
DropdownItemGroupLabel: 用于显示 Dropdown 选项分组标签的组件。
DropdownRadioItemGroup: 用于显示 Dropdown 单选选项组的组件。
DropdownRadioItem: 用于显示 Dropdown 单选选项的组件。
DropdownCheckboxItemGroup: 用于显示 Dropdown 复选选项组的组件。
DropdownCheckboxItem: 用于显示 Dropdown 复选选项的组件。
DropdownTriggerItem: 用于触发子 Dropdown 打开的组件。
SubDropdown: 用于显示子 Dropdown 的根组件。
SubDropdownContent: 用于显示子 Dropdown 内容的组件。
DropdownDivider: 用于分隔 Dropdown 选项的组件。


import {
  Dropdown,
  DropdownTrigger,
  DropdownContent,
  DropdownItem,
  DropdownItemGroup,
  DropdownItemGroupLabel,
  DropdownRadioItemGroup,
  DropdownRadioItem,
  DropdownCheckboxItemGroup,
  DropdownCheckboxItem,
  DropdownTriggerItem,
  SubDropdown,
  SubDropdownContent,
  DropdownDivider,
} from '@nex-ui/react'

Usage

Colors

Variants

Placements

Link Items

Radio Items

Checkbox Items

Custom Trigger

With Shortcut

通过 DropdownItem 的 shortcut 属性，可以为 DropdownItem 显示一个快捷键提示。

With Groups

With Icons

使用 startIcon 和 endIcon 属性，可以在 DropdownItem 的开头和结尾添加图标。

Overflow

当 Dropdown 的内容过多时，可以通过设置 DropdownContent 的 maxHeight 属性来限制其最大高度，并启用滚动。

Prevent Closing

默认情况下，选择 DropdownItem 会关闭 Dropdown。通过设置 closeOnSelect 属性为 false，可以阻止 Dropdown 在选择项时关闭。

API

Prop	Type	Default	Description
children	ReactNode	-	通常是 DropdownTrigger、DropdownContent 等组件。
open	boolean	-	控制 Dropdown 的打开状态。(受控)
defaultOpen	boolean	-	Dropdown 的默认打开状态。(非受控)
onOpenChange	(open: boolean) => void	-	当 Dropdown 打开/关闭时触发回调函数。
onClose	() => void	-	Dropdown 关闭时执行的回调函数。

DropdownContent Props

DropdownContent 继承 as (默认为 'div') 的 Props。

Prop	Type	Default	Description
children	ReactNode	-	通常是 DropdownItem、DropdownItemGroup 等组件。
ref	Ref	-	Ref 用于转发到根元素。
className	ClassValue	-	用于根元素的 className。
as	ElementType	'div'	用于根元素的组件。可以是表示 HTML 元素的字符串，也可以是一个组件。
sx	Interpolation	-	用于根元素的 sx 属性。
slotProps	Partial<Record<Slots, ComponentProps>>	-	DropdownContent Slots 的 props。
classNames	Partial<Record<Slots, ClassValue>>	-	DropdownContent Slots 的 className。
container	HTMLElement\|null\|() => HTMLElement \| null	document.body	放置 Portal 的容器元素。
restoreFocus	boolean	true	当 Dropdown 关闭时，是否将焦点恢复到触发元素。
loopFocus	boolean	true	是否在 Dropdown 内循环焦点。
closeOnDetached	boolean	true	当触发元素被完全遮挡时是否关闭 Dropdown。
closeOnEscape	boolean	true	当按下 Escape 键时是否关闭 Dropdown。
flip	false\|{ mainAxis?: boolean; crossAxis?: boolean }	{ mainAxis: true, crossAxis: true }	更改 Dropdown 的位置，使其保持在视图中。
placement	'top'\|'top-start'\|'top-end'\|'bottom'\|'bottom-start'\|'bottom-end'\|'left'\|'left-start'\|'left-end'\|'right'\|'right-start'\|'right-end'	'bottom'	Dropdown 出现的位置。
offset	false\|number\|{ mainAxis?: number; crossAxis?: number }	5	设置 Dropdown 的偏移量，或禁用偏移。
shift	boolean	true	移动 Dropdown 以使其保持在可见范围内。
color	'blue'\|'orange'\|'yellow'\|'cyan'\|'red'\|'green'\|'pink'\|'purple'\|'gray'	gray	Dropdown 选项高亮时的颜色。
variant	'solid'\|'outlined'\|'ghost'\|'faded'	'solid'	Dropdown 选项高亮时的样式。
motionProps	HTMLMotionProps\|(placement: Placement) => HTMLMotionProps	-	自定义 Dropdown 进入/退出动画的属性。
disableAnimation	boolean	false	是否禁用 Dropdown 的动画效果。
keepMounted	boolean	false	是否在 Dropdown 关闭时保持内容挂载。
minWidth	string\|number	-	Dropdown 的最小宽度。
maxHeight	string\|number	-	Dropdown 的最大高度。

DropdownContent Slots

Slot Name	Class Name	Default Component	Description
paper	.nui-dropdown-content-paper	'div'	DropdownContent 的内容容器。

DropdownTrigger Props

Prop	Type	Default	Description
children	ReactElement	-	通常是一个按钮或其他可点击元素。
closeOnClick	boolean	true	点击触发元素时是否关闭 Dropdown。

DropdownItem Props

DropdownItem 继承 as (默认为 'div') 的 Props。

Prop	Type	Default	Description
children	ReactNode	-	DropdownItem 的内容。
ref	Ref	-	Ref 用于转发到根元素。
className	ClassValue	-	用于根元素的 className。
as	ElementType	'div'	用于根元素的组件。可以是表示 HTML 元素的字符串，也可以是一个组件。
sx	Interpolation	-	用于根元素的 sx 属性。
slotProps	Partial<Record<Slots, ComponentProps>>	-	DropdownItem Slots 的 props。
classNames	Partial<Record<Slots, ClassValue>>	-	DropdownItem Slots 的 className。
disabled	boolean	false	是否禁用 DropdownItem。
closeOnSelect	boolean	true	选择该项时是否关闭 Dropdown。
shortcut	ReactNode	-	显示在 DropdownItem 右侧的快捷键提示文本。
startIcon	ReactNode	-	显示在 DropdownItem 开头的图标。
endIcon	ReactNode	-	显示在 DropdownItem 结尾的图标。
color	'blue'\|'orange'\|'yellow'\|'cyan'\|'red'\|'green'\|'pink'\|'purple'\|'gray'	gray	当 DropdownItem 高亮时使用的颜色。
variant	'solid'\|'outlined'\|'ghost'\|'faded'	'solid'	当 DropdownItem 高亮时使用的样式。
onSelect	(event: MouseEvent<HTMLDivElement>) => void	-	选择该项时触发的回调函数。

DropdownItem Slots

Slot Name	Class Name	Default Component	Description
content	.nui-dropdown-item-content	'span'	DropdownItem 的内容容器。
shortcut	.nui-dropdown-item-shortcut	'kbd'	DropdownItem 的快捷键提示容器。
startIcon	.nui-dropdown-item-start-icon	'span'	DropdownItem 的开头图标容器。
endIcon	.nui-dropdown-item-end-icon	'span'	DropdownItem 的结尾图标容器。

DropdownItemGroup Props

DropdownItemGroup 继承 as (默认为 'div') 的 Props。

Prop	Type	Default	Description
children	ReactNode	-	DropdownItemGroup 的内容，通常是 DropdownItem、DropdownItemGroupLabel 等。
ref	Ref	-	Ref 用于转发到根元素。
className	ClassValue	-	用于根元素的 className。
as	ElementType	'div'	用于根元素的组件。可以是表示 HTML 元素的字符串，也可以是一个组件。
sx	Interpolation	-	用于根元素的 sx 属性。

DropdownItemGroupLabel Props

DropdownItemGroupLabel 继承 as (默认为 'div') 的 Props。

Prop	Type	Default	Description
children	ReactNode	-	DropdownItemGroupLabel 的内容。
ref	Ref	-	Ref 用于转发到根元素。
className	ClassValue	-	用于根元素的 className。
as	ElementType	'div'	用于根元素的组件。可以是表示 HTML 元素的字符串，也可以是一个组件。
sx	Interpolation	-	用于根元素的 sx 属性。

DropdownRadioItemGroup Props

DropdownRadioItemGroup 继承 DropdownItemGroup 的 Props。

Prop	Type	Default	Description
value	T	-	当前选中的值。
onValueChange	(value: T) => void	-	当选中项改变时触发的回调函数。

DropdownRadioItem Props

DropdownRadioItem 继承 DropdownItem 的 Props。

Prop	Type	Default	Description
value	string\|number	-	该项的值。
indicator	ReactNode	-	自定义 DropdownRadioItem 选中状态指示器。

DropdownRadioItem Slots

DropdownRadioItem Slots 包括 DropdownItem 的所有 Slots，以及:

Slot Name	Class Name	Default Component	Description
indicator	.nui-dropdown-radio-item-indicator	'span'	DropdownRadioItem 的选中状态指示器容器。

DropdownCheckboxItemGroup Props

DropdownCheckboxItemGroup 继承 DropdownItemGroup 的 Props。

Prop	Type	Default	Description
value	T[]	-	当前选中的值数组。
onValueChange	(value: T[]) => void	-	当选中项改变时触发的回调函数。

DropdownCheckboxItem Props

DropdownCheckboxItem 继承 DropdownItem 的 Props。

Prop	Type	Default	Description
value	string\|number	-	该项的值。
onCheckedChange	(checked: boolean) => void	-	当选中状态变化时触发的回调函数。
indicator	ReactNode	-	自定义 DropdownCheckboxItem 选中状态指示器。

DropdownCheckboxItem Slots

DropdownCheckboxItem Slots 包括 DropdownItem 的所有 Slots，以及:

Slot Name	Class Name	Default Component	Description
indicator	.nui-dropdown-checkbox-item-indicator	'span'	DropdownCheckboxItem 的选中状态指示器容器。

DropdownDivider Props

DropdownDivider 继承 as (默认为 'hr') 的 Props。

Prop	Type	Default	Description
ref	Ref	-	Ref 用于转发到根元素。
className	ClassValue	-	用于根元素的 className。
as	ElementType	'hr'	用于根元素的组件。可以是表示 HTML 元素的字符串，也可以是一个组件。
sx	Interpolation	-	用于根元素的 sx 属性。

DropdownTriggerItem Props

DropdownTriggerItem 继承 DropdownItem 的 Props。

SubDropdown Props

SubDropdown 继承 Dropdown 的 Props。

SubDropdownContent Props

SubDropdownContent 的 API 与 DropdownContent 基本一致，但不支持 restoreFocus、closeOnEscape 和 placement。