FilterBar 筛选栏

电商列表页常用的筛选与排序工具栏，支持吸顶、排序切换、下拉筛选面板及内联筛选模式。

基础用法

设置 sorts 和 filters 即可开启基础的排序和筛选功能。

当前排序: { "key": "default", "order": "desc" }

当前筛选: {}

基础用法

内联筛选模式

如果不希望使用下拉面板，可以将 filter-in-panel 设置为 false。

服务

内联模式

高级电商布局 (自定义抽屉 & 视图切换)

在大型电商或商品密集型应用中，最右侧的按钮常抛出自定义弹窗事件，而且通常附带 商品列表/网格切换按钮 与 价格输入框面板。组件底层均已预留支持。

当前排序: { "key": "default", "order": "desc" } | 当前筛选: { "minPrice": null, "maxPrice": null }

高级布局与定制

在 Nuxt 中使用

本组件完美支持 Nuxt 3/4 SSR 数据在服务端的预渲染。

当前排序: { "key": "default", "order": "desc" } | 当前筛选: { "minPrice": null, "maxPrice": null }

Nuxt 中使用

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@yh-ui/nuxt'],
  yhUI: {
    // 默认已自动按需引入，无需特殊配置
  }
})

API

Props

参数	说明	类型	默认值
sorts	排序配置列表	FilterSortItem[]	[]
filters	筛选器配置列表	FilterItem[]	[]
sort	当前排序状态	FilterSort	{ key: null, order: null }
filter-value	当前筛选值	FilterValue	{}
view-type	视图网格布局 (v-model:viewType)	'list' | 'grid'	'list'
show-all	是否展示「全部」tab	boolean	true
sticky	是否吸顶	boolean	false
filter-in-panel	是否在弹出面板中展示筛选器	boolean	true
show-global-filter	是否展示最右侧全局筛选漏斗按钮	boolean	true
show-view-toggle	是否展示列表/网格视图切换图标	boolean	false
sticky-offset	吸顶时的偏移距离 (px)	number	0
theme-overrides	自定义主题 CSS 变量覆盖	Record<string, string>	{}

Events (事件)

事件名	说明	回调参数
sort-change	排序状态变化时触发	(sort: FilterSort)
filter-change	筛选值变化时触发	(val: FilterValue)
view-change	视图模式切换时触发	(val: 'list' | 'grid')
reset	面板点击全局重置时触发	-
reset-panel	单个筛选面板内点击重置时触发	(filter: FilterItem, val: FilterValue)
confirm	点击确认筛选时触发	(val: FilterValue)
open-filter	点击最右侧漏斗图标触发	-

Slots (插槽)

插槽名	说明	参数
panel-content	完全自定义筛选面板内容	{ filter, value, toggle }
view-icon	自定义列表/网格切换图标	{ viewType }
filter-icon	自定义最右侧筛选漏斗图标	-
extra	自定义右侧扩展区域内容	-

Expose

当前组件未暴露公开实例方法或属性。

主题变量 (CSS Variables)

变量名	默认值	说明
--yh-filter-bar-bg	var(--yh-bg-color)	根节点背景色
--yh-filter-bar-border	var(--yh-border-color-lighter)	根节点边框颜色
--yh-filter-bar-height	44px	工具栏高度
--yh-filter-bar-tab-color	var(--yh-text-color-regular)	未激活标签文字颜色
--yh-filter-bar-tab-active-color	var(--yh-color-primary)	激活标签文字颜色
--yh-filter-bar-tab-active-bg	var(--yh-color-primary-light-9)	激活标签背景
--yh-filter-bar-tab-radius	var(--yh-radius-base)	标签圆角
--yh-filter-bar-badge-bg	var(--yh-color-danger)	角标背景色
--yh-filter-bar-panel-bg	var(--yh-bg-color)	面板背景色
--yh-filter-bar-panel-shadow	0 4px 20px var(--yh-shadow-color)	面板阴影
--yh-filter-bar-panel-opt-bg	var(--yh-fill-color-light)	面板选项默认背景
--yh-filter-bar-panel-opt-active-bg	var(--yh-color-primary-light-9)	面板选项激活背景
--yh-filter-bar-panel-opt-active-color	var(--yh-color-primary)	面板选项激活文字颜色
--yh-filter-bar-panel-opt-active-border	var(--yh-color-primary)	面板选项激活边框颜色
--yh-filter-bar-z-index	100	根节点层级

类型导出

名称	说明
YhFilterBarProps	组件 Props 类型
YhFilterBarEmits	组件事件类型
YhFilterBarSlots	组件插槽类型
YhFilterSortOrder	排序方向联合类型
YhFilterSortItem	排序项类型
YhFilterType	筛选类型联合类型
YhFilterOption	筛选选项类型
YhFilterItem	筛选项类型
YhFilterValue	筛选值类型
YhFilterSort	排序状态类型
YhFilterBarInstance	组件实例类型