更新记录

1.0（2026-01-30）

暂无更新

平台兼容性

uni-app(4.61)

CommonFilterDialog 使用说明

通用筛选弹窗组件（右侧抽屉样式），支持搜索、数值区间、日期区间、单选、多选（含搜索）、树形多选等类型。适用于列表筛选/条件过滤场景。

环境与兼容性

• uni-app：Vue3 模式（使用 <script setup>）
• uni-app x：未适配
• 平台：H5 / App / 小程序（基础组件，跨平台可用）

组件特性

• 配置驱动渲染，多种字段类型
• 支持单项重置、整体重置与确定回传
• 多选支持关键词筛选
• 树形多选支持展开/收起与摘要展示

安装与引入

将 CommonFilterDialog.vue 放入项目组件目录后引入：

<script setup>
import CommonFilterDialog from '@/components/CommonFilterDialog.vue'
</script>

快速使用

<template>
  <CommonFilterDialog
    v-model="showFilter"
    :fields="fields"
    :value="filters"
    title="筛选"
    @update:value="v => (filters = v)"
    @confirm="onConfirm"
    @reset=""
  />
</template>

<script setup>
import { ref } from 'vue'
import CommonFilterDialog from '@/components/CommonFilterDialog.vue'

const showFilter = ref(false)
const filters = ref({})

const fields = [
  { key: 'keyword', label: '关键词', type: 'search', placeholder: '请输入' },
  { key: 'price', label: '价格区间', type: 'numberRange', minPlaceholder: '最小值', maxPlaceholder: '最大值' },
  { key: 'date', label: '日期范围', type: 'dateRange', startPlaceholder: '开始日期', endPlaceholder: '结束日期' },
  {
    key: 'status',
    label: '状态',
    type: 'singleSelect',
    options: [
      { label: '启用', value: 1 },
      { label: '停用', value: 0 }
    ]
  },
  {
    key: 'tags',
    label: '标签',
    type: 'multiSelect',
    searchPlaceholder: '输入关键字搜索',
    options: [
      { label: '重要', value: 'important' },
      { label: '紧急', value: 'urgent' }
    ]
  },
  {
    key: 'dept',
    label: '部门',
    type: 'treeMulti',
    options: [
      { label: '总部', value: 1, children: [{ label: '研发部', value: 11 }] }
    ]
  }
]

function onConfirm(v) {
  // 点击“确定”回调
}
function (v) {
  // 点击“重置”回调
}
</script>

字段配置说明（fields）

通用字段

• key：字段键名（必填）
• label：标题
• type：字段类型
  • search
  • numberRange
  • dateRange
  • singleSelect
  • multiSelect
  • treeMulti
• defaultValue：默认值（重置时使用）

search

• placeholder

numberRange

• minKey / maxKey：可自定义最小/最大值字段名
• minPlaceholder / maxPlaceholder

dateRange

• startKey / endKey
• startPlaceholder / endPlaceholder

singleSelect

• options：[{ label, value }]（为空时默认“是/否”）
• clearValue：点击已选项时的清空值

multiSelect

• options
• searchPlaceholder
• showEmptyTag：是否显示“空白项”摘要标签（默认显示）

treeMulti

• options：树形结构（label/value/children）

事件与双向绑定

• v-model 控制弹窗显示（对应 modelValue）
• value 为筛选值对象
• @update:value：值变化
• @confirm：点击确定
• @reset：点击重置

注意事项

• 多选字段会在重置时清空搜索关键字
• 树形多选使用 value/id/deptId 作为值优先级
• 建议在关闭弹窗前先处理 @confirm 回调