更新记录

1.0.0（2026-07-29） 下载此版本

平台兼容性

uni-app(3.8.12)

uni-query-filter

基于 uni-ui 的可配置多条件查询筛选组件，通过 JSON 配置即可生成完整的筛选面板，支持从顶部滑入、高度由内容撑开。

✨ 特性

• 🔧 完全配置驱动 — 字段名、类型、选项全部通过 fieldConfig 配置
• 📦 8 种字段类型 — input / select / radio / checkbox / date / datetime / daterange / datetimerange / switch / cascader
• 🎨 基于 uni-ui — 使用 uni-easyinput / uni-data-select / uni-data-checkbox / uni-datetime-picker / uni-icons
• 📐 顶部弹出 — 从屏幕顶部滑入，动画流畅，高度由内容撑开
• 🛡️ 安全区适配 — 适配刘海屏和 Home Indicator
• 🔄 双向绑定 — 支持 v-model 和 .sync 修饰符
• 📱 多端兼容 — App / H5 / 微信小程序 / 支付宝小程序等

📦 安装

通过 HBuilderX 插件市场搜索 uni-query-filter 导入即可。

依赖的 uni-ui 组件（会自动安装）：

• uni-easyinput
• uni-data-select
• uni-data-checkbox
• uni-datetime-picker
• uni-icons

🚀 快速上手

1. 在页面中引入

<template>
  <view>
    <button @click="showFilter = true">打开筛选</button>

    <uni-query-filter
      :visible.sync="showFilter"
      title="用户列表筛选"
      :field-config="fieldConfig"
      v-model="filterForm"
      @confirm="onConfirm"
      @reset=""
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      showFilter: false,
      filterForm: {
        department: '',
        username: '',
        status: 'normal',
        createTime: { start: '', end: '' }
      },
      fieldConfig: [
        {
          field: 'department',
          label: '部门',
          type: 'select',
          options: [
            { label: '全部', value: '' },
            { label: '匠人科技', value: 'jr' },
            { label: '研发中心', value: 'rd' }
          ]
        },
        {
          field: 'username',
          label: '用户名',
          type: 'input',
          placeholder: '请输入用户名',
          maxlength: 20
        },
        {
          field: 'status',
          label: '状态',
          type: 'radio',
          radioMode: 'button',
          options: [
            { label: '正常', value: 'normal' },
            { label: '停用', value: 'disabled' }
          ],
          defaultValue: 'normal'
        },
        {
          field: 'createTime',
          label: '创建时间',
          type: 'daterange',
          start: '2020-01-01',
          end: '2030-12-31',
          startPlaceholder: '开始日期',
          endPlaceholder: '结束日期'
        }
      ]
    }
  },
  methods: {
    onConfirm(form) {
      console.log('确认筛选：', form)
      // form = {
      //   department: 'jr',
      //   username: '演示',
      //   status: 'normal',
      //   createTime: { start: '2024-01-01', end: '2024-01-25' }
      // }
    },
    (form) {
      console.log('已重置：', form)
    }
  }
}
</script>

📋 Props

📡 Events

⚙️ fieldConfig 配置说明

通用字段

各类型特有配置

📊 数据格式

// v-model 绑定的数据格式
{
  department: 'jr',                          // select / cascader → 字符串
  username: '演示',                          // input → 字符串
  status: 'normal',                         // radio → 字符串
  role: ['admin', 'editor'],               // checkbox → 数组
  createTime: { start: '2024-01-01', end: '2024-01-25' }, // range → 对象
  loginTime: '2024-01-24 16:36:02',        // datetime → 字符串
  enableNotify: true                        // switch → 布尔值
}

🎨 自定义按钮样式

<uni-query-filter
  :visible.sync="showFilter"
  :field-config="fieldConfig"
  v-model="filterForm"
  :confirm-btn-style="{ background: '#ff6a00', borderRadius: '40rpx' }"
  :reset-btn-style="{ background: '#e8e8e8', color: '#333' }"
  confirm-text="搜索"
  reset-text="清空"
/>

📁 目录结构

uni_modules/uni-query-filter/
├── components/
│   └── uni-query-filter/
│       └── uni-query-filter.vue   # 组件主体
├── pages/
│   └── demo/
│       └── demo.vue              # 示例页面
├── package.json                   # uni_modules 元信息
├── CHANGELOG.md                  # 更新日志
└── README.md                     # 本文档

💡 常见问题

Q: 为什么不用原生 picker？

A: 原生 picker 的 mode 不支持 daterange / datetimerange，会导致 Vue 校验报错。本组件使用 uni-datetime-picker，原生支持范围选择，无报错。

Q: 面板高度怎么控制？

A: 面板高度完全由内容撑开，不设固定高度。当条件很多时，max-height: 80vh 兜底，内部自动滚动。

Q: 支持哪些端？

A: App（Vue）、H5、微信小程序、支付宝小程序、百度小程序、头条小程序、QQ小程序均支持。

📄 License

MIT