Tag 标签

用于标记状态、属性、分类或筛选条件，常见于列表、表格、详情页和筛选区域。

何时使用

标记对象的状态、分类、来源或属性。
展示可关闭的筛选条件。
用作轻量级的可选项，但不承载复杂表单交互。

基础用法

默认标签蓝色标签绿色标签自定义颜色

vue

<template>
  <x-tag>默认标签</x-tag>
  <x-tag color="blue">蓝色标签</x-tag>
  <x-tag color="green">绿色标签</x-tag>
  <x-tag color="#0f766e">自定义颜色</x-tag>
</template>

内置颜色

redorangeredorangegoldlimegreencyanbluebetter-bluepurplepink-purplemagentagray

vue

<template>
  <x-tag v-for="color in colors" :key="color" :color="color">
    {{ color }}
  </x-tag>
</template>

<script setup lang="ts">
const colors = [
  'red',
  'orangered',
  'orange',
  'gold',
  'lime',
  'green',
  'cyan',
  'blue',
  'better-blue',
  'purple',
  'pink-purple',
  'magenta',
  'gray',
];
</script>

尺寸

小型标签中型标签大型标签

vue

<template>
  <x-tag size="small">小型标签</x-tag>
  <x-tag>中型标签</x-tag>
  <x-tag size="large">大型标签</x-tag>
</template>

带边框

默认边框蓝色边框绿色边框品红边框

vue

<template>
  <x-tag bordered>默认边框</x-tag>
  <x-tag color="blue" bordered>蓝色边框</x-tag>
  <x-tag color="green" bordered>绿色边框</x-tag>
  <x-tag color="magenta" bordered>品红边框</x-tag>
</template>

可关闭

可关闭关闭事件受控显示关闭事件：0

vue

<template>
  <x-tag closable>可关闭</x-tag>
  <x-tag color="orange" closable @close="handleClose">关闭事件</x-tag>
  <x-tag v-model:visible="visible" color="purple" closable>受控显示</x-tag>
  <x-button size="mini" @click="visible = true">重置</x-button>
  <span aria-live="polite">关闭事件：{{ closeCount }}</span>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const visible = ref(true);
const closeCount = ref(0);
const handleClose = () => { closeCount.value += 1; };
</script>

可选择

默认可选未选中受控选择当前：已选

vue

<template>
  <x-tag selectable>默认可选</x-tag>
  <x-tag color="red" selectable :default-checked="false">未选中</x-tag>
  <x-tag v-model:checked="checked" color="better-blue" selectable>受控选择</x-tag>
  <span>当前：{{ checked ? '已选' : '未选' }}</span>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const checked = ref(true);
</script>

加载中

同步中发布中自定义颜色

vue

<template>
  <x-tag loading>同步中</x-tag>
  <x-tag color="blue" loading>发布中</x-tag>
  <x-tag color="#0f766e" loading>自定义颜色</x-tag>
</template>

loading 展示加载图标，保持文字不透明；它不会阻止选择或关闭。

图标与自定义关闭图标

已完成自定义关闭

vue

<template>
  <x-tag color="green">
    <template #icon>
      <span aria-hidden="true">✓</span>
    </template>
    已完成
  </x-tag>
  <x-tag color="orange" closable>
    <template #close-icon>
      <span aria-hidden="true">x</span>
    </template>
    自定义关闭
  </x-tag>
</template>

动态编辑

VueTypeScriptVitePress+ 新增

vue

<template>
  <x-tag v-for="tag in dynamicTags" :key="tag" closable @close="removeTag(tag)">
    {{ tag }}
  </x-tag>
  <x-input
    v-if="editing"
    v-model="newTag"
    size="mini"
    placeholder="新增标签"
    style="width: 96px"
    @press-enter="addTag"
    @blur="addTag"
  />
  <x-tag v-else bordered @click="editing = true">+ 新增</x-tag>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const dynamicTags = ref(['Vue', 'TypeScript', 'VitePress']);
const editing = ref(false);
const newTag = ref('');

const removeTag = (tag: string) => {
  dynamicTags.value = dynamicTags.value.filter((item) => item !== tag);
};

const addTag = () => {
  const value = newTag.value.trim();
  if (value && !dynamicTags.value.includes(value)) {
    dynamicTags.value.push(value);
  }
  newTag.value = '';
  editing.value = false;
};
</script>

不换行

这是一段很长但不会换行的标签内容

vue

<template>
  <x-tag nowrap style="max-width: 180px">
    这是一段很长但不会换行的标签内容
  </x-tag>
