99.0k

原生选择框

PreviousNext

一个带有一致设计系统集成的样式化原生 HTML 选择框元素。

import {
  NativeSelect,
  NativeSelectOption,
} from "@/components/ui/native-select"

export function NativeSelectDemo() {
  return (
    <NativeSelect>
      <NativeSelectOption value="">Select status</NativeSelectOption>
      <NativeSelectOption value="todo">Todo</NativeSelectOption>
      <NativeSelectOption value="in-progress">In Progress</NativeSelectOption>
      <NativeSelectOption value="done">Done</NativeSelectOption>
      <NativeSelectOption value="cancelled">Cancelled</NativeSelectOption>
    </NativeSelect>
  )
}

安装

pnpm dlx shadcn@latest add native-select

使用方法

import {
  NativeSelect,
  NativeSelectOptGroup,
  NativeSelectOption,
} from "@/components/ui/native-select"
<NativeSelect>
  <NativeSelectOption value="">请选择水果</NativeSelectOption>
  <NativeSelectOption value="apple">苹果</NativeSelectOption>
  <NativeSelectOption value="banana">香蕉</NativeSelectOption>
  <NativeSelectOption value="blueberry">蓝莓</NativeSelectOption>
  <NativeSelectOption value="grapes" disabled>
    葡萄
  </NativeSelectOption>
  <NativeSelectOption value="pineapple">菠萝</NativeSelectOption>
</NativeSelect>

示例

带分组

使用 NativeSelectOptGroup 对选项进行分组以便更好分类。

import {
  NativeSelect,
  NativeSelectOptGroup,
  NativeSelectOption,
} from "@/components/ui/native-select"

export function NativeSelectGroups() {
  return (
    <NativeSelect>
      <NativeSelectOption value="">Select department</NativeSelectOption>
      <NativeSelectOptGroup label="Engineering">
        <NativeSelectOption value="frontend">Frontend</NativeSelectOption>
        <NativeSelectOption value="backend">Backend</NativeSelectOption>
        <NativeSelectOption value="devops">DevOps</NativeSelectOption>
      </NativeSelectOptGroup>
      <NativeSelectOptGroup label="Sales">
        <NativeSelectOption value="sales-rep">Sales Rep</NativeSelectOption>
        <NativeSelectOption value="account-manager">
          Account Manager
        </NativeSelectOption>
        <NativeSelectOption value="sales-director">
          Sales Director
        </NativeSelectOption>
      </NativeSelectOptGroup>
      <NativeSelectOptGroup label="Operations">
        <NativeSelectOption value="support">
          Customer Support
        </NativeSelectOption>
        <NativeSelectOption value="product-manager">
          Product Manager
        </NativeSelectOption>
        <NativeSelectOption value="ops-manager">
          Operations Manager
        </NativeSelectOption>
      </NativeSelectOptGroup>
    </NativeSelect>
  )
}

<NativeSelect>
  <NativeSelectOption value="">请选择食物</NativeSelectOption>
  <NativeSelectOptGroup label="水果">
    <NativeSelectOption value="apple">苹果</NativeSelectOption>
    <NativeSelectOption value="banana">香蕉</NativeSelectOption>
    <NativeSelectOption value="blueberry">蓝莓</NativeSelectOption>
  </NativeSelectOptGroup>
  <NativeSelectOptGroup label="蔬菜">
    <NativeSelectOption value="carrot">胡萝卜</NativeSelectOption>
    <NativeSelectOption value="broccoli">西兰花</NativeSelectOption>
    <NativeSelectOption value="spinach">菠菜</NativeSelectOption>
  </NativeSelectOptGroup>
</NativeSelect>

禁用状态

禁用单个选项或整个选择框组件。

import {
  NativeSelect,
  NativeSelectOption,
} from "@/components/ui/native-select"

export function NativeSelectDisabled() {
  return (
    <NativeSelect disabled>
      <NativeSelectOption value="">Select priority</NativeSelectOption>
      <NativeSelectOption value="low">Low</NativeSelectOption>
      <NativeSelectOption value="medium">Medium</NativeSelectOption>
      <NativeSelectOption value="high">High</NativeSelectOption>
      <NativeSelectOption value="critical">Critical</NativeSelectOption>
    </NativeSelect>
  )
}

无效状态

通过 aria-invalid 属性和错误样式显示验证错误。

import {
  NativeSelect,
  NativeSelectOption,
} from "@/components/ui/native-select"

export function NativeSelectInvalid() {
  return (
    <NativeSelect aria-invalid="true">
      <NativeSelectOption value="">Select role</NativeSelectOption>
      <NativeSelectOption value="admin">Admin</NativeSelectOption>
      <NativeSelectOption value="editor">Editor</NativeSelectOption>
      <NativeSelectOption value="viewer">Viewer</NativeSelectOption>
      <NativeSelectOption value="guest">Guest</NativeSelectOption>
    </NativeSelect>
  )
}

<NativeSelect aria-invalid="true">
  <NativeSelectOption value="">请选择国家</NativeSelectOption>
  <NativeSelectOption value="us">美国</NativeSelectOption>
  <NativeSelectOption value="uk">英国</NativeSelectOption>
  <NativeSelectOption value="ca">加拿大</NativeSelectOption>
</NativeSelect>

表单集成

可与 React Hook Form 等表单库结合使用，实现受控组件。

Component native-select-form not found in registry.

输入组集成

与 InputGroup 组合使用，实现复杂的输入布局。

Component native-select-input-group not found in registry.

原生选择框 与 选择框

  • 当需要浏览器原生行为、更高性能或移动端优化下拉时，使用 NativeSelect。
  • 当需要自定义样式、动画或复杂交互时，使用 Select。

NativeSelect 组件提供原生 HTML 选择功能，并带有与设计系统一致的样式。

可访问性

  • 组件保留了所有原生 HTML 选择框的无障碍功能。
  • 屏幕阅读器可使用箭头键浏览选项。
  • 下拉箭头图标设置为 aria-hidden="true" 以避免重复朗读。
  • 需要时使用 aria-label 或 aria-labelledby 提供额外上下文。
<NativeSelect aria-label="选择你偏好的语言">
  <NativeSelectOption value="en">英语</NativeSelectOption>
  <NativeSelectOption value="es">西班牙语</NativeSelectOption>
  <NativeSelectOption value="fr">法语</NativeSelectOption>
</NativeSelect>

API 参考

NativeSelect

主选择组件，封装了原生 HTML 选择元素。

属性类型默认值
classNamestring

其他所有属性都会传递到底层的 <select> 元素。

<NativeSelect>
  <NativeSelectOption value="option1">选项 1</NativeSelectOption>
  <NativeSelectOption value="option2">选项 2</NativeSelectOption>
</NativeSelect>

NativeSelectOption

表示选择框中的单个选项。

属性类型默认值
valuestring
disabledbooleanfalse
classNamestring

其他所有属性都会传递到底层的 <option> 元素。

<NativeSelectOption value="apple">苹果</NativeSelectOption>
<NativeSelectOption value="banana" disabled>
  香蕉
</NativeSelectOption>

NativeSelectOptGroup

将相关选项分组以便更好地组织。

属性类型默认值
labelstring
disabledbooleanfalse
classNamestring

其他所有属性都会传递到底层的 <optgroup> 元素。

<NativeSelectOptGroup label="水果">
  <NativeSelectOption value="apple">苹果</NativeSelectOption>
  <NativeSelectOption value="banana">香蕉</NativeSelectOption>
</NativeSelectOptGroup>