章节

立即开始

安装

夜间模式

表单

注册表

原生选择

一个具有一致设计系统集成的风格化原生 HTML 下拉选择元素。

有关样式化选择组件，请参阅 Select 组件。

<script setup lang="ts">
import {
  NativeSelect,
  NativeSelectOption,
} from '@/components/ui/native-select'
</script>

<template>
  <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>
</template>

安装

🌐 Installation


pnpm dlx shadcn-vue@latest add native-select

用法

🌐 Usage

<script setup lang="ts">
import {
  NativeSelect,
  NativeSelectOptGroup,
  NativeSelectOption,
} from '@/components/ui/native-select'
</script>

<template>
  <NativeSelect>
    <NativeSelectOption value="">
      Select a fruit
    </NativeSelectOption>
    <NativeSelectOption value="apple">
      Apple
    </NativeSelectOption>
    <NativeSelectOption value="banana">
      Banana
    </NativeSelectOption>
    <NativeSelectOption value="blueberry">
      Blueberry
    </NativeSelectOption>
    <NativeSelectOption value="grapes" disabled>
      Grapes
    </NativeSelectOption>
    <NativeSelectOption value="pineapple">
      Pineapple
    </NativeSelectOption>
  </NativeSelect>
</template>

示例

🌐 Examples

带群组

🌐 With Groups

使用 NativeSelectOptGroup 组织选项以实现更好的分类。

🌐 Organize options using NativeSelectOptGroup for better categorization.

<script setup lang="ts">
import {
  NativeSelect,
  NativeSelectOptGroup,
  NativeSelectOption,
} from '@/components/ui/native-select'
</script>

<template>
  <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>
</template>

<template>
  <NativeSelect>
    <NativeSelectOption value="">
      Select a food
    </NativeSelectOption>
    <NativeSelectOptGroup label="Fruits">
      <NativeSelectOption value="apple">
        Apple
      </NativeSelectOption>
      <NativeSelectOption value="banana">
        Banana
      </NativeSelectOption>
      <NativeSelectOption value="blueberry">
        Blueberry
      </NativeSelectOption>
    </NativeSelectOptGroup>
    <NativeSelectOptGroup label="Vegetables">
      <NativeSelectOption value="carrot">
        Carrot
      </NativeSelectOption>
      <NativeSelectOption value="broccoli">
        Broccoli
      </NativeSelectOption>
      <NativeSelectOption value="spinach">
        Spinach
      </NativeSelectOption>
    </NativeSelectOptGroup>
  </NativeSelect>
</template>

禁用状态

🌐 Disabled State

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

🌐 Disable individual options or the entire select component.

<script setup lang="ts">
import {
  NativeSelect,
  NativeSelectOption,
} from '@/components/ui/native-select'
</script>

<template>
  <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>
</template>

无效状态

🌐 Invalid State

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

🌐 Show validation errors with the aria-invalid attribute and error styling.

<script setup lang="ts">
import {
  NativeSelect,
  NativeSelectOption,
} from '@/components/ui/native-select'
</script>

<template>
  <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>
</template>

<template>
  <NativeSelect aria-invalid="true">
    <NativeSelectOption value="">
      Select a country
    </NativeSelectOption>
    <NativeSelectOption value="us">
      United States
    </NativeSelectOption>
    <NativeSelectOption value="uk">
      United Kingdom
    </NativeSelectOption>
    <NativeSelectOption value="ca">
      Canada
    </NativeSelectOption>
  </NativeSelect>
</template>

表单集成

🌐 Form Integration

与 VeeValidate 等表单库一起使用以控制组件。

🌐 Use with form libraries like VeeValidate for controlled components.

<script setup lang="ts">
import { toTypedSchema } from '@vee-validate/zod'
import { useForm } from 'vee-validate'
import { toast } from 'vue-sonner'

