数据组件版本 0.1.0

FilterBar 筛选栏

把多个文本与选项筛选条件集中到可清除的查询工具栏。

使用概览

适合使用

列表或表格需要同时按多个常用字段缩小结果时。

不建议使用

只有一个简单搜索框，或筛选条件极少使用且更适合高级面板时。

真实示例

正在加载示例…

安装

本地候选警告Registry 地址仅指向当前本地文档站；npm 包也只用于本地候选验证，尚未公开发布。

pnpm dlx shadcn@4.16.0 add http://127.0.0.1:3000/r/filter-bar.json

基础用法

导入

import { FilterBar } from "@richardqiu/quartz/filter-bar";

JSX

<FilterBar aria-label="订单筛选" clearLabel="清除筛选" filters={[{ id: "query", label: "关键词", type: "text", placeholder: "订单号" }, { id: "status", label: "状态", type: "select", options: [{ label: "待发货", value: "pending" }] }]} />

状态与控制摘要

默认

键盘焦点可见

已禁用

label · textactive · boolean

API 参考

属性	类型	默认值	说明
`filters`	`readonly FilterDescriptor[]`	`必填`	声明每个筛选项的类型、标签、占位与可选值。
`onValuesChange`	`(values: FilterBarValues) => void`	`未设置`	在任意筛选条件变化后返回完整值集合。

组合结构

01FilterBar

键盘约定

Tab 访问每个原生筛选控件和清除操作；位于表单内时 Enter 原生提交。

可访问性契约

筛选集合是具名 search 区域。
每个描述项都要提供与控件关联的可见标签。