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

# PisellSort 设计文档

## 设计理念

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

### 1. 简洁易用

- 基于 Ant Design Form 封装，与现有表单体系无缝集成
- 提供合理的默认配置，开箱即用
- API 设计简洁，降低使用门槛

### 2. 灵活扩展

- 支持多种数据类型的排序（日期、字符串、数字）
- 支持自定义触发按钮
- 支持本地和远程两种排序模式

### 3. 用户体验

- 清晰的排序状态反馈
- 流畅的交互动画
- 合理的默认排序逻辑

## 组件架构

```
PisellSort (Form 包装器)
  └── Form (Ant Design)
       └── Form.Item
            └── Sort (内部排序组件)
```

### 架构说明

- **外层 Form**: 提供表单上下文，支持表单联动和值管理
- **Form.Item**: 处理字段绑定，默认字段名为 `sort_key`
- **Sort 组件**: 实际的排序选择器实现

## 交互设计

### 排序类型

组件支持三种数据类型的排序：

1. **日期类型 (date)**
   - 升序：从旧到新
   - 降序：从新到旧

2. **字符串类型 (string)**
   - 升序：A-Z 字母顺序
   - 降序：Z-A 逆序

3. **数字类型 (number)**
   - 升序：从小到大
   - 降序：从大到小

### 排序模式

1. **远程排序（默认）**
   - 排序值通过 `onChange` 回调传递给父组件
   - 父组件负责处理排序逻辑（如发送请求）

2. **本地排序**
   - 设置 `localFilter: true` 启用
   - 适用于数据量较小的场景
   - 无需后端支持

## 视觉设计

### 触发按钮

- 默认使用 Sort 组件内置的触发按钮
- 支持通过 `button` 属性自定义
- 建议使用图标 + 文字的组合形式

### 下拉菜单

- 采用 Ant Design Menu 组件
- 清晰的排序选项分组
- 高亮显示当前选中项

### 响应式设计

- 支持多种弹出位置配置
- 自适应容器宽度
- 移动端友好

## 可访问性

- 支持键盘导航
- 提供清晰的视觉反馈
- 符合 ARIA 规范

## 设计规范

### 间距规范

- 组件内部采用 Ant Design 标准间距
- Form 布局使用 `vertical` 模式
- Form 大小使用 `large` 尺寸

### 颜色规范

- 遵循 Ant Design 主题色彩系统
- 选中状态使用主色
- 禁用状态使用灰色

## 最佳实践

1. **合理分组**: 将相关的排序字段分组展示
2. **默认排序**: 为常用场景设置合理的默认排序
3. **状态反馈**: 及时反馈当前的排序状态
4. **性能考虑**: 大数据量场景优先使用远程排序

### 设计资源

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