更新记录

1.1.6（2026-05-20） 下载此版本

添加demo示例文件

1.1.5（2026-05-20） 下载此版本

优化布局

1.1.4（2026-05-20） 下载此版本

修复多选不能搜索的问题；

平台兼容性

uni-app(4.08)

uni-app x(4.08)

qiao-select 搜索下拉选择框

一个支持搜索过滤的下拉选择框组件，适用于 uni-app 项目，兼容 Vue2 和 Vue3。无第三方图标依赖，开箱即用。

示例代码：不确定怎么用时，请先查看组件目录下的 example/demo.vue，内含单选、多选、插槽、禁用等完整可运行示例。

特性

• 支持输入搜索过滤下拉选项（单选、多选均支持）
• 支持 v-model 双向绑定（Vue2 / Vue3）
• 支持单选、多选及多选数量限制
• 支持自定义显示字段、搜索字段、返回值类型
• 支持弹窗在上方 / 下方展示
• 支持禁用、清空、不可搜索（纯点击选择）等模式
• 支持 option、selected 插槽自定义展示
• 内置中/英/法/西等多语言「暂无数据」等提示

安装

将 qiao-select 目录放入项目的 uni_modules 下即可，无需安装 uni-icons 等额外插件。

引入方式

方式一：easycom 自动引入（推荐）

放入 uni_modules 后，页面中可直接使用组件标签（标签名与文件名一致）：

<qiao-select ... />
<!-- 或 -->
<qiaoSelect ... />

方式二：手动引入

import qiaoSelect from '@/uni_modules/qiao-select/components/qiao-select/qiaoSelect.vue'

export default {
  components: { qiaoSelect }
}

Vue2 必须 components 注册；Vue3 手动引入后同样需注册（若未走 easycom）。

更多用法与场景组合请参考 example/demo.vue。

快速开始

<view class="select-wrap">
  <qiaoSelect
    :keyId="1"
    :dataList="orgArray"
    phText="请选择机构"
    showKey="name"
    searchKey="name"
    v-model="value"
    @change="onChange"
  />
</view>

data() {
  return {
    orgArray: [
      { id: 1, name: '机构A' },
      { id: 2, name: '机构B' },
      { id: 3, name: '机构C' }
    ],
    value: null
  }
},
methods: {
  onChange(val) {
    console.log('选中：', val) // 清空时为 null
  }
}

属性说明

事件说明

Vue3 同时支持 update:modelValue；Vue2 同时触发 input 事件，与 change 参数一致。

方法

通过 ref 调用：

<qiaoSelect ref="selectRef" ... />

// 清空选中（多选清空为 []，单选为 null）
this.$refs.selectRef.clickClear()

单选模式

基础单选

<qiaoSelect
  :keyId="1"
  :dataList="list"
  showKey="name"
  phText="请选择"
  v-model="value"
/>

returnType = 'key'

只返回指定字段值，适合与后端 id 对接：

<qiaoSelect
  :dataList="list"
  showKey="name"
  returnType="key"
  returnKey="id"
  v-model="selectedId"
/>

// selectedId 示例：1、2、3 ...

不可搜索（纯选择）

不弹出键盘，适合选项较少或移动端点击选择场景：

<qiaoSelect
  :dataList="list"
  showKey="label"
  :searchable="false"
  phText="请选择状态"
  v-model="status"
/>

弹窗在上方

<qiaoSelect popupPosition="top" ... />

多选模式

<qiaoSelect
  :keyId="2"
  :dataList="fruitList"
  showKey="name"
  phText="请选择水果（最多3项）"
  :multiple="true"
  :multipleLimit="3"
  v-model="fruits"
  @change="onFruitsChange"
/>

data() {
  return {
    fruitList: [
      { id: 1, name: '苹果' },
      { id: 2, name: '香蕉' }
    ],
    // returnType='object' 时绑定对象数组
    fruits: []
    // returnType='key' + returnKey='id' 时绑定 [1, 2]
  }
}

多选行为说明：

多选 + 搜索交互：

1. 未聚焦 / 已失焦：输入框显示已选摘要（如「苹果、香蕉」）
2. 点击输入框聚焦：输入框清空，可输入关键词过滤（已选项不受影响）
3. 输入框失焦或点击遮罩关闭：恢复显示已选摘要
4. 弹层打开期间可多次搜索、点选，摘要仅在失焦后回显

设置默认值

// 单选 + returnType='object'
this.value = { id: 1, name: '机构A' }

// 单选 + returnType='key'
this.value = 1

// 多选 + returnType='object'
this.fruits = [{ id: 1, name: '苹果' }, { id: 2, name: '香蕉' }]

// 多选 + returnType='key'
this.fruits = [1, 2]

清空

// 单选
this.value = null
// 或多选
this.fruits = []

// 或调用组件方法
this.$refs.selectRef.clickClear()

插槽

option — 自定义下拉项

<qiaoSelect :dataList="list" v-model="value">
  <template #option="{ item, index, selected }">
    <view class="custom-option" :class="{ active: selected }">
      <text>{{ item.name }}</text>
      <text class="desc">{{ item.desc }}</text>
    </view>
  </template>
</qiaoSelect>

多选模式下，右侧勾选标记（✓）由组件自动渲染，无需在插槽内重复实现。

selected — 自定义已选展示

仅在 searchable=false 时生效（此时使用 view 展示区域，可完全自定义样式）。

<qiaoSelect :dataList="list" v-model="value" :searchable="false">
  <template #selected="{ value, items, text }">
    <view class="custom-selected">
      <text>{{ text || '请选择' }}</text>
    </view>
  </template>
</qiaoSelect>

searchable=true 时（含多选默认可搜索），已选内容由输入框展示，不支持 selected 插槽；如需自定义多选展示，请设 searchable=false 后使用本插槽。

数据格式

dataList 每项为普通对象，例如：

{ id: 1, name: '北京', code: 'BJ' }

• 展示字段由 showKey 指定
• 搜索字段由 searchKey 指定（缺省时用 showKey）
• 组件内部会为每项生成 qiaoSelectKey 用于模糊匹配，请勿手动依赖该字段做业务逻辑

注意事项

1. 宽度：外层容器需有明确宽度（如 width: 100%），否则可能撑满异常
2. 多实例：同一页面多个组件请设置不同 keyId，失焦时自动关闭其他弹层
3. returnKey：returnType='key' 时必须配置 returnKey，否则选择时会提示
4. 多选绑定：v-model 始终绑定数组；清空为 [] 而非 null
5. 依赖：组件使用内置字符图标，不需要安装 uni-icons
6. Vue2 / Vue3：均使用 v-model；Vue2 绑定 value + input，Vue3 绑定 modelValue + update:modelValue

完整示例

推荐直接打开 example/demo.vue 对照学习。

该文件包含：基础单选、多选、不可搜索、弹窗置顶、returnType='key'、自定义 option 插槽、禁用等场景。

在项目中预览示例，可将该文件复制到 pages 并在 pages.json 中注册，例如：

{
  "path": "pages/qiao-select-demo",
  "style": {
    "navigationBarTitleText": "qiao-select 示例"
  }
}

复制后请将组件引入路径改为：

import qiaoSelect from '@/uni_modules/qiao-select/components/qiao-select/qiaoSelect.vue'