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.
classNamesKunSelectClassNamesPer-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 to reset the selection (single) — chips already remove per-item.
colorKunUIColor"default"Focus-ring accent (the resting border/text stay neutral).
darkBorderbooleantrueLegacy dark-mode border toggle.
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.
iconstringIcon 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.
loadingTextstring"加载中…"Text under the loading spinner.
manualFilterbooleanfalseSkip the built-in label filter — you own `options` and drive them from `@search` (remote/async suggestions). Requires `searchable`.
maxVisibleTagsnumberHow 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.
namestringNative form field name — emits hidden input(s) so the value is collected by the surrounding <form> / FormData.
noResultTextstring"无匹配项"Shown 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.
roundedKunUIRoundedCorner 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.
searchPlaceholderstring"搜索…"
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; }