Select 选择器
从有限候选列表中选择一个值，并在触发器中显示当前结果。
使用概览
适合使用
- 选项较多但无需文本搜索，且页面空间有限时。
不建议使用
- 用户需要同时比较所有选项，或允许输入列表外的新值时。
真实示例
团队下拉选择
从两个有限团队选项中选择一个值。
正在加载示例…
安装
本地候选警告Registry 地址仅指向当前本地文档站；npm 包也只用于本地候选验证，尚未公开发布。
pnpm dlx shadcn@4.16.0 add http://127.0.0.1:3000/r/select.json基础用法
导入
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from "@richardqiu/quartz/select";JSX
<Select defaultValue="design" name="team"><SelectTrigger aria-label="团队"><SelectValue placeholder="选择团队" /></SelectTrigger><SelectContent><SelectItem value="design">设计</SelectItem><SelectItem value="engineering">工程</SelectItem></SelectContent></Select>状态与控制摘要
默认
悬停
键盘焦点可见
激活
已禁用
无效
已选择
已打开
已关闭
label · textactive · booleanAPI 参考
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value | string | 未设置 | 受控指定当前选中的项目值。 |
组合结构
- 01
Select - 02
SelectTrigger - 03
SelectValue - 04
SelectContent - 05
SelectGroup - 06
SelectLabel - 07
SelectItem - 08
SelectSeparator
键盘约定
- 上下方向键打开列表并移动焦点，Enter 选择，Escape 取消并把焦点还给触发器。
- 可打印字符支持预输入定位，但不会选中禁用项。
可访问性契约
- SelectTrigger 必须具备可访问名称，列表框由实际触发器或显式标签命名。
- 禁用、选中、必填、无效与占位状态以 Radix 和 Quartz 的语义输出为准。
- 粗指针目标至少为 44px；强制颜色、透明度降级和 RTL 布局均保留可读性。