shadcn/ui Select 组件完全指南

本文介绍 shadcn/ui 的 Select 组件，这是一个基于 Radix UI 构建的下拉选择组件，提供了丰富的功能和灵活的配置选项，帮助开发者快速构建美观且易用的选择器界面。

组件简介

Select 组件显示一个选项列表供用户选择，通过按钮触发下拉菜单。它是表单和设置界面中最常用的交互元素之一。

shadcn/ui 的 Select 组件基于 Radix UI 的 Select Primitive 构建，具有以下特点：

无障碍支持：完整的键盘导航和 ARIA 属性支持
高度可定制：通过 Tailwind CSS 轻松自定义样式
TypeScript 支持：完整的类型定义
RTL 支持：内置从右到左语言支持
动画效果：流畅的展开/收起动画

安装

使用 CLI 安装（推荐）

bash

npx shadcn add select

手动安装

如果需要通过手动方式安装，可以参考官方文档的详细步骤。

使用方法

基础用法

tsx

import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

<Select>
  <SelectTrigger className="w-[180px]">
    <SelectValue placeholder="Theme" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectItem value="light">Light</SelectItem>
      <SelectItem value="dark">Dark</SelectItem>
      <SelectItem value="system">System</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

组件结构

Select：根组件，管理选择器状态
SelectTrigger：触发按钮，显示当前选中值或占位符
SelectValue：显示当前选中的值
SelectContent：下拉内容容器
SelectGroup：选项分组
SelectItem：单个选项
SelectLabel：分组标签
SelectSeparator：分隔线

示例

对齐方式

使用 position 属性控制下拉菜单的对齐方式：

position="item-aligned"（默认）：选中的项目与触发器对齐
position="popper"：下拉菜单与触发器边缘对齐

tsx

<Select>
  <SelectTrigger>
    <SelectValue placeholder="Select a fruit" />
  </SelectTrigger>
  <SelectContent position="popper">
    <SelectItem value="apple">Apple</SelectItem>
    <SelectItem value="banana">Banana</SelectItem>
    <SelectItem value="orange">Orange</SelectItem>
  </SelectContent>
</Select>

分组显示

使用 SelectGroup、SelectLabel 和 SelectSeparator 组织选项：

tsx

<Select>
  <SelectTrigger>
    <SelectValue placeholder="Select a fruit" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>Fruits</SelectLabel>
      <SelectItem value="apple">Apple</SelectItem>
      <SelectItem value="banana">Banana</SelectItem>
    </SelectGroup>
    <SelectSeparator />
    <SelectGroup>
      <SelectLabel>Vegetables</SelectLabel>
      <SelectItem value="carrot">Carrot</SelectItem>
      <SelectItem value="potato">Potato</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

可滚动列表

当选项较多时，下拉菜单会自动支持滚动：

tsx

<Select>
  <SelectTrigger>
    <SelectValue placeholder="Select a timezone" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="pst">Pacific Standard Time (PST)</SelectItem>
    <SelectItem value="mst">Mountain Standard Time (MST)</SelectItem>
    <SelectItem value="cst">Central Standard Time (CST)</SelectItem>
    <SelectItem value="est">Eastern Standard Time (EST)</SelectItem>
    {/* 更多时区选项... */}
  </SelectContent>
</Select>

禁用状态

可以禁用整个选择器或单个选项：

tsx

<Select disabled>
  <SelectTrigger>
    <SelectValue placeholder="Select a fruit" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="apple">Apple</SelectItem>
  </SelectContent>
</Select>

错误状态

配合 Field 组件实现表单验证的错误状态：

tsx

import { Field, FieldError, FieldLabel } from "@/components/ui/field"

<Field data-invalid>
  <FieldLabel>Fruit</FieldLabel>
  <Select>
    <SelectTrigger aria-invalid>
      <SelectValue placeholder="Select a fruit" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="apple">Apple</SelectItem>
    </SelectContent>
  </Select>
  <FieldError>Please select a fruit.</FieldError>
</Field>

RTL 支持

shadcn/ui 支持从右到左（RTL）语言布局：

tsx

// 在布局中启用 RTL
<div dir="rtl">
  <Select>
    <SelectTrigger>
      <SelectValue placeholder="اختر فاكهة" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="apple">تفاح</SelectItem>
      <SelectItem value="banana">موز</SelectItem>
    </SelectContent>
  </Select>
</div>

API 参考

Select 组件继承自 Radix UI Select Primitive 的所有属性，完整 API 文档请参考 Radix UI Select 文档。

常用属性

属性	类型	说明
`value`	string	当前选中的值
`defaultValue`	string	默认选中的值
`onValueChange`	(value: string) => void	值变化时的回调函数
`disabled`	boolean	是否禁用
`required`	boolean	是否必填
`open`	boolean	控制下拉菜单的显示状态
`onOpenChange`	(open: boolean) => void	菜单状态变化时的回调

最佳实践

使用有意义的占位符：当没有默认选中值时，使用清晰的占位符文本提示用户
合理分组：当选项较多时，使用分组功能提高可读性
键盘导航：确保用户可以使用键盘操作选择器（方向键、Enter、Escape）
响应式设计：在小屏幕设备上测试下拉菜单的显示效果
表单集成：配合 React Hook Form 或 TanStack Form 使用，实现完整的表单验证

字节笔记本