更新记录

1.0.1（2026-05-07）下载此版本

readme更新

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

发布新版本

平台兼容性

uni-app(4.0)

Vue2	Vue2插件版本	Vue3	Vue3插件版本	Chrome	Chrome插件版本	Safari	Safari插件版本	app-vue	app-vue插件版本	app-nvue	Android	Android插件版本	iOS	iOS插件版本	鸿蒙
√	1.0.0	√	1.0.0	√	1.0.0	√	1.0.0	√	1.0.0	×	5.0	1.0.0	12	1.0.0	-

微信小程序	微信小程序插件版本	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
√	1.0.0	-	-	-	-	-	-	-	-	-	-	-

ldw-filter-selection

一个多功能联动下拉筛选组件，支持：

顶部筛选栏吸顶 / 展开固定，展开时防止页面滚动穿透
区域三级联动（cascader），支持混合二三级、按 Tab 独立设置多选
左侧菜单 + 右侧多分组筛选（sections），左右双向滚动联动
双滑块区间筛选（range）
多选标签、单选排序（list）
当前面板重置 / 确定

组件位置

uni_modules/ldw-filter-selection/components/ldw-filter-selection/ldw-filter-selection.vue

基础用法

<template>
  <ldw-filter-selection
    :filters="filters"
    @update:filters="filters = $event"
    @change="handleChange"
  ></ldw-filter-selection>
</template>

<script>
export default {
  data() {
    return {
      filters: [
        {
          key: "sort",
          label: "排序",
          type: "list",
          instant: true,
          options: [
            {
              label: "默认排序",
              value: "default",
              isDefault: true,
              selected: true,
            },
            { label: "最新发布", value: "latest" },
            { label: "总价从低到高", value: "price-asc" },
          ],
        },
      ],
    };
  },
  methods: {
    handleChange(payload) {
      console.log(payload.values);
    },
  },
};
</script>

Props

参数	类型	默认值	说明
`filters`	`Array`	`[]`	筛选项配置
`activeColor`	`String`	`''`	主题色，不传时默认跟随 `uni.scss` 中的 `$uni-color-primary`
`panelMaxHeight`	`String`	`60vh`	面板最大高度
`zIndex`	`Number`	`90`	面板层级
`sticky`	`Boolean`	`true`	是否吸顶
`maskClosable`	`Boolean`	`true`	点击遮罩是否关闭

事件

事件	说明
`update:filters`	组件内部确认后回传最新配置，建议父组件接住作为状态源
`change`	当前筛选确认后触发，返回全部筛选值
`confirm`	当前筛选确认后触发
`reset`	当前面板点击重置时触发
`open`	打开某个筛选面板时触发
`close`	关闭面板时触发

filters 数据结构

组件目前内置 4 种面板类型：

1. `cascader`

适合"区域 / 地铁 / 附近"这类多 Tab 联动结构。

支持混合二三级：同一 Tab 的 options 中，若某个 option 的 children 为空数组，则点击该 option 直接选中（显示勾选框）；若 children 有值，则正常展开三级列。

支持按 Tab 独立设置多选：在每个 columnTab 对象上单独配置 multiple；若 Tab 未设置，则继承顶层 filter 的 multiple 属性（默认为 false 单选）。

{
    key: 'region',
    label: '区域',
    type: 'cascader',
    // multiple: true,  // 可在此全局设置多选（可选）
    columnTabs: [
        {
            label: '区域',
            multiple: true,   // 该 Tab 独立开启多选
            options: [
                { label: '不限', value: 'all', isDefault: true },
                {
                    label: '鼓楼',
                    value: 'gulou',
                    childrenTitle: '热门商圈',
                    children: [
                        // children 有值 → 展示三级列
                        { label: '龙江', value: 'longjiang', desc: '21.5%用户选择' }
                    ]
                },
                {
                    label: '江北新区',
                    value: 'jiangbei',
                    children: []  // children 为空 → 直接选中该项（二级模式）
                }
            ]
        },
        {
            label: '地铁',
            multiple: false,  // 该 Tab 单选（默认）
            options: [
                { label: '不限', value: 'all-subway', isDefault: true },
                {
                    label: '地铁1号线',
                    value: 'line-1',
                    children: [
                        { label: '近1km', value: 'near-1km' }
                    ]
                }
            ]
        }
    ]
}

