Combobox

组合选择器（Combobox）是一种常见的输入模式，允许用户在弹出面板中通过关键词搜索并选择选项。它不是一个独立组件，而是由 Popover（弹出容器）、Command（可搜索列表）和 Button（触发器）三个组件组合实现。

import { Button, Command, Popover, cn } from '@skyroc/web-ui';

架构说明

Combobox 由三个组件协作完成：

Popover：提供弹出层容器，管理打开/关闭状态。
Command：数据驱动的可搜索列表，接收 items 数组自动渲染选项、分组和分隔符。
Button：作为 Popover 的 trigger，展示当前选中值和下拉指示器。

组合方式：

<Popover trigger={<Button>...</Button>}>
  <Command items={[...]} />
</Popover>

何时使用

选项较多（超过 5 个），需要搜索过滤时。
需要在弹出面板中展示结构化选项（分组、分隔符、快捷键）。
替代原生 <select>，需要更丰富的选项展示和交互。
与 Select 组件的区分：Combobox 侧重「搜索 + 选择」，Select 侧重「浏览 + 选择」。

基础用法

通过 Popover 包裹 Command，将 Button 作为触发器。Command 的 items 接收选项数组，每个选项包含 label（显示文本）和 value（匹配值）。

Preview

Code

API

Command

数据驱动的可搜索命令面板。继承 CommandRoot 的所有属性，支持通过 items 数组声明式渲染选项。

属性	说明	类型	默认值
items*	选项数据数组，支持 item、group、separator 三种类型	CommandOptionData[]	-
empty	无匹配结果时显示的内容	ReactNode	'No results.'
inputProps	传递给搜索输入框的属性	CommandInputProps	-
classNames	各 slot 的自定义 class	CommandClassNames	-
size	尺寸，影响所有子组件的字号与间距	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	'md'
className	根容器的 class，优先级低于 classNames.root	ClassValue	-

选项数据结构

items 数组中的每个元素通过 type 字段区分类型：

类型	说明	必填字段
`item`	可选择的选项（默认类型）	`label`
`group`	选项分组	`children`
`separator`	分隔线	`type` 必须显式

选项（item）

属性	说明	类型	默认值
label	选项显示文本	ReactNode	-
value	选项值，用于搜索匹配和选中标识	string	-
onSelect	选中时触发的回调	(value: string) => void	-
disabled	是否禁用	boolean	-
keywords	额外搜索关键词，不影响显示	string[]	-
leading	前置插槽，位于 label 之前	ReactNode	-
trailing	后置插槽，位于 label 之后	ReactNode	-
shortcut	关联的键盘快捷键	string \| string[]	-
className	选项的 class	ClassValue	-
size	选项尺寸	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	-

分组（group）

属性	说明	类型	默认值
children*	分组内的子选项数组	CommandOptionData[]	-
label	分组标题	ReactNode	-
className	分组容器的 class	ClassValue	-
classNames	分组内各 slot 的 class（group / groupLabel）	Pick<CommandClassNames, 'group' \| 'groupLabel'>	-

类型

CommandClassNames

Command 各 slot 的自定义 class 配置。

字段	类型	说明
root	ClassValue	根容器。
list	ClassValue	列表容器。
empty	ClassValue	空状态区域。
input	ClassValue	搜索输入框。
inputWrapper	ClassValue	输入框外层包裹区。
inputIcon	ClassValue	搜索图标。
item	ClassValue	选项行。
itemIcon	ClassValue	选项图标。
group	ClassValue	分组容器。
groupLabel	ClassValue	分组标题。
separator	ClassValue	分隔线。
shortcut	ClassValue	快捷键展示区。
dialog	ClassValue	对话框模式容器。

CommandInputProps

搜索输入框属性。继承 cmdk CommandInput 的属性，并增加 className、size 和 slot 插槽。

字段	类型	说明
placeholder	string	输入框占位文本。
value	string	受控搜索文本。
onValueChange	(search: string) => void	搜索文本变化时触发。
leading	ReactNode	前置插槽，默认为搜索图标。
trailing	ReactNode	后置插槽。
className	ClassValue	输入框 class。
classNames	Pick<CommandClassNames, 'input' \| 'inputIcon' \| 'inputWrapper'>	输入框相关 slot 的 class。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	输入框尺寸。

CommandItemOptionProps

选项数据结构。继承 CommandItem 的属性（排除 children），通过 label 显示文本。

字段	类型	说明
label	ReactNode	选项显示文本。
type	'item'	标识为选项类型，可省略。
value	string	选项值，用于搜索匹配。
onSelect	(value: string) => void	选中时回调。
disabled	boolean	是否禁用。
keywords	string[]	额外搜索关键词。
leading	ReactNode	前置插槽。
trailing	ReactNode	后置插槽。
shortcut	string \| string[]	关联键盘快捷键。
className	ClassValue	选项 class。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	选项尺寸。

CommandGroupOptionProps

分组数据结构。将多个选项归入同一分组，显示分组标题。

字段	类型	说明
children*	CommandOptionData[]	分组内的子选项数组。
label	ReactNode	分组标题文本。
type	'group'	标识为分组类型，可省略（含 children 字段时自动识别）。
className	ClassValue	分组容器 class。
classNames	Pick<CommandClassNames, 'group' \| 'groupLabel'>	分组内 slot class。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	分组尺寸。

CommandSeparatorOptionProps

分隔线数据结构。在选项列表中插入视觉分隔。

字段	类型	说明
type*	'separator'	标识为分隔线类型，必须显式指定。
className	ClassValue	分隔线 class。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	分隔线尺寸。

CommandOptionData

选项数据联合类型，每个元素可以是选项、分组或分隔线

CommandItemOptionProps | CommandGroupOptionProps | CommandSeparatorOptionProps

ClassValue

CSS 类名类型

string | null | undefined | Record<string, boolean> | ClassValue[]