定价

Select

Figma 源代码

在下拉列表中选择选项，可由数据直接生成面板，也可自定义选项组合，支持搜索与键盘操作。

我们正在让 SnowUI 组件成为 AI 对话中可直接操作的界面。目前对话交互能力仍在建设中；本页展示网站用法，支持的对话平台与组件版本将在验证后公布。 AI 对话内生成和使用 SnowUI 界面完全免费，不属于项目，不占项目或开发者席位额度，无需 SnowUI 注册、激活或付费证明。

如何使用

用于下拉单选。默认传 options 生成 Listbox / MenuItem；显式 children 替换默认选项面板。命令菜单优先 SelectButton；不是任意多选或自由输入控件。

  • options 默认生成列表；显式 children 提供 Listbox / MenuItem 后替换默认列表。

  • persistent 保存选择；action 只调用 onAction 并关闭，不保存本次选择。默认子项用 parts，显式子项直接配置。

  • 列表通过 Escape 关闭后，字段型与 buttonTrigger／SelectButton 模式均恢复真实触发按钮焦点；搜索头关闭行为由共享 Listbox 管理。

导入

import { Select } from '@snowui-design-system/components';

用法

默认值

禁用状态

无效状态

绑定

表单

加载中

状态

按钮触发

内置选项

选中标记

API 参考

属性 类型 默认值 示例 描述
value SelectValue — value={value} 当前值，支持 bind:value
gap number — gap={42} 继承 Frame 的间距 token 索引；省略时保留组件原首选间距，显式值覆盖首选间距，有效图文间距仍至少为 4 CSS px；显式零和根字号／间距缩放不压低下限。
defaultValue SelectValue — defaultValue={value} 初始值
placeholder string — placeholder="Search…" 空值占位文字，显示在 Trigger 中
name string — name="Example" 表单提交字段名
disabled boolean false disabled 禁用状态
readonly boolean false readonly 只读状态
required boolean false required 必填状态
form string — form="Example" 指定外部表单归属
autofocus boolean — autofocus 首次渲染自动聚焦
tabindex number — tabindex={42} Tab 顺序
title string — title="Example" 原生提示
id string — id="example" 原生 id
invalid boolean false invalid 组件级无效态
children Snippet — <Select>Content</Select> <Listbox> + <MenuItem> 组合内容
options SelectOption[] [] options={options} 默认内置列表数据，字段遵循 ListboxItem；传入显式 children 时不渲染该默认列表。
triggerContent Snippet<[SelectTriggerContext]> — triggerContent={triggerContentContent} buttonTrigger 开启时替换触发按钮内容；接收 value、option、label、placeholder、open、disabled。
buttonTrigger boolean false buttonTrigger 使用 Button 代替字段型触发器；保留展开、选择与焦点恢复协议。
buttonBare boolean true buttonBare 只在 buttonTrigger 模式生效，控制内置 Button 是否为无外壳 bare 外观。
selectionMode "persistent" | "action" "persistent" selectionMode="persistent" persistent 保存选择值；action 只执行 onAction、关闭面板并恢复触发器焦点，不保存本次选项。
onAction (value: string) => void — onAction={(value) => { /* handle value */ }} action 模式选择选项后调用，参数为字符串选项值；此时面板已关闭，返回值不参与选择。
parts SelectParts — parts={partsOptions} 配置默认 Listbox、Input、MenuItem 与按钮触发器；显式 child 不消费父级 parts。
ariaLabel string — ariaLabel="Example" 触发器的可访问名称；按钮触发模式无自定义内容时也作为后备显示内容。
onclick (event: MouseEvent) => void — onclick={(value) => { /* handle value */ }} 非 disabled、非 readonly 的触发器点击切换展开状态后调用，接收原始 MouseEvent。
oninput (event: Event) => void — oninput={(value) => { /* handle value */ }} persistent 模式选择了不同值时调用，接收隐藏表单输入派发的 change Event；实际新值从绑定 value 读取，不是原生文本输入过程。
onchange (event: Event) => void — onchange={(value) => { /* handle value */ }} persistent 模式选择值改变后调用，接收同一次 change Event；相同值与 action 模式不触发。
onfocus (event: FocusEvent) => void — onfocus={(value) => { /* handle value */ }} 字段型触发器取得焦点时调用，接收 FocusEvent；按钮触发模式不使用此直接处理器。
onblur (event: FocusEvent) => void — onblur={(value) => { /* handle value */ }} 字段型触发器失去焦点时调用，接收 FocusEvent；按钮触发模式不使用此直接处理器。
onkeydown (event: KeyboardEvent) => void — onkeydown={(value) => { /* handle value */ }} 触发器的内置方向键、Enter/Space 和 Escape 处理后调用，接收 KeyboardEvent；不能撤销已处理的动作。
onkeyup (event: KeyboardEvent) => void — onkeyup={(value) => { /* handle value */ }} 字段型触发器松开按键时调用，接收 KeyboardEvent；按钮触发模式不使用此直接处理器。