更新记录
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 } 或纯字符串均可。

收藏人数:
购买普通授权版(
试用
赞赏(0)
下载 13
赞赏 0
下载 12771027
赞赏 1959
赞赏
京公网安备:11010802035340号