Select (选择器)

下拉选择框(v-model),由 options 数组驱动。

基础用法

Basic.vue

可搜索

Searchable.vue

多选

值: vue, solid

Multiple.vue

可清除

Clearable.vue

禁用

Disabled.vue

错误

此项为必填项

Error.vue

颜色

Colors.vue

自定义选项(#option 插槽)

CustomOption.vue

异步 / 远程数据源

已选 0 项:—

选中一项后再搜别的词——标签不会丢,组件为当前选中的值保留了最后一次见到的 option。

Async.vue

筛选栏形态

  • CLANNAD

    2004 · PC · 催泪/校园

    已完成
  • Summer Pockets

    2018 · Switch · 夏天/催泪

    进行中
  • Little Busters!

    2007 · Switch · 校园/催泪

    已完成
FilterBar.vue

属性

属性类型默认值说明
modelValue *KunSelectValue | KunSelectValue[] | null—
options *readonly KunSelectOption<KunSelectValue>[]—
ariaLabelstring""
classNamestring""Extra classes for the outer wrapper. Use `classNames` to reach the trigger, popup, list, options or chips.
classNamesKunSelectClassNames—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.
clearablebooleanfalseShow an X that resets the whole selection. The X is out of the Tab order but is a labelled button to a screen reader, so touch screen-reader users can reach it. From the keyboard, Backspace or Delete on the focused trigger clears a single Select (a `multiple` one removes its last value that way regardless).
colorKunUIColor"default"Focus-ring accent (the resting border/text stay neutral).
darkBorderbooleantrueLegacy dark-mode border toggle. 已废弃:No-op since 0.18.0. Every neutral border now resolves to the unified `--color-kun-border` token (the `border-kun` utility), which already flips light↔dark — so the old light-translucent / dark-solid split this prop toggled is gone. Safe to remove from call sites.
debouncenumber0Debounce 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.
descriptionstring""Helper text under the field (hidden when `error` is set).
disabledbooleanfalse
errorstring""
fullWidthbooleantrueStretch 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.
iconstring—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.
labelstring""
loadingbooleanfalseAsync 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.
loadingTextstringlocale select.loadingText under the loading spinner.
manualFilterbooleanfalseSkip the built-in label filter — you own `options` and drive them from `@search` (remote/async suggestions). Requires `searchable`.
maxVisibleTagsnumber—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.
multiplebooleanfalseMulti-select: v-model becomes an array; the trigger shows removable chips and the list stays open while toggling. A chip's × is pointer-only; from the keyboard, Backspace or Delete on the focused trigger removes the last value, and a screen reader unticks the option in the list.
namestring—Native form field name — emits hidden input(s) so the value is collected by the surrounding <form> / FormData.
noResultTextstringlocale select.noResultShown when the filter matches nothing.
placeholderstring""
popupWidthKunSelectPopupWidth"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.
roundedKunUIRounded—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.
searchablebooleanfalseRender a filter input at the top of the list. Also the switch that enables `@search` / `manualFilter` — without it there is nothing to type into.
searchPlaceholderstringlocale select.searchPlaceholderPlaceholder in the in-panel search box.
sizeKunUISize"md"

事件

事件回调参数说明
searchquery: stringThe filter text, debounced by `debounce`. Requires `searchable`. Also fired with `''` (immediately) when the popup opens, so a remote source can load its first page.
setvalue: KunSelectValue, index: numberThe 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:modelValuevalue: KunSelectValue | KunSelectValue[] | null

插槽

插槽作用域
#option{ option: KunSelectOption<KunSelectValue>; index: number; active: boolean; selected: boolean; }