Element Plus Tag 标签组件完整指南：从基础用法到 CheckTag 可选中标签

Element Plus Tag 标签组件完整指南从基础用法到 CheckTag 可选中标签【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus导读本文围绕 Element PlusVue 3 UI 组件库中的 Tag 标签组件展开系统讲解其类型type、尺寸size、主题effect、可关闭、可编辑、圆角与可选中CheckTag等全部能力并深入源码验证底层实现原理。读完本文你将掌握 Tag 组件的全部 API 用法能够结合实际业务构建动态标签输入、分类筛选、状态标记等实战场景。官方文档位置docs/en-US/component/tag.md对应示例位于 docs/examples/tag。基本用法用 type 定义标签类型Tag 组件用于标记与选择Used for marking and selection。通过type属性可以定义 Tag 的类型同时color属性可用于直接设置标签的背景色。五种内置类型分别对应不同的语义色primary主色、success成功、info信息、warning警告、danger危险默认值为primary。示例代码完整代码见 docs/examples/tag/basic.vuetemplate div classflex gap-2 el-tag typeprimaryTag 1/el-tag el-tag typesuccessTag 2/el-tag el-tag typeinfoTag 3/el-tag el-tag typewarningTag 4/el-tag el-tag typedangerTag 5/el-tag /div /template自定义背景色color属性接收任意合法 CSS 颜色字符串如#409EFF会被直接内联到标签根元素的background-color样式上。从源码 packages/components/tag/src/tag.vue 可以看到渲染时通过:style{ backgroundColor: color }动态应用因此color的优先级高于type对应的主题色适合品牌色定制场景。可移除标签Removable Tag设置closable属性接受Boolean即可让标签显示关闭按钮点击后触发close事件并移除标签。默认情况下标签移除时带有淡出fading动画——该动画由源码中的transition包裹实现使用el-zoom-in-center过渡效果见 packages/components/tag/src/tag.vue。如果不需要动画可以设置disable-transitions属性为true此时将直接渲染为普通span而不再套用transition。示例代码完整代码见 docs/examples/tag/removable.vuetemplate div classflex gap-2 el-tag v-fortag in tags :keytag.name closable :typetag.type {{ tag.name }} /el-tag /div /template script langts setup import { ref } from vue import type { TagProps } from element-plus interface TagsItem { name: string type: TagProps[type] } const tags refTagsItem[]([ { name: Tag 1, type: primary }, { name: Tag 2, type: success }, { name: Tag 3, type: info }, { name: Tag 4, type: warning }, { name: Tag 5, type: danger }, ]) /script从源码实现看关闭按钮是一个真实的button typebutton元素带aria-label无障碍标签内容来自国际化文案el.tag.close内部渲染Close图标并通过click.stop阻止事件冒泡后再触发close事件见 packages/components/tag/src/tag.vue。这意味着点击关闭按钮不会同时触发标签的click事件。动态编辑标签Edit Dynamically借助close事件可以轻松实现新增/删除标签的完整交互闭环点击标签的关闭按钮移除标签点击New Tag按钮显示输入框输入内容后按回车或失焦确认并追加新标签。示例代码完整代码见 docs/examples/tag/editable.vuetemplate div classflex gap-2 el-tag v-fortag in dynamicTags :keytag closable :disable-transitionsfalse closehandleClose(tag) {{ tag }} /el-tag el-input v-ifinputVisible refInputRef v-modelinputValue classw-20 sizesmall keyup.enterhandleInputConfirm blurhandleInputConfirm / el-button v-else classbutton-new-tag sizesmall clickshowInput New Tag /el-button /div /template script langts setup import { nextTick, ref } from vue import type { InputInstance } from element-plus const inputValue ref() const dynamicTags ref([Tag 1, Tag 2, Tag 3]) const inputVisible ref(false) const InputRef refInputInstance() const handleClose (tag: string) { dynamicTags.value.splice(dynamicTags.value.indexOf(tag), 1) } const showInput () { inputVisible.value true nextTick(() { InputRef.value!.input!.focus() }) } const handleInputConfirm () { if (inputValue.value) { dynamicTags.value.push(inputValue.value) } inputVisible.value false inputValue.value } /script实现要点handleClose通过splice从数组中删除对应标签showInput切换输入框可见状态并借助nextTick在 DOM 更新后自动聚焦输入框handleInputConfirm同时绑定keyup.enter与blur两个操作路径都能完成确认新增其中click.stop源码内部与stop语义保持一致避免交互冲突标签的close会收到原生MouseEvent事件对象示例中直接用标签文本作为标识进行删除。这是典型的标签输入器类似邮件收件人输入场景的基础范式可在此基础上扩展防重复校验、最大数量限制等业务逻辑。尺寸Sizes除默认尺寸外Tag 组件还提供了三种可选尺寸large、default、small通过size属性设置。当不传size时标签会继承外层el-form/el-form-item的size配置——源码中使用useFormSize()获取表单上下文尺寸见 packages/components/tag/src/tag.vue这与 Button、Input 等组件的尺寸联动行为保持一致。示例代码完整代码见 docs/examples/tag/sizes.vuetemplate div classflex gap-2 el-tag sizelargeLarge/el-tag el-tagDefault/el-tag el-tag sizesmallSmall/el-tag /div /templatesize的合法取值定义在常量componentSizes中即large | default | small见 packages/components/tag/src/tag.ts。主题ThemeTag 提供三种主题dark、light、plain通过effect属性切换默认值为light。dark实心深色背景 白色文字对比最强light浅色背景 深色文字柔和醒目是默认主题plain白色/极浅背景 描边 主题色文字视觉最轻。示例代码完整代码见 docs/examples/tag/theme.vuetemplate div classflex gap-2 spanDark/span el-tag v-foritem in items :keyitem.label :typeitem.type effectdark {{ item.label }} /el-tag /div div classflex gap-2 mt-4 spanLight/span el-tag v-foritem in items :keyitem.label :typeitem.type effectlight {{ item.label }} /el-tag /div div classflex gap-2 mt-4 spanPlain/span el-tag v-foritem in items :keyitem.label :typeitem.type effectplain {{ item.label }} /el-tag /div /template script langts setup import { ref } from vue import type { TagProps } from element-plus type Item { type: TagProps[type]; label: string } const items refArrayItem([ { type: primary, label: Tag 1 }, { type: success, label: Tag 2 }, { type: info, label: Tag 3 }, { type: warning, label: Tag 4 }, { type: danger, label: Tag 5 }, ]) /script三种主题 × 五种类型可以自由组合覆盖绝大多数状态标记场景例如dangerdark用于强提示、successplain用于弱化展示。圆角标签Rounded与 Button 类似Tag 也可以设置为圆角样式只需添加round属性即可。圆角后的标签在胶囊形筛选条、趋势词云等场景中更常见。示例代码完整代码见 docs/examples/tag/rounded.vuetemplate div classflex gap-2 el-tag v-foritem in items :keyitem.label :typeitem.type effectdark round {{ item.label }} /el-tag /div div classflex gap-2 mt-4 el-tag v-foritem in items :keyitem.label :typeitem.type effectlight round {{ item.label }} /el-tag /div div classflex gap-2 mt-4 el-tag v-foritem in items :keyitem.label :typeitem.type effectplain round {{ item.label }} /el-tag /div /template从源码看round与type、hit、effect、closable、size一起参与containerKls的类名计算见 packages/components/tag/src/tag.vue样式由is-round修饰类驱动主题样式定义在 theme-chalk 的 tag.scss 中。可选中标签CheckTag有些业务需要复选框式的标签选中 / 未选中二态切换但 Button 形态的 checkbox 又无法满足需求此时应使用check-tag即el-check-tag组件。它的 API 非常简单checked / v-model:checked是否选中Boolean默认falsedisabled是否禁用Boolean默认false自 ^(2.8.2) 起支持typeCheckTag 的类型自 ^(2.5.4) 起支持取值primary | success | info | warning | danger默认primarychange事件点击时触发回调参数为切换后的布尔值(value: boolean) void。示例代码完整代码见 docs/examples/tag/checkable.vuetemplate div classflex gap-2 el-check-tag checkedChecked/el-check-tag el-check-tag :checkedchecked changeonChangeToggle me/el-check-tag el-check-tag disabledDisabled/el-check-tag /div div classflex gap-2 mt-4 el-check-tag :checkedchecked1 typeprimary changeonChange1 Tag 1 /el-check-tag el-check-tag :checkedchecked2 typesuccess changeonChange2 Tag 2 /el-check-tag el-check-tag :checkedchecked3 typeinfo changeonChange3 Tag 3 /el-check-tag el-check-tag :checkedchecked4 typewarning changeonChange4 Tag 4 /el-check-tag el-check-tag :checkedchecked5 typedanger changeonChange5 Tag 5 /el-check-tag el-check-tag :checkedchecked6 disabled typesuccess changeonChange6 Tag 6 /el-check-tag /div /template script langts setup import { ref } from vue const checked ref(false) const checked1 ref(true) const checked2 ref(true) const checked3 ref(true) const checked4 ref(true) const checked5 ref(true) const checked6 ref(true) const onChange (status: boolean) { checked.value status } // onChange1 ~ onChange6 同理将 status 写入对应 ref /script从源码 packages/components/check-tag/src/check-tag.vue 可以看到其实现逻辑点击根元素触发handleChange若disabled为true则直接return不产生任何事件否则取反得到checked !props.checked同时派发change事件与update:checked事件因此既支持change监听也天然支持v-model:checked双向绑定类名计算中通过is-checked、is-disabled以及m(type)三个修饰类控制选中态、禁用态与类型配色。组件是一个受控 半受控结合的轻量实现即使不写v-model点击也会通过change事件把新状态交还给你手动维护。Tag API 完整参考以下内容与官方文档 docs/en-US/component/tag.md 保持一致并结合源码 packages/components/tag/src/tag.ts 补充取值与默认值说明。Tag Attributes名称说明类型默认值typeTag 类型^[enum]primary \| success \| info \| warning \| dangerprimaryclosable是否可移除^[boolean]falsedisable-transitions是否禁用动画^[boolean]falsehit是否有高亮边框^[boolean]falsecolorTag 背景色^[string]—sizeTag 尺寸^[enum]large \| default \| small—effectTag 主题^[enum]dark \| light \| plainlightround是否为圆角^[boolean]false补充说明type的默认值primary与effect的默认值light在源码withDefaults与buildProps中均有双重定义见 packages/components/tag/src/tag.vuesize未设置时继承表单上下文尺寸useFormSize因此放在el-form中的 Tag 会自动跟随表单尺寸hit表示命中高亮用于搜索结果等场景下标记命中的标签会呈现高亮描边效果disable-transitions为true时源码直接渲染纯span分支无transition包裹同时保留el-zoom-in-center过渡的引入仅作为关闭动画的手段。Tag Events名称说明类型click点击 Tag 时触发^[Function](evt: MouseEvent) voidclose移除 Tag 时触发^[Function](evt: MouseEvent) void源码中tagEmits对两个事件均做了evt instanceof MouseEvent的类型守卫校验见 packages/components/tag/src/tag.ts不符合预期的调用会在开发期收到类型告警。Tag Slots名称说明default自定义默认内容CheckTag API 完整参考CheckTag Attributes名称说明类型默认值checked / v-model:checked是否选中^[boolean]falsedisabled ^(2.8.2)是否禁用^[boolean]falsetype ^(2.5.4)CheckTag 类型^[enum]primary \| success \| info \| warning \| dangerprimaryCheckTag Events名称说明类型change点击 Check Tag 时触发^[Function](value: boolean) voidCheckTag Slots名称说明default自定义默认内容源码层面的实现细节1. 关闭按钮的可用性与事件隔离关闭按钮使用原生button typebutton并携带aria-label文案来自useLocale国际化表el.tag.close保证键盘可聚焦、屏幕阅读器可读。click.stop确保点击关闭按钮只触发close而不会连带触发click。2. 过渡动画的取舍disable-transitions直接决定渲染分支false默认时外层包一层transition nameel-zoom-in-center appear标签挂载与移除均有缩放 淡出动效true时退化为普通元素适合高频增删、追求极简交互的场景。3. 类型体系与扩展约定TagProps接口与tagProps运行时 props 同时存在其中tagProps与TagPropsPublic均被标记为deprecatedRemoved after 3.0.0, UseTagPropsinstead见 packages/components/tag/src/tag.ts即推荐直接使用类型层面的TagProps进行 TS 推导如示例中的TagProps[type]运行时 props 结构保持兼容。组件测试见 packages/components/tag/tests/tag.test.tsx。4. 与表单体系的联动useFormSize()让 Tag 无需显式传size也能与el-form/el-form-item的尺寸配置保持一致这在批量渲染标签的场景如表格操作列、筛选器中非常实用避免逐个设置尺寸。总结按场景选型业务场景推荐方案静态状态展示el-tagtypeeffect搜索结果命中高亮el-tag hit可删除的筛选条件el-tag closable close...动态新增/删除标签复用editable示例中的 输入框 按钮 闭环需要切换选中态的标签el-check-tag v-model:checked禁用状态的可选标签el-check-tag disabled自 2.8.2 起自定义品牌背景色el-tag color#xxx从基础的类型与主题到可关闭、动态编辑再到 CheckTag 的可选中交互Tag 家族覆盖了标记与选择的绝大多数使用场景。结合源码阅读可以看到其在事件隔离、无障碍aria-label、表单尺寸联动与受控状态管理上的细致设计值得在实现自定义标签类组件时参考。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考