更新记录

0.0.3（2025-07-24） 下载此版本

feat: 1.新增single属性控制选择器只能存在一个。 2.暴露openSelector，closeSelector方法用于手动控制选择器。

0.0.2（2025-07-21） 下载此版本

fix: 1.调整组件zIndex属性默认值为99，防止微信小程序层级问题无法点击选择器。 2.更新说明文档及注意事项。

0.0.1（2025-07-16） 下载此版本

组件初始化

平台兼容性

uni-app

uni-app x

其他

xs-combox 组件使用说明

xs-combox 是一个基于 UniApp 的下拉选择输入框组件，支持本地/远程数据、搜索、清空、禁用、自定义显示等功能。

目录

• 安装
• 基础用法
• 属性说明
• 事件说明
• 插槽说明
• 样式自定义
• 示例

安装

将 uni_modules/xs-combox 目录复制到你的 uni_modules 目录下，无需额外安装依赖。

基础用法

<template>
  <xs-combox
    v-model="selected"
    :options="options"
    placeholder="请选择"
  />
</template>

<script setup>
import { ref } from 'vue'
const selected = ref('')
const options = [
  { label: '选项一', value: 1 },
  { label: '选项二', value: 2 }
]
</script>

属性说明

options 说明

• 支持三种类型：对象、字符串、数字。
• 对象时，需指定 fieldLabel 和 fieldValue 字段或函数。

filterOption 用法

• true：默认本地过滤（模糊匹配 label）。
• false：不进行本地过滤。
• Function：自定义过滤逻辑，参数为输入值，返回布尔。

事件说明

插槽说明

下拉项自定义示例

<xs-combox
  v-model="selected"
  :options="options"
>
  <template #default="{ item, index }">
    <view style="color: red;">{{ item.label }} - {{ item.value }}</view>
  </template>
</xs-combox>

样式自定义

• 通过 bordered 属性控制边框。
• 通过 placeholderClass 自定义占位符样式。
• 支持 scoped 样式覆盖类名：.xs-combox、.xs-combox-wrapper、.xs-combox-selector 等。
• 支持通过 prefixIcon 插槽自定义输入框前缀内容。
• 下拉面板支持关闭按钮，点击“关闭”可收起下拉列表。
• 输入框聚焦时自动清空搜索内容，失焦时可保留或还原。
• 支持 openSelector()、closeSelector()、toggleSelector() 方法手动控制下拉面板显示。

进阶用法示例

远程搜索

<xs-combox
  v-model="selected"
  :options="remoteOptions"
  :loading="loading"
  :filterOption="false"
  @search="onSearch"
/>

const remoteOptions = ref([])
const loading = ref(false)
function onSearch(val) {
  loading.value = true
  // 异步获取数据
  fetchOptions(val).then(list => {
    remoteOptions.value = list
    loading.value = false
  })
}

组件暴露方法

• toggleSelector()：手动打开/关闭下拉面板
• openSelector()：手动打开下拉面板
• closeSelector()：手动关闭下拉面板

const comboxRef = ref()
comboxRef.value.toggleSelector()
comboxRef.value.openSelector()
comboxRef.value.closeSelector()

其他说明

• 依赖 uni-icons、uni-load-more 组件。
• 支持移动端和小程序平台。
• 注意如果不弹出选择框，父元素不要设置overflow-hidden。

如需更多自定义需求，请参考源码或联系作者。