xtf-linkui

Appearance

xtf-tag ​

组件说明 ​

xtf-tag 是标签组件，用于展示标记、状态或筛选。支持 solid / light / soft / outlined / ghost / glass 六种变体、6 种主题色、xxs~lg 五档尺寸，以及 status / success / warning / danger / feature / hot / promo / location / mark / filter / glass / im 12 种预设场景。提供图标、关闭（closable）、可选中（checkable）、圆点/角标形状（shape）等能力，是状态展示与筛选场景的核心组件。

基础用法 ​

1. 最简示例 ​

通过 text 设置文字，theme 控制主题色，variant 控制变体：

vue
<template>
  <view style="display: flex; gap: 16rpx; flex-wrap: wrap; padding: 32rpx">
    <xtf-tag text="默认" />
    <xtf-tag text="成功" theme="success" />
    <xtf-tag text="警告" theme="warning" />
    <xtf-tag text="危险" theme="danger" />
  </view>
</template>

2. 变体与形状 ​

通过 variant 切换视觉形态，通过 shape 切换 round / dot / mark 形状：

vue
<template>
  <view style="display: flex; flex-direction: column; gap: 24rpx; padding: 32rpx">
    <view style="display: flex; gap: 16rpx; flex-wrap: wrap">
      <xtf-tag text="实心" variant="solid" />
      <xtf-tag text="浅色" variant="light" />
      <xtf-tag text="柔和" variant="soft" />
      <xtf-tag text="描边" variant="outlined" />
      <xtf-tag text="幽灵" variant="ghost" />
      <xtf-tag text="玻璃" variant="glass" />
    </view>
    <view style="display: flex; gap: 16rpx; flex-wrap: wrap; align-items: center">
      <xtf-tag text="圆角" shape="round" />
      <xtf-tag shape="dot" text="圆点" />
      <xtf-tag shape="mark" text="角标" theme="warning" variant="light" />
    </view>
  </view>
</template>

3. 预设场景 ​

通过 preset 一键应用业务预设：

vue
<template>
  <view style="display: flex; gap: 16rpx; flex-wrap: wrap; padding: 32rpx">
    <xtf-tag preset="status" text="进行中" />
    <xtf-tag preset="success" text="已完成" />
    <xtf-tag preset="warning" text="待处理" />
    <xtf-tag preset="danger" text="已过期" />
    <xtf-tag preset="hot" text="热卖" />
    <xtf-tag preset="promo" text="促销" />
    <xtf-tag preset="location" text="附近" />
    <xtf-tag preset="feature" text="推荐" />
  </view>
</template>

4. 图标与关闭 ​

通过 icon 添加图标，通过 closable 开启关闭按钮（触发 close 事件后自动隐藏）：

vue
<template>
  <view style="display: flex; flex-direction: column; gap: 24rpx; padding: 32rpx">
    <view style="display: flex; gap: 16rpx; flex-wrap: wrap">
      <xtf-tag text="带图标" icon="star" theme="warning" />
      <xtf-tag text="筛选" preset="filter" />
    </view>
    <view style="display: flex; gap: 16rpx; flex-wrap: wrap">
      <xtf-tag text="可关闭" closable @close="onClose" />
      <xtf-tag text="标签1" closable theme="success" @close="onClose" />
      <xtf-tag text="标签2" closable theme="info" @close="onClose" />
    </view>
  </view>
</template>

<script>
export default {
  methods: {
    onClose(e) {
      console.log('关闭标签', e)
      uni.showToast({ title: '已移除标签', icon: 'none' })
    }
  }
}
</script>

5. 可选中标签 ​

通过 checkable 开启可选中能力，v-model:checked 双向绑定选中态，切换触发 change 事件：

vue
<template>
  <view style="display: flex; gap: 16rpx; flex-wrap: wrap; padding: 32rpx">
    <xtf-tag
      v-for="item in tags"
      :key="item"
      :text="item"
      preset="filter"
      checkable
      :checked="checked === item"
      @change="onChange(item, $event)"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      tags: ['全部', '最新', '热销', '好评'],
      checked: '全部'
    }
  },
  methods: {
    onChange(item, checked) {
      this.checked = checked ? item : '全部'
      console.log('当前选中:', this.checked)
    }
  }
}
</script>

6. 尺寸与自定义 ​

通过 size 控制尺寸，通过 color / bg-color / text-color 自定义颜色：

vue
<template>
  <view style="display: flex; flex-direction: column; gap: 24rpx; padding: 32rpx">
    <view style="display: flex; gap: 16rpx; align-items: center; flex-wrap: wrap">
      <xtf-tag text="超小" size="xxs" />
      <xtf-tag text="小" size="xs" />
      <xtf-tag text="中" size="md" />
      <xtf-tag text="大" size="lg" />
    </view>
    <view style="display: flex; gap: 16rpx; flex-wrap: wrap">
      <xtf-tag text="自定义紫" variant="solid" color="#8B5CF6" />
      <xtf-tag text="浅紫底" variant="light" color="#8B5CF6" />
      <xtf-tag text="渐变" gradient color="#6366F1" gradient-end-color="#EC4899" />
    </view>
  </view>
</template>

全部属性 ​

