更新记录

1.2.0(2026-11-17)

  • 组件更名为 x-tag-select,增加 6 种配色方案 (theme),完善 PC 端交互与键盘操作

平台兼容性

x-tag-select(标签选择器)

一个纯前端的 uni-app 组件:输入关键字触发远程搜索,选中后以标签形式展示,支持标签删除、退格删除、重复项过滤与下拉滑动防误选。 搜索逻辑通过 search 属性由业务方注入,组件本身不依赖任何请求库,可用于标签、分类、关键词等多选场景。

平台支持

平台 支持情况
App(vue2 / vue3) ✅
H5 ✅
微信小程序 ✅
其他小程序 / 快应用 ⚠️ 未做兼容测试

演示工程

本插件包根目录同时是一个可直接运行的 uni-app(vue2)演示工程:

  • 演示页面:../../../pages/demo/demo.vue
  • 运行方式:用 HBuilderX 打开 tag-select 目录,运行到 H5 / 微信小程序 / App 即可
  • 演示页面使用内置模拟数据模拟远程搜索(延迟 300ms),点击下拉项即可添加标签,并实时展示选中结果
  • 演示页面顶部可切换「小 / 中 / 大」三种组件尺寸、最大标签数量(不限 / 3 / 5 / 10)与六种配色方案,并提示键盘操作方式

使用方法

1. 引入组件

uni_modules 组件支持 easycom 自动引入,无需 import:

<x-tag-select v-model="selectedTags" :search="searchTags" />
<x-tag-select v-model="selectedTags" size="large" :search="searchTags" />
<x-tag-select v-model="selectedTags" size="small" :search="searchTags" />
<x-tag-select v-model="selectedTags" :max="3" :search="searchTags" />

如项目未开启 easycom,可手动引入:

import XTagSelect from '@/uni_modules/x-tag-select/components/x-tag-select/x-tag-select.vue';
export default {
  components: { XTagSelect }
};

2. 注入搜索方法

search 接收 (keyword, { type }),返回 Promise<Array>(也支持同步返回数组):

export default {
  data() {
    return {
      selectedTags: []
    };
  },
  methods: {
    // 返回值支持三种形态:数组、Promise<数组>、{ data: 数组 }
    searchTags(keyword, { type }) {
      return new Promise((resolve, reject) => {
        uni.request({
          url: 'https://example.com/api/searchTags',
          data: { type, keyword },
          success: res => resolve(res.data.data),
          fail: reject
        });
      });
    }
  }
};

3. 完整示例

<template>
  <view class="form-item">
    <text class="label">标签</text>
    <x-tag-select
      v-model="selectedTags"
      type="1"
      placeholder="请输入标签"
      :search="searchTags"
      @select=""
    />
  </view>
</template>

<script>
  export default {
    data() {
      return {
        selectedTags: []
      };
    },
    methods: {
      searchTags(keyword, { type }) {
        return this.$http.get('/api/searchTags', { type, keyword }).then(res => res.data);
      },
      (item) {
        console.log('选中标签', item);
      }
    }
  };
</script>

属性

属性 类型 默认值 说明
value Array [] vue2 v-model 绑定值,元素为 { value, title } 或字符串
modelValue Array - vue3 v-model 绑定值,优先级高于 value
placeholder String 请输入标签 输入框占位提示
type Number / String 1 业务类型,搜索时透传给 search 方法
size String medium 组件尺寸,可选 large / medium / small
theme String default 配色方案,可选 default / primary / success / warning / danger / purple
max Number 0 最多可选的标签数量,0 表示不限制
search Function null 远程搜索方法,(keyword, { type }) => Promise<Array>

尺寸

size 说明
large 大尺寸,输入框更高、字号更大,适合独立表单项
medium 默认尺寸
small 小尺寸,适合表格行内、紧凑表单
<x-tag-select v-model="list" size="large" :search="searchTags" />
<x-tag-select v-model="list" size="small" :search="searchTags" />

配色方案

通过 theme 属性切换标签与下拉高亮的配色:

theme 标签底色 下拉高亮
default cadetblue(青) 浅青
primary #409eff(蓝) #ecf5ff
success #67c23a(绿) #f0f9eb
warning #e6a23c(橙) #fdf6ec
danger #f56c6c(红) #fef0f0
purple #8a63d2(紫) #f3f0fb
<x-tag-select v-model="list" theme="primary" :search="searchTags" />
<x-tag-select v-model="list" theme="danger" :search="searchTags" />

事件

事件名 参数 说明
change Array<{ value, title }> 标签新增或删除后触发(vue2 v-model 使用该事件)
update:modelValue Array<{ value, title }> vue3 v-model 同步
select { value, title } 选中某个搜索结果时触发
max-exceed Number 已达到 max 上限仍尝试添加时触发,参数为 max
focus - 输入框获得焦点
blur - 输入框失去焦点
search-error Error 搜索方法抛错或返回的 Promise 被 reject

交互说明

  • 输入关键字即触发搜索,过期请求的结果会被丢弃,避免快速输入时结果错乱。
  • 点击下拉项选中,选中后自动清空输入并重新聚焦,方便连续录入。
  • PC 端可使用鼠标点击下拉项选中(支持悬停高亮),点击组件外部会自动收起下拉。
  • 已选中的项不会重复添加。
  • 设置 max 后,达到上限时输入框替换为「最多可选 N 项」提示,继续选择不会添加标签并触发 max-exceed;删除标签后输入框自动恢复。
  • 输入框为空时按退格键可删除最后一个标签(H5 / App 支持)。
  • 下拉列表中滑动不会误触发选中。
  • 搜索结果返回后默认高亮第一项;选中项会自动滚动到可视区域内。

键盘操作

按键 行为
↑ 上一个选项(循环)
↓ 下一个选项(循环)
Enter / 软键盘「完成」 确定选中当前高亮项,未高亮时选中第一项
Esc 关闭下拉列表
Backspace(输入框为空) 删除最后一个标签

键盘导航在 H5 端通过原生 keydown 监听实现(uni-app 的 input 组件不对外抛出 keydown 事件);移动端软键盘通过「完成」按钮确定选中。

数据结构

搜索方法与绑定值统一使用如下结构,也兼容字符串数组:

// 推荐
[{ value: 'T01', title: '前端开发' }]
// 兼容
['前端开发']

搜索返回值也兼容常见后端结构:元素为 { value, title }、{ id, name } 或纯字符串均可。

更新日志

见 changelog.md

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。