更新记录

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 等。

进阶用法示例

远程搜索

<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()：手动打开/关闭下拉面板

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

其他说明

• 依赖 uni-icons、uni-load-more 组件。
• 支持移动端和小程序平台。

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