开发预览更新于 2026-05-10

Select 选择器

下拉选择 —— options 数组式 API，支持 clearable、键盘导航、disabled item。

基础用法

通过 options 数组传入选项，每项至少包含 value 与 label。

已选：shanghai

<script setup lang="ts">
import { ref } from 'vue';
import { CfSelect, type SelectOption } from '@chufix-design/vue';

const options: SelectOption[] = [
{ value: 'beijing', label: '北京' },
{ value: 'shanghai', label: '上海' },
{ value: 'guangzhou', label: '广州' },
];

const city = ref<string | null>('shanghai');
</script>

<template>
<CfSelect v-model="city" :options="options" placeholder="选一个城市" />
</template>

import { useState } from 'react';
import { CfSelect, type SelectOption } from '@chufix-design/react';

const options: SelectOption[] = [
{ value: 'beijing', label: '北京' },
{ value: 'shanghai', label: '上海' },
{ value: 'guangzhou', label: '广州' },
];

export default function Demo() {
const [city, setCity] = useState<string | null>('shanghai');
return (
  <CfSelect
    value={city}
    options={options}
    placeholder="选一个城市"
    onChange={(v) => setCity(v as string | null)}
  />
);
}

视觉变体

3 种 variant 与 Input 一致：outline（默认）/ filled / ghost。

<CfSelect v-model="v1" :options="options" variant="outline" />
<CfSelect v-model="v2" :options="options" variant="filled" />
<CfSelect v-model="v3" :options="options" variant="ghost" />

<CfSelect value={v1} options={options} variant="outline" onChange={setV1} />
<CfSelect value={v2} options={options} variant="filled" onChange={setV2} />
<CfSelect value={v3} options={options} variant="ghost" onChange={setV3} />

状态与可清空

clearable 在已选中时显示 ×；disabled 整体禁用；error 切到错误色边框。单个 option 可以加 disabled: true 跳过。

<CfSelect v-model="a" :options="options" placeholder="可清空" clearable />
<CfSelect v-model="b" :options="options" placeholder="禁用" disabled />
<CfSelect v-model="b" :options="options" placeholder="错误状态" error />

<CfSelect value={a} options={options} clearable onChange={setA} />
<CfSelect value={b} options={options} disabled />
<CfSelect value={b} options={options} error />

事件与表单

Select 除了值变化，也会暴露打开状态、active 选项、清空、焦点等事件；传入 name 时会同步一个 hidden input，方便在原生表单里提交当前值。

api

等待交互：打开菜单、移动 active、选择或清空。

<CfSelect
v-model="value"
:options="options"
clearable
name="status"
@change="(value, meta) => console.log(value, meta.option)"
@select="(option) => console.log('select', option)"
@clear="() => console.log('clear')"
@open-change="(open) => console.log('open', open)"
@active-change="(option, index) => console.log(option, index)"
/>

<CfSelect
value={value}
options={options}
clearable
name="status"
onChange={(value, meta) => console.log(value, meta.option)}
onSelect={(option) => console.log('select', option)}
onClear={() => console.log('clear')}
onOpenChange={(open) => console.log('open', open)}
onActiveChange={(option, index) => console.log(option, index)}
/>

键盘交互

按键	行为
`↓` / `↑`	打开菜单 / 在选项之间移动 active
`Enter` / `空格`	打开菜单 / 选中当前 active 项
`Esc`	关闭菜单
`Tab`	关闭菜单并把焦点交还浏览器

API

Prop	类型	默认值	说明
`options`	`SelectOption[]`	`[]`	选项数组，`{ value, label, disabled? }`
`placeholder`	`string`	`'请选择'`	未选中时显示
`variant`	`'outline' \| 'filled' \| 'ghost'`	`'outline'`	视觉变体
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	整体尺寸
`clearable`	`boolean`	`false`	已选中时显示清除按钮
`disabled`	`boolean`	`false`	整体禁用
`error`	`boolean`	`false`	错误态
`name`	`string`	—	生成 hidden input，参与原生表单提交
`id`	`string`	—	触发按钮 id，并用于关联 listbox

Events

Vue 事件	React 回调	payload	说明
`change`	`onChange`	`(value, { option })`	值变化，清空时 `option` 为 `null`
`select`	`onSelect`	`option`	选中某个 option
`clear`	`onClear`	—	点击清除按钮
`open-change`	`onOpenChange`	`open`	下拉菜单打开 / 关闭
`active-change`	`onActiveChange`	`(option, index)`	键盘或鼠标移动 active option
`focus` / `blur`	`onFocus` / `onBlur`	`FocusEvent`	触发按钮焦点事件

当前实现使用 position: absolute 浮层；如果父级 overflow: hidden 裁掉了菜单，后续会扩展 Portal 版本。