多选时的返回值：extractFilterValue 在 multiple: true 的 Tab 下返回数组，单选时返回对象或 null。

2. `sections`

适合"房型 / 更多"这类左侧菜单 + 右侧多个区块。

左右双向滚动联动（Scroll Spy）：滚动右侧内容区时，左侧菜单会自动高亮并滚动到对应的分组标题；点击左侧菜单时，右侧内容区平滑跳转到对应锚点。

⚠️ 左侧菜单中每一个 section 对应右侧的一个独立区块。如果需要某类选项独占左侧一个菜单项，请将其单独提取为一个 section，而不是放在同一 section 的多个 blocks 内。

{
    key: 'roomType',
    label: '房型',
    type: 'sections',
    sections: [
        {
            key: 'rooms',
            label: '房屋居室',       // 左侧菜单显示此 label
            blocks: [
                {
                    key: 'living-room-count',
                    title: '房屋居室',
                    type: 'chips',
                    options: [
                        { label: '一室', value: '1-room' },
                        { label: '二室', value: '2-room' }
                    ]
                }
            ]
        },
        {
            key: 'bathroom',
            label: '卫生间',         // 独立 section，左侧有独立菜单项
            blocks: [
                {
                    key: 'bathroom-count',
                    title: '卫生间',
                    type: 'chips',
                    options: [
                        { label: '1卫', value: '1-bathroom' },
                        { label: '2卫', value: '2-bathroom' }
                    ]
                }
            ]
        }
    ]
}

3. `range`

适合"价格"这类顶部模式切换 + 区间筛选。

{
    key: 'price',
    label: '价格',
    type: 'range',
    modes: [
        {
            key: 'totalPrice',
            label: '总价(万/套)',
            block: {
                title: '总价(万/套)',
                min: 0,
                max: 700,
                step: 10,
                unit: '万',
                minEdgeLabel: '0元',
                maxEdgeLabel: '700万以上',
                options: [
                    { label: '80-100万', value: [80, 100] },
                    { label: '100-150万', value: [100, 150] }
                ],
                showInputs: true,
                inputsTitle: '自定义价格',
                minPlaceholder: '最低总价',
                maxPlaceholder: '最高总价'
            }
        }
    ]
}

4. `list`

适合"排序"这类立即生效的单选列表。

{
    key: 'sort',
    label: '排序',
    type: 'list',
    instant: true,
    options: [
        { label: '默认排序', value: 'default', isDefault: true, selected: true },
        { label: '最新发布', value: 'latest' }
    ]
}

block 类型

sections 和 range 内部支持两种 block：

`chips`

{
    key: 'orientation',
    title: '朝向',
    type: 'chips',
    multiple: true,   // 是否多选，默认 false
    options: [
        { label: '东', value: 'east' },
        { label: '南', value: 'south' }
    ]
}

`range`

{
    key: 'building-area',
    title: '建筑面积',
    type: 'range',
    min: 0,
    max: 200,
    step: 10,
    unit: 'm²',
    minEdgeLabel: '0m²',
    maxEdgeLabel: '200m²以上',
    options: [
        { label: '60-90m²', value: [60, 90] },
        { label: '90-110m²', value: [90, 110] }
    ]
}

minEdgeLabel 和 maxEdgeLabel 会作为滑块组件下方的左右说明文案显示；不传时会按最小值 / 最大值自动生成。

返回值格式

change / confirm 事件会返回：

{
    activeKey: 'price',
    filters: [...],
    values: {
        // cascader 单选
        region: { label: '龙江', value: 'longjiang', desc: '...', isDefault: false },
        // cascader 多选（multiple: true 的 tab 下）
        region: [
            { label: '龙江', value: 'longjiang', isDefault: false },
            { label: '建宁路', value: 'jianning-road', isDefault: false }
        ],
        // range
        price: {
            totalPrice: {
                value: [80, 150],
                presets: [{ label: '80-100万', value: [80, 100] }],
                inputMin: '',
                inputMax: '',
                summary: '80-150万'
            }
        }
    }
}

示例

项目首页 pages/index/index.vue 已放了一套贝壳风格演示页，可直接运行查看交互效果。