Select (选择器)
下拉选择框(v-model),由 options 数组驱动。
基础用法
Vue
Basic.vue
可搜索
Vue
Searchable.vue
多选
VueSolid
值: vue, solid
Multiple.vue
可清除
Vue
Clearable.vue
禁用
Vue
React
Disabled.vue
错误
请选择
此项为必填项
Error.vue
颜色
Vue
Vue
Vue
Vue
Vue
Vue
Colors.vue
自定义选项(#option 插槽)
Kun
CustomOption.vue
异步 / 远程数据源
搜索作品名
已选 0 项:—
选中一项后再搜别的词——标签不会丢,组件为当前选中的值保留了最后一次见到的 option。
Async.vue
筛选栏形态
标签 · 1
平台
状态
- 已完成
CLANNAD
2004 · PC · 催泪/校园
- 进行中
Summer Pockets
2018 · Switch · 夏天/催泪
- 已完成
Little Busters!
2007 · Switch · 校园/催泪
FilterBar.vue
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue * | KunSelectValue | KunSelectValue[] | null | — | |
| options * | readonly KunSelectOption<KunSelectValue>[] | — | |
| ariaLabel | string | "" | |
| className | string | "" | Extra classes for the outer wrapper. Use `classNames` to reach the trigger, popup, list, options or chips. |
| classNames | KunSelectClassNames | — | Per-part class hooks (root / trigger / popup / list / option / chip), merged after the component's own classes, so yours wins the conflict — KunUI's own `rounded-kun-*` / `shadow-kun-*` / `z-kun-*` scales included. `rounded` is still the right tool for the trigger and popup radius; `classNames.chip` is the only way to reach a chip. |
| clearable | boolean | false | Show an X to reset the selection (single) — chips already remove per-item. |
| color | KunUIColor | "default" | Focus-ring accent (the resting border/text stay neutral). |
| darkBorder | boolean | true | Legacy dark-mode border toggle. |
| debounce | number | 0 | Debounce the `@search` emit by N ms; the filter field itself still updates instantly. 0 (default) emits on every keystroke — set e.g. 300 for a remote source so you fetch once the user pauses, not per keypress. |
| description | string | "" | Helper text under the field (hidden when `error` is set). |
| disabled | boolean | false | |
| error | string | "" | |
| fullWidth | boolean | true | Stretch the control to its container. Turn it off in a filter bar, so the trigger shrinks to its own content. The wrapper shrink-wraps its widest child, so a long `label`, `description` or `error` widens it too — a filter pill wants none of those. |
| icon | string | — | Icon rendered before the value in the trigger — a filter glyph for a filter bar, a category glyph for a field. Must be one of the bundled icon names. |
| label | string | "" | |
| loading | boolean | false | Async data source: show a spinner in the list (instead of `noResultText`) while a remote `@search` request is in flight. Drive it from your fetch — true when the request starts, false when the results land. |
| loadingText | string | "加载中…" | Text under the loading spinner. |
| manualFilter | boolean | false | Skip the built-in label filter — you own `options` and drive them from `@search` (remote/async suggestions). Requires `searchable`. |
| maxVisibleTags | number | — | How many chips a `multiple` trigger renders before collapsing the rest into a `+N` badge. `0` renders no chips at all and the trigger reads `{placeholder} · {n}`, or a bare count when there is no placeholder — what a filter pill wants, and what keeps a filter bar from growing a row per selection. Unset renders every chip. |
| multiple | boolean | false | Multi-select: v-model becomes an array; the trigger shows removable chips and the list stays open while toggling. |
| name | string | — | Native form field name — emits hidden input(s) so the value is collected by the surrounding <form> / FormData. |
| noResultText | string | "无匹配项" | Shown when the filter matches nothing. |
| placeholder | string | "" | |
| popupWidth | KunSelectPopupWidth | "trigger" | Popup width. The default pins it to the trigger, which is wrong the moment the trigger is a short pill — a 90px trigger gets a 90px list. `'auto'` sizes to the content and keeps the trigger width as a floor. Every mode but `'trigger'` is capped to the viewport, so a fixed width chosen for a desktop layout cannot hang off the edge of a phone. |
| rounded | KunUIRounded | — | Corner radius. When unset it follows the nearest KunUIConfigProvider's `rounded`. `full` means a pill, which is only defined for the single-line trigger — the floating panel falls back to `lg`, because `9999px` on an n-row panel is clamped by the browser to half its short side. Every other bucket applies to both. |
| searchable | boolean | false | Render a filter input at the top of the list. Also the switch that enables `@search` / `manualFilter` — without it there is nothing to type into. |
| searchPlaceholder | string | "搜索…" | |
| size | KunUISize | "md" |
事件
| 事件 | 回调参数 | 说明 |
|---|---|---|
| search | query: string | The filter text, debounced by `debounce`. Requires `searchable`. Also fired with `''` (immediately) when the popup opens, so a remote source can load its first page. |
| set | value: KunSelectValue, index: number | The option the user just picked and its index in `options`. Fires on every pick, including each toggle in `multiple`; `update:modelValue` carries the whole value. |
| update:modelValue | value: KunSelectValue | KunSelectValue[] | null |
插槽
| 插槽 | 作用域 |
|---|---|
| #option | { option: KunSelectOption<KunSelectValue>; index: number; active: boolean; selected: boolean; } |