cui

Appearance

cuixingjian
1691
8.1m

Select 选择器 ​

当选项过多时，使用下拉菜单展示并选择内容。

基础用法 ​

适用广泛的基础单选

vue
<template>
  <c-select v-model="value" placeholder="请选择" :options="options" />
</template>

<script setup>
import { ref } from "vue";

const value = ref("");
const options = [
  { label: "选项一", value: "option1" },
  { label: "选项二", value: "option2" },
  { label: "选项三", value: "option3" },
  { label: "选项四", value: "option4" },
];
</script>

有禁用选项 ​

在选项中，设定 disabled 值为 true，即可禁用该选项

vue
<template>
  <c-select v-model="value" placeholder="请选择" :options="options" />
</template>

<script setup>
import { ref } from "vue";

const value = ref("");
const options = [
  { label: "选项一", value: "option1" },
  { label: "选项二", value: "option2", disabled: true },
  { label: "选项三", value: "option3" },
  { label: "选项四", value: "option4", disabled: true },
];
</script>

禁用状态 ​

选择器不可用状态

vue
<template>
  <c-select v-model="value" placeholder="请选择" :options="options" disabled />
</template>

可清空 ​

包含清空按钮，可将选择器清空为初始状态

vue
<template>
  <c-select v-model="value" placeholder="请选择" :options="options" clearable />
</template>

可搜索 ​

可以利用搜索功能快速查找选项

vue
<template>
  <c-select
    v-model="value"
    placeholder="请选择"
    :options="options"
    filterable
  />
</template>

<script setup>
import { ref } from "vue";

const value = ref("");
const options = [
  { label: "苹果", value: "apple" },
  { label: "香蕉", value: "banana" },
  { label: "橙子", value: "orange" },
  { label: "葡萄", value: "grape" },
  { label: "草莓", value: "strawberry" },
  { label: "西瓜", value: "watermelon" },
];
</script>

多选 ​

支持多选，v-model 绑定数组。

请选择
vue
<template>
  <c-select
    v-model="values"
    placeholder="请选择"
    :options="options"
    multiple
    clearable
    filterable
  />
</template>

<script setup>
import { ref } from "vue";

const values = ref([]);
const options = [
  { label: "选项一", value: "option1" },
  { label: "选项二", value: "option2" },
  { label: "选项三", value: "option3" },
  { label: "选项四", value: "option4" },
];
</script>

基础多选（标签） ​

多选选择器默认会在输入框中使用标签展示已选项。

请选择
vue
<template>
  <c-select v-model="values" :options="options" multiple clearable />
</template>

<script setup>
import { ref } from "vue";
const values = ref([]);
</script>

折叠标签 ​

通过 collapse-tags 折叠展示标签，仅显示前若干个，剩余以 + N 显示。

请选择

折叠标签 Tooltip ​

可通过 collapse-tags-tooltip 在 + N 上显示被折叠项的标签文案（采用原生 title 简化表现）。

请选择

指定最多展示的标签数量 ​

使用 max-collapse-tags 控制折叠模式下可见的标签数量。

请选择

不同尺寸 ​

Select 组件提供除了默认值以外的三种尺寸，可以在不同场景下选择合适的按钮尺寸。

vue
<template>
  <c-select
    v-model="value1"
    placeholder="大尺寸"
    :options="options"
    size="large"
  />
  <c-select v-model="value2" placeholder="默认尺寸" :options="options" />
  <c-select
    v-model="value3"
    placeholder="小尺寸"
    :options="options"
    size="small"
  />
</template>

大数据与虚拟滚动 ​

当选项数量较大（如 1000+）时，建议开启虚拟滚动，仅渲染可视区域内的选项，显著提升打开与滚动性能。

  • 开启方式：设置 virtual 为 true。
  • 可选配置：item-height（默认 34，与样式一致，可不传；如自定义选项高度需同步传入）、keeps（视窗保留项数）、buffer（前后缓冲项数）。
  • 建议同时开启 filterable，结合内置防抖过滤，搜索体验更佳。
vue
<template>
  <c-select
    v-model="val"
    :options="bigOptions"
    placeholder="请选择（5000 项）"
    filterable
    virtual
    :keeps="12"
    :buffer="3"
  />
</template>

<script setup>
import { ref } from 'vue'

const val = ref('')
const bigOptions = Array.from({ length: 5000 }).map((_, i) => ({
  label: `选项 ${i + 1}`,
  value: i + 1
}))
</script>

Select Attributes ​

参数说明类型可选值默认值
model-value / v-model绑定值string / number / array——
multiple是否多选boolean—false
collapse-tags折叠多选标签，显示 + Nboolean—false
collapse-tags-tooltip折叠标签显示 tooltip（使用 title）boolean—false
max-collapse-tags折叠模式下最多显示的标签数量number—1
options选项数据SelectOption[]—[]
placeholder占位符string—请选择
disabled是否禁用boolean—false
clearable是否可以清空选项boolean—false
filterable是否可搜索boolean—false
size输入框尺寸stringlarge / default / smalldefault
no-data-text选项为空时显示的文字string—无数据
virtual是否启用虚拟滚动boolean—false
item-height选项高度（用于虚拟滚动估算；默认与样式一致为 34，可不传）number—34
keeps视窗保留项数（虚拟滚动）number—12
buffer前后缓冲项数（虚拟滚动）number—3

SelectOption ​

参数说明类型可选值默认值
label选项的标签string——
value选项的值string / number——
disabled是否禁用该选项boolean—false

Select Events ​

事件名称说明回调参数
change选中值发生变化时触发目前的选中值
clear用户点击清空按钮时触发—
focus当 input 获得焦点时触发(event: Event)
blur当 input 失去焦点时触发(event: Event)

Select Methods ​

方法名说明参数
focus使 input 获取焦点—
blur使 input 失去焦点—

键盘操作 ​

按键说明
Enter选择当前高亮的选项
Escape关闭下拉菜单
ArrowUp向上移动高亮选项
ArrowDown向下移动高亮选项