FilterPanel 筛选面板

用于管理列表页筛选条件的面板组件，支持多选筛选项、单选筛选项、快捷日期范围、展开收起、重置等功能。

基础用法

展示筛选条件的基本配置，支持多选/单选筛选项、远程数据加载、日期范围选择

<template>
  <ClientOnly>
  <div class="filter-panel-demo">
    <HxFilterPanel
      v-model="filterState"
      title="筛选条件"
      :filters="filters"
      @filter-change="onFilterChange"
      @reset="onReset"
    />
    <div class="filter-panel-demo__output">
      <p class="filter-panel-demo__output-title">当前 v-model</p>
      <pre class="filter-panel-demo__pre">{{ JSON.stringify(filterState, null, 2) }}</pre>
    </div>
  </div>
  </ClientOnly>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { HxFilterPanel } from '@whhx/ui'
import type { FilterConfig, FilterState } from '@whhx/ui'

const filters: FilterConfig[] = [
  {
    type: 'filter-item',
    prop: 'category',
    label: '分类',
    multiple: true,
    options: [
      { label: '全部', value: 'all' },
      { label: '电子', value: 'electronics' },
      { label: '家居', value: 'home' },
      { label: '图书', value: 'book', disabled: true },
    ],
  },
  {
    type: 'filter-item',
    prop: 'status',
    label: '状态',
    multiple: false,
    options: [
      { label: '待处理', value: 'pending' },
      { label: '进行中', value: 'doing' },
      { label: '已完成', value: 'done' },
    ],
  },
  {
    type: 'filter-item',
    prop: 'region',
    label: '城市（远程）',
    multiple: true,
    remote: {
      url: '/api/options/select',
      labelKey: 'label',
      valueKey: 'value',
    },
  },
  {
    type: 'date-range',
    prop: 'dateRange',
    label: '时间范围',
  },
]

const filterState = ref<FilterState>({
  category: ["electronics",
    "home"],
  status: 'doing',
  dateRange: [],
})

const onFilterChange = (prop: string, value: unknown) => {
  console.log('[filter-change]', prop, value)
}

const onReset = () => {
  console.log('[reset]')
}
</script>

<style scoped>
.filter-panel-demo {
	width: 100%;
}

.filter-panel-demo__output {
	margin-top: 16px;
	padding: 12px 16px;
	background: var(--el-fill-color-lightest);
	border-radius: 8px;
}

.filter-panel-demo__output-title {
	margin: 0 0 8px;
	font-size: 13px;
	color: var(--el-text-color-regular);
}

.filter-panel-demo__pre {
	margin: 0;
	font-size: 12px;
	line-height: 1.5;
	color: var(--el-text-color-primary);
	white-space: pre-wrap;
	word-break: break-all;
}
</style>

折叠与高度

通过 `collapse` 属性控制折叠状态，通过 `height` 属性限制面板内容区最大高度，超出内容自动显示滚动条

筛选条件

商品分类:电子产品, 家居用品颜色:全部价格区间:不限评分:全部

商品分类

全部

电子产品

家居用品

图书音像

服装鞋帽

食品饮料

运动户外

美妆护肤

母婴用品

汽车用品

品牌

选项1

选项2

选项3

选项4

选项5

选项6

选项7

选项8

选项9

选项10

选项11

选项12

选项13

选项14

选项15

选项16

选项17

选项18

选项19

选项20

颜色

全部

红色

蓝色

绿色

黑色

白色

灰色

黄色

紫色

粉色

橙色

尺码

XS

S

M

L

XL

XXL

价格区间

不限

0-100元

100-500元

500-1000元

1000-2000元

2000元以上

特性

选项1

选项2

选项3

选项4

选项5

选项6

选项7

选项8

选项9

选项10

选项11

选项12

选项13

选项14

选项15

评分

全部

5星

4星及以上

3星及以上

上市时间

-

当前 v-model

{
  "category": [
    "electronics",
    "home"
  ],
  "brand": [],
  "color": "all",
  "size": [],
  "priceRange": "all",
  "feature": [],
  "rating": "all",
  "dateRange": []
}

