TagInput (标签输入)

标签输入(v-model string[]),支持分隔符、校验与计数。

基础用法

vuenuxt2/8
Basic.vue

变体与颜色

vuereact
vuereact
vuereact
Variants.vue

上限与分隔

vuenuxt2/5

最多 5 个标签,支持粘贴批量拆分

Limits.vue

错误与禁用

vuereact
vuereact

至少需要一个标签

States.vue

属性

属性类型默认值说明
allowDuplicatesbooleanfalseAccept a tag that is already in the list. Off by default; a repeat emits `invalid` with `duplicate`.
caseSensitivebooleanfalseTreat `Vue` and `vue` as different tags when checking for duplicates.
classNamestring""Extra classes for the bordered field. Use `classNames` to reach the outer wrapper, the tags or the text input.
classNamesKunTagInputClassNamesPer-part class hooks, merged after the component's own classes so yours wins the conflict — KunUI's own `rounded-kun-*` / `shadow-kun-*` scales included.
colorKunUIColor"primary"Focus-ring accent; the resting border stays neutral.
confirmOnBlurbooleantrueCommit whatever is half-typed in the field when it loses focus, instead of discarding it.
descriptionstring""Helper text below the field (hidden when `error` is set). Canonical name.
disabledbooleanfalseBlocks input and dims the field.
errorstring""Error message below the field. Setting it also paints the invalid state and hides `description`.
helperTextstring""Helper text below the field.
labelstring""Visible label above the field.
maxTagLengthnumber100Longest accepted tag, in characters. Default 100.
maxTagsnumberNumber.POSITIVE_INFINITYCap on how many tags can be added. Reaching it emits `invalid` with `max-reached`.
minTagLengthnumber1Shortest accepted tag, in characters. Default 1, i.e. no empty tags.
modelValuestring[][]The tags, two-way bound with `v-model`. Every add and remove writes a new array — the model is never mutated in place.
placeholderstring""Placeholder shown in the text input while it is empty.
readonlybooleanfalseTags stay visible but cannot be added or removed.
respectCompositionbooleantrueIgnore Enter while an IME composition is in progress, so confirming Chinese/Japanese/Korean candidates does not add a tag by accident.
roundedKunUIRoundedRadius of the field. It deliberately does not reach the tags: a tag IS a `<KunChip>` and stays a pill at every setting, so a `KunChip` next to the field and a tag inside it never disagree. Reach a tag with `classNames.chip`.
showCounterbooleanfalseShow a live `used / maxTags` counter. Hidden when `maxTags` is unset.
sizeKunUISize"md"Height, padding and font size, on the shared form-control scale.
splitChars(string | RegExp)[]["\n", ",", ",", ";"]Characters (or patterns) that end a tag as you type. Default `["\n", ",", ",", ";"]` — the full-width comma is there because a CJK keyboard produces it without the user noticing.
splitOnPastebooleantrueSplit pasted text on `splitChars`, so a pasted list becomes many tags instead of one.
transform((raw: string) => string)Normalise a raw entry before it is validated and added — lowercasing, stripping a leading `#`, and so on. Runs after `trim`.
trimbooleantrueStrip leading and trailing whitespace before a tag is added.
validateKunTagInputValidatorCustom rule run on every candidate tag. Return `true` to accept, or a message string to reject; the message arrives with the `invalid` event.
variantKunTagInputVariant"flat"Field style: `bordered` outline, or `flat` filled with no border.

事件

事件回调参数说明
addtag: stringA tag that passed every check and is now in the model.
invalidreason: KunTagInputInvalidReason, raw: string, detail?: stringWhy an entry was rejected, plus the raw text. `detail` carries the message returned by a `validate` function.
removetag: string, index: numberThe tag that was removed and the index it held.
update:modelValuevalue: string[]

插槽

插槽作用域
#tag{ tag: string; index: number; remove: () => void; }