TagsInput 标签输入框

用于输入和管理多个标签的组件，支持通过键盘快捷键添加和删除标签。

组件特性

⌨️ 键盘交互：支持 Enter、逗号或自定义分隔符添加标签。
📏 多种尺寸：支持 xs、sm、default、lg、xl、2xl 六种尺寸。
❌ 禁用/只读/加载：支持 disabled、loading、readonly 属性。
🔢 最大标签数：使用 max 属性限制可添加的最大标签数量。
✖️ 可清除：设置 clearable 属性后，可清除所有标签。
📝 表单集成：配合 BrFormField、vee-validate 和 zod 实现带验证的标签输入。
🌗 暗黑模式：基于 BrConfigProvider 自动适配暗黑模式。

基础用法

通过 v-model 绑定一个字符串数组，输入文本后按 Enter 键即可添加标签。每个标签右侧有关闭按钮，也可以使用 Backspace 键删除最后一个标签。

<script setup>
import { ref } from 'vue'
const tags = ref(['Vue', 'React'])
</script>

<template>
  <div class="space-y-2">
    <BrTagsInput v-model="tags" placeholder="输入标签后按 Enter 添加..." />
    <p class="text-xs text-muted-foreground">当前标签: {{ tags }}</p>
  </div>
</template>

尺寸

提供 xs、sm、default、lg、xl、2xl 六种尺寸。

<template>
<div class="space-y-2">
  <BrTagsInput size="xs" placeholder="Extra Small" />
  <BrTagsInput size="sm" placeholder="Small" />
  <BrTagsInput size="default" placeholder="Default" />
  <BrTagsInput size="lg" placeholder="Large" />
  <BrTagsInput size="xl" placeholder="Extra Large" />
  <BrTagsInput size="2xl" placeholder="2 Extra Large" />
</div>
</template>

禁用、加载与只读

通过 disabled、loading、readonly 属性控制组件的不同状态。

禁用：完全禁止交互
加载中：显示加载动画，禁止输入
只读：标签不可删除，不可添加新标签

<script setup>
import { ref } from 'vue'
const tags = ref(['标签一', '标签二'])
</script>

<template>
<div class="space-y-2">
  <BrTagsInput v-model="tags" disabled placeholder="禁用状态" />
  <BrTagsInput v-model="tags" loading placeholder="加载中状态" />
  <BrTagsInput v-model="tags" readonly placeholder="只读状态" />
</div>
</template>

最大标签数

使用 max 属性限制可添加的最大标签数量。

<script setup>
import { ref } from 'vue'
const tags = ref(['Vue'])
</script>

<template>
  <div class="space-y-2">
    <BrTagsInput v-model="tags" :max="5" placeholder="最多添加 5 个标签" />
    <p class="text-xs text-muted-foreground">已添加 {{ tags.length }}/5 个标签</p>
  </div>
</template>

可清除

设置 clearable 属性后，当存在标签时会显示一个清除按钮，点击可清除所有标签。

<script setup>
import { ref } from 'vue'
const tags = ref(['JavaScript', 'TypeScript', 'Vue'])
</script>

<template>
  <div class="space-y-2">
    <BrTagsInput v-model="tags" clearable placeholder="可清除标签输入框" />
  </div>
</template>

表单集成

配合 BrFormField、vee-validate 和 zod 使用，实现带验证的标签输入。

<script setup>
import { ref } from 'vue'
import { useForm } from 'vee-validate'
import { z } from 'zod'
import { toTypedSchema } from '@vee-validate/zod'

const schema = toTypedSchema(z.object({
  tags: z.array(z.string()).min(1, '请至少添加一个标签').max(5, '最多添加 5 个标签'),
}))

const { handleSubmit } = useForm({
  validationSchema: schema,
  initialValues: {
    tags: [],
  },
})

const onSubmit = handleSubmit((formValues) => {
  alert(`提交成功! 标签: ${formValues.tags.join(', ')}`)
})
</script>

<template>
  <form @submit="onSubmit" class="space-y-4 max-w-md">
    <BrFormField name="tags" label="技能标签" required>
      <BrTagsInput name="tags" placeholder="输入技能后按 Enter 添加..." clearable />
    </BrFormField>
    <BrButton type="submit">提交</BrButton>
  </form>
</template>

主题定制

你可以使用 Tailwind CSS 类自定义标签输入框的外观，或者通过覆盖全局 CSS 变量。

Tailwind 定制

你也可以使用 class 属性添加自定义样式：

<BrTagsInput class="border-blue-500 focus-within:ring-blue-500" />

API

Props

属性名	类型	默认值	说明
modelValue	`string[]`	-	标签数组，支持 `v-model` 双向绑定。
defaultValue	`string[]`	-	默认标签数组。
size	`xs` \| `sm` \| `default` \| `md` \| `lg` \| `xl` \| `2xl`	`default`	标签输入框尺寸。
max	`number`	-	允许添加的最大标签数量。
disabled	`boolean`	`false`	是否禁用输入框。
readonly	`boolean`	`false`	是否只读。只读时不可添加或删除标签。
loading	`boolean`	`false`	是否显示加载中状态。
placeholder	`string`	`''`	占位文本。
delimiter	`string`	`','`	用于分割输入的分隔符。
addOnBlur	`boolean`	`false`	失焦时是否自动添加当前输入为标签。
clearable	`boolean`	`false`	是否显示清除所有标签的按钮。
error	`boolean`	`false`	是否显示错误状态（红色边框）。

Slots

名称	说明
prefix	显示在标签之前的内容，通常用于放置图标。
suffix	显示在输入框之后的内容，通常用于放置图标。
items	自定义标签渲染。作用域参数为 `{ tags: string[], size: string }`。

Events

名称	参数	说明
update:modelValue	`string[]`	标签数组变化时触发。
add	`string`	添加新标签时触发，参数为新标签值。
remove	`string`	删除标签时触发，参数为被删除标签值。
clear	-	点击清除按钮时触发。
focus	`FocusEvent`	输入框获得焦点时触发。
blur	`FocusEvent`	输入框失去焦点时触发。

#TagsInput 标签输入框

#组件特性

#基础用法

#尺寸

#禁用、加载与只读

#最大标签数

#可清除

#表单集成

#主题定制

#Tailwind 定制

#API

#Props

#Slots

#Events