---
nav:
  title: 组件
  order: 1
group:
  title: DataDisplay
  order: 3
title: PisellFilter
order: 16
category: pro
---

# PisellFilter - 筛选组件

## 简介

PisellFilter 是一个强大的筛选组件，基于 Ant Design Form 封装，提供了快速筛选和高级筛选两种模式。适用于表格、列表等需要复杂筛选功能的场景。

## 特性

- 🎯 **双模式筛选**: 支持快速筛选和高级筛选两种模式
- 🎨 **灵活配置**: 支持多种筛选类型（单选、输入、日期等）
- 📱 **表单集成**: 基于 Ant Design Form 封装，支持表单联动
- 🔄 **受控模式**: 支持完全受控的筛选状态管理
- ⚡ **性能优化**: 合理的状态管理和更新机制
- 🎭 **TypeScript**: 完整的 TypeScript 类型定义

## 基础用法

```tsx
import {useState} from 'react';
import {PisellFilter} from '@pisell/materials';

const Demo = () => {
    const [filterValue, setFilterValue] = useState({
        quickFilter: [],
        otherFilter: [],
    });

    return (
        <PisellFilter
            value={filterValue}
            onChange={setFilterValue}
            quickFilterMaxLength={5}
            formFiltersPrefix="filter_"
        />
    );
};

export default Demo;
```

## API

### PisellFilter Props

| 参数                   | 说明         | 类型                                           | 默认值       | 版本 |
|----------------------|------------|----------------------------------------------|-----------|----|
| value                | 筛选值        | `FilterValueType`                            | -         | -  |
| onChange             | 筛选值变化回调    | `(value: FilterValueType) => void`           | -         | -  |
| hiddenQuickFilter    | 隐藏快速筛选     | `boolean`                                    | `true`    | -  |
| hiddenOtherFilter    | 隐藏高级筛选     | `boolean`                                    | `false`   | -  |
| quickFilterMaxLength | 快速筛选最大显示数量 | `number`                                     | `100`     | -  |
| formFiltersPrefix    | 表单字段前缀     | `string`                                     | `''`      | -  |
| renderItem           | 自定义渲染筛选项   | `(item: any, otherProps?: any) => ReactNode` | -         | -  |
| size                 | 筛选按钮尺寸     | `'small' \| 'middle' \| 'large'`             | `'large'` | -  |
| placement            | 弹出层定位      | `Popover` 的 placement                        | -         | -  |

### FilterValueType

```typescript
interface FilterValueType {
    quickFilter: FilterItemProps[];  // 快速筛选项数组
    otherFilter: FilterItemProps[];  // 高级筛选项数组
}
```

### FilterItemProps

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

## 进阶用法

### 快速筛选模式

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

const Demo = () => {
    const [filterValue, setFilterValue] = useState({
        quickFilter: [
            {
                type: 'single',
                key: 'status',
                label: '状态',
                name: 'status',
                props: {
                    options: [
                        {label: '全部', value: 'all'},
                        {label: '启用', value: 'enabled'},
                        {label: '禁用', value: 'disabled'},
                    ],
                },
                other: {},
            },
        ],
        otherFilter: [],
    });

    return (
        <PisellFilter
            value={filterValue}
            onChange={setFilterValue}
            hiddenQuickFilter={false}
            hiddenOtherFilter={true}
            quickFilterMaxLength={3}
        />
    );
};

export default Demo;
```

### 高级筛选模式

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

const Demo = () => {
    const [filterValue, setFilterValue] = useState({
        quickFilter: [],
        otherFilter: [
            {
                type: 'input',
                key: 'keyword',
                label: '关键词',
                name: 'keyword',
                props: {
                    placeholder: '请输入关键词',
                },
                other: {},
            },
            {
                type: 'datePicker',
                key: 'created_at',
                label: '创建时间',
                name: 'created_at',
                props: {},
                other: {},
            },
        ],
    });

    return (
        <PisellFilter
            value={filterValue}
            onChange={setFilterValue}
            hiddenQuickFilter={true}
            hiddenOtherFilter={false}
        />
    );
};

export default Demo;
```

### 混合模式

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