<template>
  <div class="filter-panel-demo">
    <HxFilterPanel
      v-model="filterState"
      title="筛选条件"
      :filters="filters"
      height="280px"
      @filter-change="onFilterChange"
      @reset="onReset"
    />
    <div class="filter-panel-demo__output">
      <p class="filter-panel-demo__output-title">当前 v-model</p>
      <pre class="filter-panel-demo__pre">{{ JSON.stringify(filterState, null, 2) }}</pre>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { HxFilterPanel } from '@whhx/ui'
import type { FilterConfig, FilterState } from '@whhx/ui'

// 生成大量选项用于测试折叠动画和高度限制
const generateOptions = (count: number) => {
  return Array.from({ length: count }, (_, i) => ({
    label: `选项${i + 1}`,
    value: `option-${i + 1}`,
  }))
}

const filters: FilterConfig[] = [
  {
    type: 'filter-item',
    prop: 'category',
    label: '商品分类',
    multiple: true,
    options: [
      { label: '全部', value: 'all' },
      { label: '电子产品', value: 'electronics' },
      { label: '家居用品', value: 'home' },
      { label: '图书音像', value: 'books' },
      { label: '服装鞋帽', value: 'clothing' },
      { label: '食品饮料', value: 'food' },
      { label: '运动户外', value: 'sports' },
      { label: '美妆护肤', value: 'beauty' },
      { label: '母婴用品', value: 'baby' },
      { label: '汽车用品', value: 'auto' },
    ],
  },
  {
    type: 'filter-item',
    prop: 'brand',
    label: '品牌',
    multiple: true,
    options: generateOptions(20),
  },
  {
    type: 'filter-item',
    prop: 'color',
    label: '颜色',
    multiple: false,
    options: [
      { label: '全部', value: 'all' },
      { label: '红色', value: 'red' },
      { label: '蓝色', value: 'blue' },
      { label: '绿色', value: 'green' },
      { label: '黑色', value: 'black' },
      { label: '白色', value: 'white' },
      { label: '灰色', value: 'gray' },
      { label: '黄色', value: 'yellow' },
      { label: '紫色', value: 'purple' },
      { label: '粉色', value: 'pink' },
      { label: '橙色', value: 'orange' },
    ],
  },
  {
    type: 'filter-item',
    prop: 'size',
    label: '尺码',
    multiple: true,
    options: [
      { label: 'XS', value: 'xs' },
      { label: 'S', value: 's' },
      { label: 'M', value: 'm' },
      { label: 'L', value: 'l' },
      { label: 'XL', value: 'xl' },
      { label: 'XXL', value: 'xxl' },
    ],
  },
  {
    type: 'filter-item',
    prop: 'priceRange',
    label: '价格区间',
    multiple: false,
    options: [
      { label: '不限', value: 'all' },
      { label: '0-100元', value: '0-100' },
      { label: '100-500元', value: '100-500' },
      { label: '500-1000元', value: '500-1000' },
      { label: '1000-2000元', value: '1000-2000' },
      { label: '2000元以上', value: '2000+' },
    ],
  },
  {
    type: 'filter-item',
    prop: 'feature',
    label: '特性',
    multiple: true,
    options: generateOptions(15),
  },
  {
    type: 'filter-item',
    prop: 'rating',
    label: '评分',
    multiple: false,
    options: [
      { label: '全部', value: 'all' },
      { label: '5星', value: '5' },
      { label: '4星及以上', value: '4' },
      { label: '3星及以上', value: '3' },
    ],
  },
  {
    type: 'date-range',
    prop: 'dateRange',
    label: '上市时间',
  },
]

const filterState = ref<FilterState>({
  category: ['electronics', 'home'],
  brand: [],
  color: 'all',
  size: [],
  priceRange: 'all',
  feature: [],
  rating: 'all',
  dateRange: [],
})

const onFilterChange = (prop: string, value: unknown) => {
  console.log('[filter-change]', prop, value)
}

const onReset = () => {
  console.log('[reset]')
}
</script>

<style scoped>
.filter-panel-demo {
	width: 100%;
}

.filter-panel-demo__output {
	margin-top: 16px;
	padding: 12px 16px;
	background: var(--el-fill-color-lightest);
	border-radius: 8px;
}

