强大的 Vue 标签输入组件：基于 Element Plus 的 ElTagInput 详解

标签输入框组件 (ElTagInput)

一个功能强大的标签输入组件，基于 Element Plus 开发，支持多种交互模式和自定义配置。

组件链接 demo示例链接

功能特点

• 🏷️ 支持添加、删除和管理多个标签
• 🔢 可限制最大显示标签数量，超出部分折叠显示
• 🎨 自定义标签样式（类型、效果、大小）
• 🛑 支持禁用、只读和错误状态
• 🔄 双向绑定 (v-model) 支持
• ✨ 连续输入模式（输入后自动保持焦点）
• 🧹 一键清空功能
• 📝 保留输入值选项
• 📊 完整的事件系统

安装与使用

基本用法

<template>
  <el-tag-input v-model="tags" />
</template>

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

属性

属性名	说明	类型	默认值
v-model / modelValue	绑定的标签数组	Array	\[\]
max-tag-count	最大展示标签数量（0表示不限制）	Number	0
tag-type	标签类型（同 Element Tag 的 type）	String	''
tag-effect	标签效果（light/dark/plain）	String	'light'
tag-size	标签尺寸（large/default/small）	String	'default'
tag-height	自定义标签高度（像素）	Number	32
tag-width	自定义标签宽度（像素）	Number	0
disabled	是否禁用	Boolean	false
readonly	是否只读	Boolean	false
error	是否错误状态	Boolean	false
placeholder	输入框占位文本	String	'添加标签'
allow-clear	是否显示清空按钮	Boolean	false
retain-input-value	输入确认后是否保留输入值	Boolean	false
input-debounce	输入事件防抖时间（毫秒）	Number	300

事件

事件名	说明	回调参数
update:modelValue	标签数组更新时触发	(tags: string\[\])
change	标签数组变化时触发	(tags: string\[\])
input-value-change	输入值变化时触发（防抖）	(value: string, event: Event)
press-enter	按下回车确认输入时触发	{ value: string, tags: string\[\] }
remove	删除标签时触发	{ value: string, index: number, tags: string\[\] }
clear	清空所有标签时触发	{ oldTags: string\[\], tags: string\[\] }
focus	输入框获取焦点时触发	(value: string, event: Event)
blur	输入框失去焦点时触发	(value: string, event: Event)

方法

通过 ref 调用组件方法：

<template>
  <el-tag-input ref="tagInputRef" />
  <button @click="addTag">添加标签</button>
</template>

<script setup>
import { ref } from 'vue'
const tagInputRef = ref(null)

const addTag = () => {
  tagInputRef.value?.addTag('新标签')
}
</script>

可用方法

方法名	说明	参数	返回值
addTag	添加标签	(tag: string)	boolean
clearTags	清空所有标签	-	string\[\] (原标签)
getTags	获取当前标签	-	string\[\]
setTags	设置标签	(tags: string\[\])	string\[\]
removeTagByIndex	按索引移除标签	(index: number)	string/null
getInputValue	获取当前输入值	-	string
setInputValue	设置输入值	(value: string)	string
focus	聚焦输入框	-	boolean
blur	失焦输入框	-	boolean

示例

高级配置

<el-tag-input
  v-model="tags"
  :max-tag-count="3"
  tag-type="success"
  tag-effect="dark"
  :tag-height="40"
  allow-clear
/>

事件监听

<el-tag-input
  v-model="tags"
  @press-enter="handleEnter"
  @remove="handleRemove"
  @clear="handleClear"
/>

<script setup>
const handleEnter = ({ value, tags }) => {
  console.log('添加标签:', value, '当前标签:', tags)
}
const handleRemove = ({ value, index, tags }) => {
  console.log('移除标签:', value, '位置:', index, '剩余标签:', tags)
}
const handleClear = ({ oldTags }) => {
  console.log('清空标签，原标签:', oldTags)
}
</script>

连续输入模式

<el-tag-input v-model="tags" />
<!-- 输入标签后按回车，输入框会自动保持焦点 -->

样式定制

组件支持通过 CSS 变量和样式覆盖进行自定义：

.el-tag-input {
  --tag-height: 36px; /* 自定义标签高度 */
}

注意事项

• 当 max-tag-count 为 0 时表示不限制显示标签数量
• 连续输入模式下，按 ESC 或点击外部可退出输入状态
• 在禁用或只读状态下无法添加/删除标签

示例截图