</template>

亮暗颜色与选择反馈

内置色的文字色与背景分开定义。取消选择后恢复默认文字和透明背景，再次选中恢复对应颜色；悬浮仍有默认弱底反馈。下例可切换局部暗色，并通过页面计数确认 check 回调。

切换标签暗色

redorangeredorangegoldlimegreencyanbluebetter-bluepurplepink-purplemagentagray加载颜色自定义亮色

选择事件：0；关闭事件：0

vue

<template>
  <label><x-switch v-model="dark" />切换标签暗色</label>
  <x-config-provider :dark="dark" class="color-scope">
    <div class="color-row">
      <x-tag v-for="color in colors" :key="color" :color="color" selectable bordered closable :visible="true" @check="checks++" @close="closes++">{{ color }}</x-tag>
      <x-tag color="gold" loading>加载颜色</x-tag>
      <x-tag color="#ffb800" selectable style="--x-tag-custom-color-text: var(--x-color-constant-dark)">自定义亮色</x-tag>
    </div>
    <p aria-live="polite">选择事件：{{ checks }}；关闭事件：{{ closes }}</p>
  </x-config-provider>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { ConfigProvider as XConfigProvider, Switch as XSwitch, Tag as XTag } from 'x-next';
import 'x-next/style.css';

const dark = ref(false);
const checks = ref(0);
const closes = ref(0);
const colors = ['red', 'orangered', 'orange', 'gold', 'lime', 'green', 'cyan', 'blue', 'better-blue', 'purple', 'pink-purple', 'magenta', 'gray'];
</script>

<style scoped>
.color-row {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
.color-scope {
  padding: 16px;
  color: var(--x-color-text-primary);
  background: var(--x-color-bg-surface);
}
</style>

这里用 visible=true 展示受控关闭：按钮会触发 close，父层未更新 visible 时标签仍保留，关闭不会触发选择。自定义色默认用白字，亮色背景需显式覆盖 --x-tag-custom-color-text，组件不自动推导任意 CSS 背景的前景色。页面为暗色时，请先切回亮色观察局部对照；dark=false 不会重置暗色祖先。

selectable 当前支持鼠标切换，尚未提供键盘选择和独立 disabled 属性；关闭按钮可通过 Tab 聚焦后用 Enter 或 Space 激活。

按需导入

import { Tag } from 'x-next';

样式按需引入（base.css 为共享基础层，多个组件只需引入一次）：

import 'x-next/style/base.css';
import 'x-next/style/tag.css';

Props

参数	说明	类型	默认值
`color`	标签颜色，支持内置色或自定义 CSS 色值	`TagColor \| string`	`-`
`size`	标签尺寸	`'small' \| 'medium' \| 'large'`	`'medium'`
`bordered`	是否显示边框	`boolean`	`false`
`visible`	标签是否可见，支持 `v-model:visible`	`boolean`	`undefined`
`defaultVisible`	默认是否可见，非受控模式	`boolean`	`true`
`loading`	是否为加载状态	`boolean`	`false`
`closable`	是否可关闭	`boolean`	`false`
`selectable`	是否可选择	`boolean`	`false`
`checked`	是否选中，仅 `selectable` 时有效，支持 `v-model:checked`	`boolean`	`undefined`
`defaultChecked`	默认是否选中，非受控模式	`boolean`	`true`
`nowrap`	标签内容是否不换行	`boolean`	`false`
`closeAriaLabel`	关闭按钮的无障碍名称，默认“关闭标签”	`string`	`-`

TagColor

red、orangered、orange、gold、lime、green、cyan、blue、better-blue、purple、pink-purple、magenta、gray

Events

事件名	说明	回调参数
`update:visible`	可见状态变化时触发	`visible: boolean`
`update:checked`	选中状态变化时触发	`checked: boolean`
`close`	点击关闭按钮时触发	`event: MouseEvent`
`check`	点击可选择标签时触发	`checked: boolean, event: MouseEvent`

Slots

插槽名	说明
`default`	标签内容
`icon`	自定义图标
`close-icon`	自定义关闭图标

Tag 标签 ​

何时使用 ​

基础用法 ​

内置颜色 ​

尺寸 ​

带边框 ​

可关闭 ​

可选择 ​

加载中 ​

图标与自定义关闭图标 ​

动态编辑 ​

不换行 ​

亮暗颜色与选择反馈 ​

按需导入 ​

Props ​

TagColor ​

Events ​

Slots ​