属性类型默认值作用描述适用范围
textString''标签文字设置文案
labelString''标签文字（text 的别名）设置文案
themeString'primary'主题色：'primary' / 'success' / 'warning' / 'danger' / 'info' / 'secondary'切换颜色
presetString''业务预设：'status' / 'success' / 'warning' / 'danger' / 'feature' / 'hot' / 'promo' / 'location' / 'mark' / 'filter' / 'glass' / 'im'一键应用场景
colorString''自定义主色精确控制颜色
variantString'solid'变体：'solid' / 'light' / 'soft' / 'outlined' / 'ghost' / 'glass'切换视觉形态
shapeString'default'形状：'round' / 'dot' / 'mark'切换形状
sizeString''尺寸：'xxs' / 'xs' / 'sm' / 'md' / 'lg'，默认继承 configProvider控制大小
iconString''图标名（xtf-icon）带图标
iconPositionString'start'图标位置：'start' / 'end'图标布局
iconSizeString | Number''图标大小图标尺寸
closableBooleanfalse是否可关闭可移除标签
checkableBooleanfalse是否可选中筛选场景
checkedBoolean | String | Numberfalse选中态（v-model:checked）筛选选中
gradientBooleanfalse是否渐变强调标签
glassBooleanfalse是否玻璃态玻璃风格
blockBooleanfalse是否块级占满布局
hairlineBooleanfalse细边框（1rpx）细线风格
bgColorString''自定义背景色精确控制背景
textColorString''自定义文字色精确控制文字
borderColorString''自定义边框色精确控制边框
softColorString''自定义柔和背景色浅色变体
gradientEndColorString''渐变结束色渐变标签
glassColorString''玻璃态背景色玻璃风格
dotColorString''圆点颜色（shape="dot"）圆点标签
closeBgColorString''关闭按钮背景色关闭按钮
checkedVariantString'solid'选中时变体筛选选中
uncheckedVariantString'outlined'未选中时变体筛选未选中
disabledBooleanfalse是否禁用禁用交互
showBoolean | String | Numbertrue是否显示（v-model:show），closable 关闭后为 false显隐控制
ellipsisBooleanfalse文字超出省略长文案
maxWidthString | Number''最大宽度限制宽度
motionString''动效：'pulse' / 'bounce'强调动画
customClassString''自定义类名样式覆盖
customStyleString | Object''自定义样式动态样式覆盖

事件 ​

事件名称触发时机回调参数参数说明
click点击标签时触发（disabled 不触发）(event)点击事件对象
change可选中标签切换选中态时触发(value: Boolean)切换后的选中态
close点击关闭按钮时触发（disabled 不触发）(event)点击事件对象
update:checked可选中标签选中态同步(value: Boolean)切换后的选中态
update:showclosable 关闭后同步 show(value: Boolean)关闭后为 false

事件使用示例 ​

vue
<template>
  <view style="display: flex; flex-direction: column; gap: 24rpx; padding: 32rpx">
    <view style="display: flex; gap: 16rpx; flex-wrap: wrap">
      <xtf-tag
        v-for="tag in tags"
        :key="tag.id"
        :text="tag.name"
        preset="filter"
        checkable
        :checked="selected === tag.name"
        @change="onTagChange(tag.name, $event)"
      />
    </view>
    <view style="display: flex; gap: 16rpx; flex-wrap: wrap">
      <xtf-tag text="可移除标签" closable @close="onClose" @click="onClick" />
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      tags: [
        { id: 1, name: '最新' },
        { id: 2, name: '热销' },
        { id: 3, name: '好评' }
      ],
      selected: '热销'
    }
  },
  methods: {
    onTagChange(name, checked) {
      this.selected = checked ? name : ''
      console.log('标签 change:', name, checked)
      uni.showToast({ title: '筛选已切换', icon: 'none' })
    },
    onClick(e) {
      console.log('点击标签', e)
    },
    onClose(e) {
      console.log('关闭标签', e)
      uni.showToast({ title: '已移除', icon: 'none' })
    }
  }
}
</script>

插槽 ​

插槽名称说明
default标签文字内容（有 text 属性时默认插槽优先）
prefix文字前置内容（如自定义图标）
suffix文字后置内容（如自定义图标）

插槽使用示例 ​

通过 prefix / suffix 插槽插入自定义图标或加载状态：

vue
<template>
  <view style="display: flex; gap: 16rpx; flex-wrap: wrap; padding: 32rpx">
    <xtf-tag text="带前缀图标" shape="round" theme="success">
      <template #prefix>
        <xtf-icon name="check_circle" size="xxs" />
      </template>
    </xtf-tag>
    <xtf-tag text="下载中" shape="round" theme="info">
      <template #suffix>
        <xtf-icon name="download" size="xxs" />
      </template>
    </xtf-tag>
  </view>
</template>

主题说明 ​

  • 实心背景使用 var(--xtf-tag-solid-shadow)，柔和背景使用 var(--xtf-tag-soft-shadow)
  • 玻璃态模糊使用 var(--xtf-tag-glass-blur)，阴影使用 var(--xtf-tag-glass-shadow)
  • 各主题色对应 --xtf-color-{theme} 与 --xtf-color-{theme}-soft 变量
  • 圆角使用 var(--xtf-radius-lg)，全圆角使用 var(--xtf-radius-full)
  • 选中按压使用 scale(0.96) 变换，pulse / bounce 动效有对应 @keyframes

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。

MIT Licensed

Copyright © 2026 xtf-linkui