---
title: 开发文档
order: 3
category: pro
---

# PisellQuickFilter 开发文档

## 技术架构

### 组件结构

```
pisellQuickFilter/
├── index.tsx              # 组件主入口
├── type.ts                # TypeScript 类型定义
└── docs/                  # 组件文档
    ├── PisellQuickFilter.md
    ├── PisellQuickFilter.$tab-design.md
    ├── PisellQuickFilter.$tab-dev.md
    └── PisellQuickFilter.$tab-test.md
```

### 技术栈

- **React**: 使用 `forwardRef` 支持 ref 转发
- **Ant Design**: 基于 `Form` 组件封装
- **TypeScript**: 完整的类型定义

## 核心实现

### 组件封装

> 以下为示意代码。实际实现中 QuickFilter 从 `../filter/components/QuickFilter` 引入（仅 materials
> 包内可用），文档站构建时无法解析该路径，故此处用占位展示结构。

```tsx
import {forwardRef} from 'react';
import {Form} from 'antd';

// 实际源码中: import QuickFilter from '../filter/components/QuickFilter';
// 实际源码中: import type { PisellQuickFilterProps } from './type';
const QuickFilterPlaceholder = ({value, formFiltersPrefix}: { value?: object; formFiltersPrefix?: string }) => (
    <div style={{padding: 8, background: '#f5f5f5', borderRadius: 4}}>QuickFilter 占位</div>
);

const PisellQuickFilter = forwardRef<unknown, Record<string, unknown>>((props, ref) => {
    const {filterList, formFiltersPrefix, ...otherProps} = props as {
        filterList?: object[];
        formFiltersPrefix?: string;
        [k: string]: unknown
    };

    return (
        <Form
            ref={ref}
            labelCol={{span: 0}}
            size="large"
            layout="inline"
            className="filter-form-wrapper"
            {...otherProps}
        >
            <QuickFilterPlaceholder
                value={{quickFilter: filterList}}
                formFiltersPrefix={formFiltersPrefix || ''}
            />
        </Form>
    );
});

export default PisellQuickFilter;
```

### 设计要点

1. **属性解构**: 从 props 中提取关键属性，其余属性透传给 Form
2. **固定配置**: Form 使用固定的布局配置（inline、large）
3. **数据转换**: 将 `filterList` 转换为 QuickFilter 需要的数据格式
4. **forwardRef**: 支持外部获取表单实例

## 类型定义

### PisellQuickFilterProps

```typescript
export type PisellQuickFilterProps = FormInstance & {
    children?: React.ReactNode;
    formFiltersPrefix: string;          // 表单字段前缀
    filterList?: FilterItemProps[];     // 筛选项列表
    quickFilterMaxLength: number;       // 快速筛选最大数量
    hiddenQuickFilter: boolean;         // 是否隐藏快速筛选
    hiddenOtherFilter: boolean;         // 是否隐藏其他筛选
}
```

### FilterItemProps

继承自 `filter` 组件的类型定义，支持多种筛选项类型。

## 依赖关系

### 内部依赖

- `filter/components/QuickFilter`: 实际的快速筛选实现组件
- `filter/types`: 筛选项类型定义

### 外部依赖

- `react`: React 核心库
- `antd`: Ant Design 组件库（Form 组件）

## 扩展开发

### 添加新的筛选类型

如需添加新的筛选类型，需要：

1. 在 `filter/types.ts` 中扩展 `FilterItemProps` 类型
2. 在 `filter/components/QuickFilter` 中实现对应的渲染逻辑
3. 更新文档说明新增的筛选类型

### 自定义样式

可以通过以下方式自定义样式：

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

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

export default () => (
    <PisellQuickFilter
        filterList={filterList}
        formFiltersPrefix="filters"
        className="custom-quick-filter"
        style={{backgroundColor: '#f5f5f5'}}
    />
);
```

然后在全局或组件样式中定义：

```less
.custom-quick-filter {
  .filter-form-wrapper {
    // 自定义样式
  }
}
```

## 性能优化

### 组件优化建议

1. **使用 memo**: 如果父组件频繁渲染，考虑使用 `React.memo` 包裹
2. **回调优化**: 使用 `useCallback` 优化传入的回调函数
3. **数据缓存**: 对于静态的 `filterList`，可以提取到组件外部避免重复创建

### 示例

```tsx
import {useMemo, useCallback} from 'react';
import {PisellQuickFilter} from '@pisell/materials';

export default () => {
    // 缓存筛选项列表
    const filterList = useMemo(() => [
        {
            type: 'input',
            key: 'keyword',
            label: '关键词',
            props: {},
            other: {},
        },
    ], []);

    // 优化回调函数
    const handleValuesChange = useCallback((changedValues: object, allValues: object) => {
        console.log('Values changed:', changedValues);
    }, []);

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

## 调试技巧

### 查看表单值

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

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

export default () => {
    const formRef = useRef<{ getFieldsValue: () => object }>(null);

    const handleCheck = () => {
        console.log('Form values:', formRef.current?.getFieldsValue());
    };

    return (
        <>
            <PisellQuickFilter
                ref={formRef}
                filterList={filterList}
                formFiltersPrefix="filters"
            />
            <button onClick={handleCheck}>查看表单值</button>
        </>
    );
};
```

## 常见问题

### Q: 为什么表单值没有更新？

A: 确保正确使用了 `formFiltersPrefix` 和 `filterList` 中的 `key` 配置。

### Q: 如何获取表单实例？

A: 使用 `ref` 获取表单实例，组件通过 `forwardRef` 支持 ref 转发。

### Q: 筛选项不显示怎么办？

A: 检查 `filterList` 配置是否正确，特别是 `type` 和 `props` 是否匹配。

## 贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个组件！

提交 PR 前请确保：

1. ✅ 代码符合项目规范
2. ✅ 添加了必要的注释
3. ✅ 更新了相关文档
4. ✅ 通过了单元测试