const Demo = () => {
    const [filterValue, setFilterValue] = useState({
        quickFilter: [
            {
                type: 'single',
                key: 'category',
                label: '分类',
                name: 'category',
                props: {
                    options: [
                        {label: '全部', value: 'all'},
                        {label: '类型A', value: 'a'},
                        {label: '类型B', value: 'b'},
                    ],
                },
                other: {},
            },
        ],
        otherFilter: [
            {
                type: 'rangePicker',
                key: 'date_range',
                label: '日期范围',
                name: ['start_date', 'end_date'],
                props: {},
                other: {},
            },
        ],
    });

    return (
        <PisellFilter
            value={filterValue}
            onChange={setFilterValue}
            hiddenQuickFilter={false}
            hiddenOtherFilter={false}
            quickFilterMaxLength={5}
            formFiltersPrefix="filter_"
        />
    );
};

export default Demo;
```

### 自定义渲染

```tsx
import {PisellFilter} from '@pisell/materials';
import {Tag} from 'antd';

const Demo = () => {
    const [filterValue, setFilterValue] = useState({
        quickFilter: [],
        otherFilter: [],
    });

    const renderItem = (item: any, otherProps: any) => {
        return (
            <div style={{padding: '8px'}}>
                <Tag color="blue">{item.label}</Tag>
                {/* 自定义渲染逻辑 */}
            </div>
        );
    };

    return (
        <PisellFilter
            value={filterValue}
            onChange={setFilterValue}
            renderItem={renderItem}
        />
    );
};

export default Demo;
```

### 本地筛选

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

const Demo = () => {
    const [filterValue, setFilterValue] = useState({
        quickFilter: [
            {
                type: 'single',
                key: 'status',
                label: '状态',
                name: 'status',
                props: {
                    options: [
                        {label: '全部', value: 'all'},
                        {label: '启用', value: 'enabled'},
                    ],
                },
                localFilter: true,  // 启用本地筛选
                other: {},
            },
        ],
        otherFilter: [],
    });

    return (
        <PisellFilter
            value={filterValue}
            onChange={setFilterValue}
            hiddenQuickFilter={false}
        />
    );
};

export default Demo;
```

## 筛选类型说明

### 1. single - 单选筛选

适用于选项固定的单选场景，如状态、分类等。

```typescript
{
    type: 'single',
        key
:
    'status',
        label
:
    '状态',
        name
:
    'status',
        props
:
    {
        options: [
            {label: '全部', value: 'all'},
            {label: '启用', value: 'enabled'},
            {label: '禁用', value: 'disabled'},
        ],
    }
,
    other: {
    }
,
}
```

### 2. input - 输入框筛选

适用于文本输入场景，如关键词搜索。

```typescript
{
    type: 'input',
        key
:
    'keyword',
        label
:
    '关键词',
        name
:
    'keyword',
        props
:
    {
        placeholder: '请输入关键词',
    }
,
    other: {
    }
,
}
```

### 3. datePicker - 日期选择

适用于单个日期选择场景。

```typescript
{
    type: 'datePicker',
        key
:
    'created_at',
        label
:
    '创建时间',
        name
:
    'created_at',
        props
:
    {
        format: 'YYYY-MM-DD',
    }
,
    other: {
    }
,
}
```

### 4. rangePicker - 日期范围选择

适用于日期范围筛选场景。

```typescript
{
    type: 'rangePicker',
        key
:
    'date_range',
        label
:
    '日期范围',
        name
:
    ['start_date', 'end_date'],
        props
:
    {
        format: 'YYYY-MM-DD',
    }
,
    other: {
    }
,
}
```

### 5. search - 搜索框

适用于带搜索按钮的输入场景。

```typescript
{
    type: 'search',
        key
:
    'search',
        label
:
    '搜索',
        name
:
    'search',
        props
:
    {
        placeholder: '请输入搜索内容',
    }
,
    other: {
    }
,
}
```

## 注意事项

1. **表单集成**: PisellFilter 组件内部已集成 Form，使用时无需再包裹 Form 组件
2. **状态管理**: 组件使用受控模式，需要通过 `value` 和 `onChange` 管理状态
3. **字段前缀**: 使用 `formFiltersPrefix` 可以避免字段名冲突
4. **性能优化**: 大量筛选项时，建议设置合理的 `quickFilterMaxLength`
5. **数据结构**: 确保 `quickFilter` 和 `otherFilter` 的数据结构符合 `FilterItemProps` 类型定义

## 设计指南

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

## 开发指南

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

## 测试指南

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