XtfTagGroup

组件说明

xtf-tag-group 是可选择、可删除的标签集合组件，适用于筛选条件和标签管理。既可由 options 数据驱动，也可与 xtf-tag-group-item 配合通过插槽渲染复杂条目。

---

基础用法

1. 数据驱动选择

<template><xtf-tag-group v-model="selected" :options="options" /></template>
<script>
export default {
  data() {
    return {
      selected: ['new'],
      options: [
        { value: 'new', text: '新品' },
        { value: 'sale', text: '促销' }
      ]
    }
  }
}
</script>

2. 选择限制和删除

<template>
  <xtf-tag-group
    v-model="selected"
    :options="options"
    closable
    :max="2"
    @change="changed"
    @delete="deleted"
    @selection-limit="limited"
    @update:options="options = $event"
  />
</template>
<script>
export default {
  data() {
    return {
      selected: [],
      options: [
        { value: 'a', text: 'A' },
        { value: 'b', text: 'B' },
        { value: 'c', text: 'C' }
      ]
    }
  },
  methods: {
    changed(p) {
      console.log(p.values)
    },
    deleted(p) {
      uni.showToast({ title: p.tag.text, icon: 'none' })
    },
    limited(p) {
      console.log(p.type)
    }
  }
}
</script>

3. 自定义条目插槽

插槽模式使用 xtf-tag-group-item 注册条目，插槽参数提供真实选中状态和操作函数。

<template>
  <xtf-tag-group v-model="selected" :max="1">
    <xtf-tag-group-item value="fast" text="极速配送">
      <template #default="p">
        <xtf-card @click="p.toggle">
          <xtf-text :text="p.selected ? '已选择极速配送' : '选择极速配送'" /><xtf-button
            size="xs"
            label="移除"
            @click.stop="p.remove" /></xtf-card></template>
</xtf-tag-group-item>
  </xtf-tag-group>
</template>
<script>
export default {
  data() {
    return { selected: [] }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
options	Array	[]	数据驱动的标签数组	非插槽模式
value	Array | String | Number | Boolean	undefined	Vue 2 兼容的受控值	旧式双向绑定
modelValue	Array | String | Number | Boolean	undefined	优先级最高的受控值	v-model
multiple	Boolean	true	是否多选	单选筛选设为 false
max	Number | String	0	最大选择数，0 不限制	限制筛选数
min	Number | String	0	最小保留选择数，0 不限制	必选标签
checkable	Boolean	true	全局是否允许选择	仅展示标签
closable	Boolean	false	全局是否允许删除	标签管理
disabled	Boolean	false	禁用所有标签	不可编辑状态
layoutMode	String	'flow'	flow 流式或 manager 单列管理布局	管理列表
layout	String	''	manager 的兼容布局字段	兼容已有数据
direction	String	'row'	row 或 column 排列方向	流式布局
wrap	Boolean	true	流式布局是否换行	单行横排
gap	String | Number	16	条目间距	调整密度
valueKey	String	'value'	options 的业务值字段名	对接异构数据
labelKey	String	'label'	options 的显示字段名	对接异构数据
theme	String	''	默认标签主题	统一语义色
variant	String	''	默认标签变体	统一外观
shape	String	''	默认标签形状	统一外观
size	String	''	默认标签尺寸	统一密度
color	String	''	默认标签自定义颜色	品牌色标签
customClass	String	''	根节点类名	局部定制
customStyle	String | Object	''	根节点样式	局部定制

options 每项支持的字段

字段	类型	默认值	说明
value / valueKey 指定字段	String | Number | Boolean	索引	标签业务值
text / label / labelKey 指定字段	String	值的字符串形式	显示文字
key	String | Number	value	唯一身份标识
disabled	Boolean	false	禁用单个标签
checkable	Boolean	继承组属性	覆盖单项可选状态
closable	Boolean	继承组属性	覆盖单项可删除状态
theme / variant / shape / size / color	String	继承组属性	覆盖单项 xtf-tag 外观
其他 xtf-tag 属性	Any	-	会透传给内部 xtf-tag

---

事件

事件名称	触发时机	回调参数	参数说明
input	选中值变化时	(value: Array | Any)	multiple 为假时返回单值
update:modelValue	选中值变化时	(value: Array | Any)	用于 v-model
update:options	删除条目时	(tags: Array)	删除后的序列化标签数组
change	选中值变化时	(payload: Object)	选择变化完整数据
selection-change	选中值变化时	(payload: Object)	同 change
selection-limit	达到 max 或 min 限制时	(payload: Object)	{ type, max/min, tag, selectedValues, allTags }
tag-click	点击条目时	(payload: Object)	{ tag, item, index, selectedValues, allTags }
item-click	点击条目时	(payload: Object)	同 tag-click
delete	删除条目时	(payload: Object)	{ tag, item, index, allTags, selectedValues, selectedTags }
remove	删除条目时	(payload: Object)	同 delete
close	删除条目时	(payload: Object)	同 delete

事件使用示例

<template>
  <xtf-tag-group
    v-model="selected"
    :options="options"
    closable
    @change="change"
    @tag-click="click"
    @delete="remove"
  />
</template>
<script>
export default {
  data() {
    return { selected: [], options: [{ value: 'vip', text: '会员' }] }
  },
  methods: {
    change(p) {
      console.log('selected', p.values)
    },
    click(p) {
      console.log('click', p.index)
    },
    remove(p) {
      uni.showToast({ title: '已删除 ' + p.tag.text, icon: 'none' })
    }
  }
}
</script>

---

方法

1. getTags() — 获取全部当前标签

无参数，返回 Array，每项含 value、text、checked、index。

<template>
  <view>
    <xtf-button label="全部标签" @click="read" /><xtf-tag-group
      ref="group"
      :options="[{ value: 'a', text: 'A' }]"
  /></view>
</template>
<script>
export default {
  methods: {
    read() {
      console.log(this.$refs.group.getTags())
    }
  }
}
</script>

2. getSelectedValues() — 获取已选值

无参数，返回 Array。

const values = this.$refs.group.getSelectedValues()

3. getSelectedTags() — 获取已选标签对象

无参数，返回 Array；每项结构与 getTags() 一致。

const tags = this.$refs.group.getSelectedTags()

---

主题说明

• 间距由 var(--xtf-tag-group-gap) 控制，组件根据 gap 写入该变量。
• 标签外观继承 xtf-tag 的主题变量和 theme、variant 等属性。
• 在 xtf-config-provider 覆盖标签主题，或以组属性设置默认外观。