定价

SelectButton

Figma 源代码

以按钮形式提供单项下拉选择，适合工具栏、筛选入口和需要紧凑展示的选项切换。

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

如何使用

用于按钮触发的选择或命令菜单。表单字段式单选用 Select；多项操作随宽度收纳用 OverflowActions。

  • options 提供唯一字符串 value；label 定制触发按钮文字，children 用来替换列表。

  • action 模式不更新 value 或触发 onchange；根级 Props 配置按钮，parts 不提供 Button 入口。

导入

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

用法

变体

API 参考

属性 类型 默认值 示例 描述
value SelectValue — value={value} 当前选中值（string、number 或 undefined），支持 bind:value；优先于 defaultValue，实际选项选择写入字符串。action 模式不保存选择。
defaultValue SelectValue — defaultValue={value} value 未定义时的回退选中值；仅 persistent 模式用于选择显示，首次选择后由 value 驱动。
options SelectOption[] [] options={options} 选项数据：每项包含字符串 value、label 及可选 disabled；默认生成 MenuItem。显式 children 提供列表时使用其选项注册。
placeholder string — placeholder="Search…" 未选中时的提示文字；action 模式触发器始终显示该文字。没有 label、选项文字或 placeholder 时触发器文字为空。
name string — name="Example" 表单字段名；仅提供非空 name 时创建 hidden input，提交当前选中值的字符串形式。
form string — form="Example" hidden input 所属表单的 id，可关联组件外部表单；仅设置 name 生成输入后生效。
required boolean false required 传入 Select 的必填标记；当前实现未将其接入原生约束校验，也不会阻止空值提交，业务需自行验证。
disabled boolean false disabled 禁用触发按钮并阻止打开或切换选项；当前 hidden input 不随该标记禁用，已有值仍可随表单提交。
readonly boolean false readonly 阻止用户通过触发器打开或改变选项，保留显示与外部 value 更新；不会禁用 hidden input。
invalid boolean false invalid 将无效状态传给 Select wrapper；当前 Button 触发器不自动增加错误边框或 aria-invalid，不能代替业务校验与错误说明。
ariaLabel string — ariaLabel="Example" 触发 Button 的可访问名称；不提供可见 label 时应设置。
showIndicator boolean true showIndicator 显示下拉指示器；false 时连同自定义 indicator 一起隐藏，选择能力不受影响。
search boolean false search 开启默认 Listbox 内置搜索；parts.Listbox.search 可覆盖。显式 children 模式应在自己的 Listbox 上配置搜索。
selectionMode "persistent" | "action" "persistent" selectionMode="persistent" persistent 保存选中值并显示选项文字；action 只触发 onAction、关闭列表且保持 placeholder，不更新 value 或触发 onchange。
label Snippet<[SelectButtonLabelContext]> — label={labelContent} 替换触发器文字；参数包含 value、option、label、placeholder，保留指示器和按钮交互。
indicator Snippet<[SelectButtonIndicatorContext]> — indicator={indicatorContent} 替换指示图形，参数为 open、disabled；仅 showIndicator=true 时渲染。
children Snippet — <SelectButton>Content</SelectButton> 显式 Listbox/MenuItem 内容，替换默认列表；不作为按钮文字使用，文字定制请用 label。
parts ComponentPartsOf<{ Listbox: typeof Listbox; Input: typeof Input; MenuItem: typeof MenuItem; }> — parts={partsOptions} 配置默认内建列表、搜索输入和选项；不提供 parts.Button，按钮样式在根级传入。显式 children 自行配置所属子项。
onchange (event: Event) => void — onchange={(value) => { /* handle value */ }} persistent 模式选中不同值后调用，参数为 change Event；用 bind:value 读取新值，重复选择与 action 模式不触发。
onAction (value: string) => void — onAction={(value) => { /* handle value */ }} 仅 action 模式在执行选项后接收其 value；列表随后保持关闭，组件不保存选中值。
onclick (event: MouseEvent) => void — onclick={(value) => { /* handle value */ }} 触发器完成打开或关闭后调用；disabled/readonly 时不调用，不能通过 preventDefault() 撤销已执行的切换。
onkeydown (event: KeyboardEvent) => void — onkeydown={(value) => { /* handle value */ }} 组件处理方向键、Enter、Escape 等选择键盘逻辑后调用；readonly 分支也会转交按键，不能据此取消已发生的内部操作。