开发预览更新于 2026-05-10

TagInput 标签输入

多标签输入控件，键入回车追加，退格删除，支持粘贴批量导入。

基础用法

v-model 绑定一个 string[]。键入文字后按 Enter 追加；输入框为空时按 Backspace 删除最后一个标签；点击标签上的 × 也可移除。

vuereact

<script setup lang="ts">
import { ref } from 'vue';
import { CfTagInput } from '@chufix-design/vue';

const tags = ref<string[]>(['vue', 'react']);
</script>

<template>
<CfTagInput v-model="tags" placeholder="输入后按回车添加" />
</template>

import { useState } from 'react';
import { CfTagInput } from '@chufix-design/react';

export default function Demo() {
const [tags, setTags] = useState<string[]>(['vue', 'react']);
return <CfTagInput value={tags} placeholder="输入后按回车添加" onChange={setTags} />;
}

色调

tone 控制标签底色，与 Tag 组件的语义色一一对应。

neutral

accenthighlight

warn

error

<CfTagInput v-model="a" tone="neutral" />
<CfTagInput v-model="b" tone="accent" />
<CfTagInput v-model="c" tone="success" />
<CfTagInput v-model="d" tone="warning" />
<CfTagInput v-model="e" tone="danger" />

<CfTagInput value={a} tone="neutral" onChange={setA} />
<CfTagInput value={b} tone="accent"  onChange={setB} />
<CfTagInput value={c} tone="success" onChange={setC} />
<CfTagInput value={d} tone="warning" onChange={setD} />
<CfTagInput value={e} tone="danger"  onChange={setE} />

自定义分隔符

separators 是一个键名数组，键入这些键就把当前草稿提交为标签。逗号 / 空格 / Tab 都可以加进去。粘贴时会按 , \\n \\t 自动拆分。

<CfTagInput
v-model="tags"
:separators="['Enter', ',', ' ']"
placeholder="回车 / 逗号 / 空格 都能分隔"
/>

<CfTagInput
value={tags}
separators={['Enter', ',', ' ']}
placeholder="回车 / 逗号 / 空格 都能分隔"
onChange={setTags}
/>

数量限制 / 校验

max 限制总数，validate 是一个返回 boolean 的函数；不通过的输入会被默默丢弃。

已添加 0 / 5；非法格式不会被加入。

<script setup lang="ts">
import { ref } from 'vue';
import { CfTagInput } from '@chufix-design/vue';

const tags = ref<string[]>([]);
const isEmail = (t: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t);
</script>

<template>
<CfTagInput
  v-model="tags"
  :max="5"
  :validate="isEmail"
  :separators="['Enter', ',', ' ']"
  placeholder="最多 5 个邮箱地址"
/>
</template>

import { useState } from 'react';
import { CfTagInput } from '@chufix-design/react';

const isEmail = (t: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t);

export default function Demo() {
const [tags, setTags] = useState<string[]>([]);
return (
  <CfTagInput
    value={tags}
    max={5}
    validate={isEmail}
    separators={['Enter', ',', ' ']}
    placeholder="最多 5 个邮箱地址"
    onChange={setTags}
  />
);
}

API

属性	类型	默认值	说明
`modelValue` (Vue) / `value` (React)	`string[]`	`[]`	当前标签数组
`placeholder`	`string`	`'输入后回车添加'`	占位文案，仅在空状态显示
`variant`	`'outline' \| 'filled' \| 'ghost'`	`'outline'`	视觉模式
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	尺寸
`tone`	`'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'`	`'neutral'`	标签底色
`disabled`	`boolean`	`false`	禁用
`error`	`boolean`	`false`	错误态
`max`	`number`	`—`	标签数量上限
`separators`	`string[]`	`['Enter']`	触发提交的键，可包含 `'Enter'` `','` `' '` `'Tab'` 或单字符
`unique`	`boolean`	`true`	是否去重，重复的输入会被忽略
`trim`	`boolean`	`true`	提交前是否 trim
`validate`	`(tag) => boolean`	`—`	返回 `false` 的输入会被丢弃

事件：update:modelValue / add / remove（React 端：onChange / onAdd / onRemove）。