.filter-panel-demo__output-title {
	margin: 0 0 8px;
	font-size: 13px;
	color: var(--el-text-color-regular);
}

.filter-panel-demo__pre {
	margin: 0;
	font-size: 12px;
	line-height: 1.5;
	color: var(--el-text-color-primary);
	white-space: pre-wrap;
	word-break: break-all;
}
</style>

远程联动

省 → 市 → 区三级级联，通过 `FilterRemoteConfig.dependsOn` 实现联动

<template>
  <ClientOnly>
  <div class="filter-panel-demo">
    <HxFilterPanel
      v-model="filterState"
      title="筛选条件"
      :filters="filters"
      @filter-change="onFilterChange"
      @reset="onReset"
    />
    <div class="filter-panel-demo__output">
      <p class="filter-panel-demo__output-title">当前 v-model</p>
      <pre class="filter-panel-demo__pre">{{ JSON.stringify(filterState, null, 2) }}</pre>
    </div>
  </div>
  </ClientOnly>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { HxFilterPanel } from '@whhx/ui'
import type { FilterConfig, FilterState } from '@whhx/ui'

/**
 * =============================================================
 * filter-panel 远程联动示例 — 省 → 市 → 区三级级联
 * =============================================================
 *
 * 【接口约定 /api/options/linked】
 *   POST body { parent: <value> }   → 接口支持
 *   GET  ?parent=<value>            → 接口也支持
 *   返回 { code: 0, data: [{ label, value }] }
 *
 *   parent 传值规则：
 *     parent 为空 / 'all'   → 该层级全部选项
 *     parent = <省 value>   → 返回该省下的市列表
 *     parent = <市 value>   → 返回该市下的区列表
 *     parent = 'province'   → 返回省列表
 *
 * 【联动配置】
 *   remote.dependsOn         : 依赖的父级 prop 名称
 *   remote.dependsOnParamKey : 父值作为哪个参数名传递，默认 "value"
 *   remote.dependsOnIn       : 显式指定 'query' | 'body'，默认跟随 method
 *   remote.url / method / labelKey / valueKey : 与普通远程请求一致
 * =============================================================
 */
const BASE_URL = '/api/options/linked'

const filters: FilterConfig[] = [
  // ── 第1级：省份（远程，请求时 parent='province'）─────────────────
  {
    type: 'filter-item',
    prop: 'province',
    label: '省份',
    multiple: false,
    remote: {
      method: 'post',
      url: BASE_URL,
      body: { parent: 'province' },
      labelKey: 'label',
      valueKey: 'value',
    },
  },

  // ── 第2级：城市（联动 — 依赖省份，父值注入 body）────────────────
  // 未选省份时返回所有市，选中后返回该省下的市
  {
    type: 'filter-item',
    prop: 'city',
    label: '城市',
    multiple: false,
    remote: {
      method: 'post',
      url: BASE_URL,
      dependsOn: 'province',
      dependsOnParamKey: 'parent',
      dependsOnIn: 'body',
      labelKey: 'label',
      valueKey: 'value',
    },
  },

  // ── 第3级：区县（联动 — 依赖城市，父值注入 query）────────────
  // 未选城市时返回所有区，选中后返回该市下的区
  {
    type: 'filter-item',
    prop: 'district',
    label: '区县',
    multiple: true,
    remote: {
      method: 'post',
      url: BASE_URL,
      dependsOn: 'city',
      dependsOnParamKey: 'parent',
      dependsOnIn: 'body',
      labelKey: 'label',
      valueKey: 'value',
    },
  },

  {
    type: 'date-range',
    prop: 'dateRange',
    label: '时间范围',
    options: [],
  },
]

const filterState = ref<FilterState>({
  province: '',
  city: '',
  district: '',
  dateRange: '',
})

const onFilterChange = (prop: string, value: unknown) => {
  console.log('[filter-change]', prop, value)
}

const onReset = () => {
  console.log('[reset]')
}
</script>

<style scoped>
.filter-panel-demo {
	width: 100%;
}

.filter-panel-demo__output {
	margin-top: 16px;
	padding: 12px 16px;
	background: var(--el-fill-color-lightest);
	border-radius: 8px;
}

