---
title: 设计文档
order: 2
category: pro
---

# PisellFilter 设计文档

## 设计理念

PisellFilter 组件的设计遵循以下核心原则：

### 1. 渐进式筛选

- **快速筛选**: 提供常用筛选项的快速访问
- **高级筛选**: 支持更复杂的筛选条件组合
- **分层展示**: 将简单和复杂的筛选分离，降低用户认知负担

### 2. 灵活可扩展

- 支持多种筛选类型（单选、输入、日期等）
- 支持自定义渲染筛选项
- 支持本地和远程两种筛选模式

### 3. 用户体验优先

- 清晰的视觉层次
- 流畅的交互反馈
- 合理的默认配置

## 组件架构

```
PisellFilter (Form 包装器)
  └── Form (Ant Design)
       └── FilterButton (筛选按钮组件)
            ├── QuickFilter (快速筛选区)
            │    └── FilterItem[]
            └── OtherFilter (高级筛选区)
                 └── FilterItem[]
```

### 架构说明

- **外层 Form**: 提供表单上下文，支持表单联动和值管理
- **FilterButton**: 实际的筛选器实现，处理筛选逻辑
- **QuickFilter**: 快速筛选区域，显示常用筛选项
- **OtherFilter**: 高级筛选区域，显示更多筛选选项

## 交互设计

### 筛选模式

组件支持两种筛选模式的组合使用：

1. **快速筛选模式**
   - 直接展示在界面上
   - 适合 3-5 个常用筛选项
   - 即时响应，无需点击确认

2. **高级筛选模式**
   - 通过弹出层展示
   - 适合多个筛选条件组合
   - 支持批量设置和确认

### 筛选类型

#### 1. Single（单选）
- 适用场景：状态、分类等枚举值筛选
- 交互方式：点击即选中
- 视觉反馈：选中项高亮显示

#### 2. Input（输入框）
- 适用场景：关键词、编号等文本搜索
- 交互方式：输入文本后失焦或回车确认
- 视觉反馈：输入框激活状态

#### 3. DatePicker（日期选择）
- 适用场景：单个日期筛选
- 交互方式：点击选择日期
- 视觉反馈：日历面板展开

#### 4. RangePicker（日期范围）
- 适用场景：时间段筛选
- 交互方式：选择开始和结束日期
- 视觉反馈：双日历面板展开

#### 5. Search（搜索框）
- 适用场景：带搜索按钮的输入
- 交互方式：输入后点击搜索按钮
- 视觉反馈：搜索图标和加载状态

## 视觉设计

### 布局规范

- **快速筛选区**: 水平排列，自动换行
- **高级筛选区**: 垂直排列，分组展示
- **间距**: 筛选项之间保持 8px 间距
- **对齐**: 左对齐，保持视觉整齐

### 状态设计

1. **默认状态**
   - 未选中：默认样式
   - 已选中：主色高亮

2. **交互状态**
   - Hover：轻微背景色变化
   - Active：按下效果
   - Focus：焦点框

3. **禁用状态**
   - 灰色显示
   - 不可点击
   - 禁用提示

### 颜色规范

- **主色**: 用于选中状态和重要操作
- **辅助色**: 用于次要信息和边框
- **文字色**: 
  - 主文字：#000000 (85%)
  - 次文字：#000000 (65%)
  - 禁用：#000000 (25%)

## 响应式设计

### 桌面端
- 筛选项横向排列
- 支持多行展示
- 快速筛选和高级筛选并存

### 移动端
- 筛选项纵向排列
- 优先显示快速筛选
- 高级筛选通过抽屉展开

## 可访问性

### 键盘支持
- Tab: 在筛选项间切换
- Enter: 确认选择
- Esc: 关闭筛选面板
- Space: 展开/收起选项

### 屏幕阅读器
- 提供清晰的 ARIA 标签
- 描述筛选项的作用
- 播报筛选结果数量

### 对比度
- 确保文字和背景有足够对比度
- 选中状态清晰可辨
- 禁用状态视觉明确

## 性能考虑

### 渲染优化
- 使用虚拟滚动处理大量筛选项
- 延迟渲染非可见区域
- 防抖处理输入事件

### 数据处理
- 本地筛选使用 Web Worker
- 远程筛选支持取消请求
- 合理设置筛选项最大数量

## 设计规范

### 尺寸规范

- **筛选项高度**: 32px (large)
- **最小宽度**: 80px
- **最大宽度**: 根据内容自适应
- **间距**: 8px

### 文案规范

- **标签文字**: 简洁明确，不超过 4 个字
- **占位符**: 提供操作提示
- **空状态**: 友好的空状态提示

## 最佳实践

1. **筛选项数量**: 快速筛选不超过 5 个，高级筛选按需配置
2. **默认值**: 为常用场景设置合理的默认筛选
3. **状态反馈**: 及时反馈当前的筛选状态和结果数量
4. **重置功能**: 提供清除所有筛选的快捷方式
5. **记忆功能**: 记住用户的筛选习惯（localStorage）

### 设计资源

- [Figma 设计稿](https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=12666-71379)
- [文档规范](https://m1ed09stz4r.feishu.cn/wiki/JWZXwKJFTiMsLOkZpfGcyk5qnah)