import { z } from 'zod'
import { Button } from '@/components/ui/button'
import {
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@/components/ui/form'
import {
  NativeSelect,
  NativeSelectOption,
} from '@/components/ui/native-select'

const formSchema = toTypedSchema(z.object({
  country: z.string().min(2, {
    message: 'Select a country.',
  }),
}))

const form = useForm({
  validationSchema: formSchema,
})

const onSubmit = form.handleSubmit((values) => {
  console.log('Form submitted!', values)
  toast('You submitted the following values:', {
    description: h('pre', { class: 'mt-2 rounded-md bg-neutral-900 p-4 w-full' }, h('code', { class: 'text-code-foreground' }, JSON.stringify(values, null, 2))),
  })
})
</script>

<template>
  <form class="w-full max-w-sm space-y-6" @submit="onSubmit">
    <FormField v-slot="{ field }" name="country">
      <FormItem>
        <FormLabel>Country</FormLabel>
        <FormControl>
          <NativeSelect v-bind="field">
            <NativeSelectOption value="">
              Select a country
            </NativeSelectOption>
            <NativeSelectOption value="us">
              United States
            </NativeSelectOption>
            <NativeSelectOption value="uk">
              United Kingdom
            </NativeSelectOption>
            <NativeSelectOption value="ca">
              Canada
            </NativeSelectOption>
          </NativeSelect>
        </FormControl>
        <FormDescription>
          Select a country
        </FormDescription>
        <FormMessage />
      </FormItem>
    </FormField>

    <Button type="submit" class="w-full">
      Submit
    </Button>
  </form>
</template>

原生选择 vs 选择

🌐 Native Select vs Select

当你需要原生浏览器行为、更好的性能或针对移动设备优化的下拉菜单时，请使用 NativeSelect。
当你需要自定义样式、动画或复杂交互时使用 Select。

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

🌐 The NativeSelect component provides native HTML select functionality with consistent styling that matches your design system.

可访问性

🌐 Accessibility

该组件保持了所有原生 HTML 选择元素的可访问性功能。
屏幕阅读器可以使用箭头键浏览选项。
V形图标标记为 aria-hidden="true" 以避免重复。
在需要时使用 aria-label 或 aria-labelledby 提供额外的上下文。

<template>
  <NativeSelect aria-label="Choose your preferred language">
    <NativeSelectOption value="en">
      English
    </NativeSelectOption>
    <NativeSelectOption value="es">
      Spanish
    </NativeSelectOption>
    <NativeSelectOption value="fr">
      French
    </NativeSelectOption>
  </NativeSelect>
</template>

API参考

🌐 API Reference

NativeSelect

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

🌐 The main select component that wraps the native HTML select element.

属性	类型	默认值
`class`	`string`

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

🌐 All other props are passed through to the underlying <select> element.

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

NativeSelectOption

表示选择中的单个选项。

🌐 Represents an individual option within the select.

属性	类型	默认值
`value`	`string`
`disabled`	`boolean`	`false`
`class`	`string`

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

🌐 All other props are passed through to the underlying <option> element.

<template>
  <NativeSelectOption value="apple">
    Apple
  </NativeSelectOption>
  <NativeSelectOption value="banana" disabled>
    Banana
  </NativeSelectOption>
</template>

NativeSelectOptGroup

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

🌐 Groups related options together for better organization.

属性	类型	默认值
`label`	`string`
`disabled`	`boolean`	`false`
`class`	`string`

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

🌐 All other props are passed through to the underlying <optgroup> element.

<template>
  <NativeSelectOptGroup label="Fruits">
    <NativeSelectOption value="apple">
      Apple
    </NativeSelectOption>
    <NativeSelectOption value="banana">
      Banana
    </NativeSelectOption>
  </NativeSelectOptGroup>
</template>

菜单栏导航菜单

On This Page

安装用法示例带群组禁用状态无效状态表单集成原生选择 vs 选择可访问性 API参考 NativeSelect NativeSelectOption NativeSelectOptGroup