.filter-panel-demo__output-title {
	margin: 0 0 8px;
	font-size: 13px;
	color: var(--el-text-color-regular);
}

.filter-panel-demo__pre {
	margin: 0;
	font-size: 12px;
	line-height: 1.5;
	color: var(--el-text-color-primary);
	white-space: pre-wrap;
	word-break: break-all;
}
</style>

API

HxFilterPanel Props

参数	说明	类型	默认值
modelValue / v-model	筛选状态对象，key 为 prop，value 为选中值	FilterState	{}
title	面板标题	string	'筛选条件'
filters	筛选条件配置数组	FilterConfig[]	[]
collapse	是否默认收起筛选条件区域	boolean	false
height	折叠面板内容区最大高度（控制展开时的最大高度）	string	'400px'

HxFilterPanel Emits

事件名	说明	参数
update:modelValue	筛选状态变更	(value: FilterState)
change	筛选状态变更（与 update:modelValue 同时触发）	(value: FilterState)
filter-change	单个筛选项值变化	(key: string, value: FilterValueType)
reset	重置所有筛选条件	()

FilterConfig

参数	说明	类型	默认值
prop	字段标识，对应 FilterState 的 key	string	—
label	显示名称	string	—
type	筛选类型	'filter-item' | 'date-range'	—
options	静态选项列表，使用 remote 时可省略	FilterOption[]	—
labelKey	选项中 label 字段名（透传至子组件）	string	'label'
valueKey	选项中 value 字段名（透传至子组件）	string	'value'
multiple	是否支持多选（仅 filter-item）	boolean	true
remote	远程数据配置，优先级高于 options	FilterRemoteConfig	—
dateShortcuts	快捷区间按钮列表（仅 date-range）	FilterDateRangeShortcut[]	近 7 / 30 / 90 天
dateFormat	日期输出与展示格式（仅 date-range）	string	'YYYY-MM-DD'

FilterRemoteConfig

参数	说明	类型	默认值
url	远程请求 URL	string	—
method	请求方法	'get' | 'post'	'get'
params	URL query 参数（GET 自动拼接在 ? 后）	Record<string, unknown>	—
body	请求体参数（POST 序列化为 JSON 放入 body）	Record<string, unknown>	—
bodyType	请求体格式	'json' | 'form-data'	'json'
labelKey	响应数据中 label 字段名	string	'label'
valueKey	响应数据中 value 字段名	string	'value'
childrenKey	响应数据中 children 字段名（用于级联和分组）	string	'children'
dependsOn	联动：依赖的父级 prop 名称，父值变化时自动重新请求	string	—
dependsOnParamKey	联动：父值作为哪个参数名传递	string	'value'
dependsOnIn	联动：父值注入在 query 还是 body 中，默认跟随 method	'query' | 'body'	—

FilterDateRangeShortcut

参数	说明	类型
label	按钮文案	string
days	结束为今天、开始为今天往前推的天数	number

FilterOption

参数	说明	类型	默认值
[key: string]	可配置任意字段扩展	any	—
disabled	是否禁用该选项	boolean	false

功能说明

• 筛选项类型：type: 'filter-item' 由内部 FilterItem 渲染，支持静态 options 与远程数据加载，支持单选/多选；type: 'date-range' 为快捷区间 +「自定义」+ el-date-picker 范围选择。
• 日期范围 v-model：值为 ''（未选择）或 [start, end] 字符串元组，格式由 dateFormat 控制。
• 远程联动：通过 FilterRemoteConfig.dependsOn 配置，父级 prop 值变化时自动清空自身选中值并重新请求远程数据。
• 选中态展示：顶部 Chip 区域展示当前所有有效筛选条件，支持逐个清除。
• 展开收起：通过 collapse 属性控制筛选条件区域的折叠状态。
• 重置：点击「重置」按钮清空所有筛选条件。

类型定义

import type {
  FilterPanelProps,
  FilterPanelEmits,
  FilterConfig,
  FilterOption,
  FilterDateRangeShortcut,
  FilterState,
  FilterValueType,
  FilterRemoteConfig,
  FilterItemProps,
  FilterItemEmits,
  FilterItemInstance,
  FilterDateRangeProps,
} from '@whhx/ui'