---
nav:
  title: 组件
  order: 1
group:
  title: Data Entry
  order: 3
title: PisellQuickFilter
order: 10
category: pro
---

# PisellQuickFilter - 快速筛选组件

## 简介

PisellQuickFilter 是一个基于 Ant Design Form 的快速筛选表单组件，提供了简洁的筛选项配置和表单管理功能。

## 特性

- 🎯 **快速配置**: 通过简单的配置即可实现筛选功能
- 📝 **表单集成**: 基于 Ant Design Form，支持完整的表单能力
- 🎨 **灵活定制**: 支持自定义表单前缀、筛选项列表等
- 🔄 **受控模式**: 支持完全受控的表单管理
- 📱 **响应式**: 自适应不同屏幕尺寸
- 🎭 **TypeScript**: 完整的 TypeScript 类型定义

## 基础用法

```tsx
import { PisellQuickFilter } from '@pisell/materials';

const Demo = () => {
  const filterList = [
    {
      type: 'input',
      key: 'keyword',
      label: '关键词',
      props: {
        placeholder: '请输入关键词',
      },
      other: {},
    },
    {
      type: 'single',
      key: 'status',
      label: '状态',
      props: {
        options: [
          { label: '全部', value: '' },
          { label: '启用', value: '1' },
          { label: '禁用', value: '0' },
        ],
      },
      other: {},
    },
  ];

  return (
    <PisellQuickFilter
      filterList={filterList}
      formFiltersPrefix="filters"
    />
  );
};

export default Demo;
```

## API

### PisellQuickFilter Props

| 参数                 | 说明                   | 类型                  | 默认值  | 版本 |
| -------------------- | ---------------------- | --------------------- | ------- | ---- |
| filterList           | 筛选项列表             | `FilterItemProps[]`   | `[]`    | -    |
| formFiltersPrefix    | 表单字段前缀           | `string`              | -       | -    |
| quickFilterMaxLength | 快速筛选最大显示数量   | `number`              | -       | -    |
| hiddenQuickFilter    | 是否隐藏快速筛选       | `boolean`             | `false` | -    |
| hiddenOtherFilter    | 是否隐藏其他筛选       | `boolean`             | `false` | -    |
| children             | 自定义子元素           | `React.ReactNode`     | -       | -    |

**注意**: 该组件继承了 Ant Design `FormInstance` 的所有属性和方法。

### FilterItemProps

```typescript
interface FilterItemProps {
  type: 'single' | 'input' | 'datePicker' | 'rangePicker' | 'search'; // 筛选项类型
  key: string; // 字段唯一标识
  name?: string | string[]; // 字段名称
  label?: string; // 标签文本
  props: object; // 组件属性
  sort?: boolean; // 是否支持排序
  localFilter?: boolean; // 是否本地筛选
  other: Record<string, any>; // 其他配置
  isCustom?: boolean; // 是否自定义
  columnKey?: string; // 列 key
  isHidden?: boolean; // 是否隐藏
}
```

## 进阶用法

### 多种筛选类型

```tsx
import { PisellQuickFilter } from '@pisell/materials';

const Demo = () => {
  const filterList = [
    {
      type: 'input',
      key: 'keyword',
      label: '关键词',
      props: {
        placeholder: '请输入关键词',
      },
      other: {},
    },
    {
      type: 'single',
      key: 'category',
      label: '分类',
      props: {
        options: [
          { label: '全部', value: '' },
          { label: '类型1', value: '1' },
          { label: '类型2', value: '2' },
        ],
      },
      other: {},
    },
    {
      type: 'datePicker',
      key: 'createTime',
      label: '创建时间',
      props: {
        placeholder: '请选择日期',
      },
      other: {},
    },
    {
      type: 'rangePicker',
      key: 'dateRange',
      label: '日期区间',
      props: {
        placeholder: ['开始日期', '结束日期'],
      },
      other: {},
    },
  ];

  return (
    <PisellQuickFilter
      filterList={filterList}
      formFiltersPrefix="filters"
      quickFilterMaxLength={3}
    />
  );
};

export default Demo;
```

### 限制快速筛选数量

```tsx
import { PisellQuickFilter } from '@pisell/materials';

const Demo = () => {
  const filterList = [
    // ... 多个筛选项
  ];

  return (
    <PisellQuickFilter
      filterList={filterList}
      formFiltersPrefix="filters"
      quickFilterMaxLength={5} // 限制最多显示 5 个快速筛选项
    />
  );
};

export default Demo;
```

### 隐藏部分筛选

```tsx
import { PisellQuickFilter } from '@pisell/materials';

const Demo = () => {
  const filterList = [
    // ... 筛选项配置
  ];

  return (
    <PisellQuickFilter
      filterList={filterList}
      formFiltersPrefix="filters"
      hiddenQuickFilter={false} // 显示快速筛选
      hiddenOtherFilter={true} // 隐藏其他筛选
    />
  );
};

export default Demo;
```

### 自定义表单前缀

```tsx
import { PisellQuickFilter } from '@pisell/materials';

const Demo = () => {
  const filterList = [
    {
      type: 'input',
      key: 'keyword',
      label: '关键词',
      props: {},
      other: {},
    },
  ];

  return (
    <PisellQuickFilter
      filterList={filterList}
      formFiltersPrefix="customPrefix" // 自定义前缀
    />
  );
};

export default Demo;
```

## 注意事项

1. **表单前缀**: `formFiltersPrefix` 参数用于设置表单字段的前缀，确保表单字段不冲突
2. **筛选项配置**: 每个筛选项的 `key` 必须唯一
3. **类型匹配**: 确保 `type` 和 `props` 配置匹配对应的组件类型
4. **性能优化**: 大量筛选项时，建议使用 `quickFilterMaxLength` 限制显示数量

## 设计指南

详见 [设计文档](./PisellQuickFilter.$tab-design.md)

## 开发指南

详见 [开发文档](./PisellQuickFilter.$tab-dev.md)

## 测试指南

详见 [测试文档](./PisellQuickFilter.$tab-test.md)
