# List 组件设计文档

## 1. 概述

List 组件是一个高度可配置的列表展示组件，支持多种布局模式、分页方式和响应式设计。组件采用模块化架构，具备出色的性能和可扩展性。

## 2. 架构设计

### 2.1 整体架构

```
List 组件
├── 核心组件层
│   ├── List.tsx          # 主列表组件
│   ├── ResponsiveWrapper.tsx # 响应式包装器
│   └── TestResponsiveWrapper.tsx # 测试组件
├── 子组件层
│   ├── Tab/              # 标签页组件
│   ├── Pagination/       # 分页组件
│   ├── EmptyState/       # 空状态组件
│   ├── ScrollLoader/     # 滚动加载组件
│   └── WaterfallList/    # 瀑布流组件
├── 状态管理层
│   ├── useListState.ts   # 列表状态管理
│   ├── useWaterfall.ts   # 瀑布流布局算法
│   └── useDevice.ts      # 设备检测
└── 样式层
    ├── base.less         # 基础样式
    ├── content.less      # 内容区域样式
    ├── header.less       # 头部样式
    ├── footer.less       # 底部样式
    ├── floatButton.less  # 浮动按钮样式
    └── responsive.less   # 响应式样式
```

### 2.2 设计原则

- **可组合性**：采用组件化设计，各功能模块独立且可复用
- **可配置性**：提供丰富的配置项，满足不同业务场景需求
- **响应式**：支持多设备适配，提供统一的响应式配置接口
- **性能优化**：使用 useMemo、useCallback 等优化渲染性能
- **类型安全**：完整的 TypeScript 类型定义，支持泛型约束

## 3. 核心功能

### 3.1 布局系统

#### 3.1.1 布局模式

1. **网格布局 (Grid Layout)**
   - 支持固定列数和行数
   - 自动计算项目尺寸
   - 支持垂直和水平排版

2. **瀑布流布局 (Waterfall Layout)**
   - 自适应高度排列
   - 智能列平衡算法
   - 支持预设尺寸优化

#### 3.1.2 排版方向

- **垂直排版**：从上到下，从左到右
- **水平排版**：从左到右，从上到下

#### 3.1.3 间距控制

- `columnGap`：列间距
- `rowGap`：行间距
- 支持像素值精确控制

### 3.2 分页系统

#### 3.2.1 分页模式

1. **全部显示 (All)**
   - 一次性显示所有数据
   - 适用于数据量较小的场景

2. **滚动加载 (Scroll)**
   - 支持自动触发和手动触发
   - 智能检测滚动边界
   - 防抖优化，避免频繁请求

3. **分页器 (Pager)**
   - 传统分页器界面
   - 支持页码跳转和每页数量调整
   - 显示数据总数信息

4. **查看更多 (More)**
   - 点击按钮加载更多数据
   - 支持"查看更少"功能
   - 渐进式数据加载

#### 3.2.2 数据加载机制

```typescript
interface LoadDataParams {
  trigger: 'tabChange' | 'pagination' | 'pageSize' | 'loadMore' | 'scroll';
  currentPage: number;
  pageSize: number;
  activeTab?: string;
  previousPage?: number;
  previousPageSize?: number;
}
```

### 3.3 标签页系统

#### 3.3.1 标签页模式

1. **锚点模式 (Anchor)**
   - 页面内锚点跳转
   - 分组数据展示
   - 平滑滚动定位

2. **切换模式 (Switch)**
   - 传统标签页切换
   - 数据过滤显示
   - 单一内容区域

3. **无标签 (None)**
   - 隐藏标签页
   - 显示所有数据

#### 3.3.2 数据分组逻辑

- 支持自定义分组字段
- 智能字段匹配算法
- 动态数据过滤

### 3.4 响应式系统

#### 3.4.1 设备检测

```typescript
interface DeviceInfo {
  type: 'pc' | 'pad' | 'mobile';
  isMobile: boolean;
  isPad: boolean;
  isPc: boolean;
  width: number;
  height: number;
}
```

#### 3.4.2 断点定义

- **移动端**：< 768px
- **平板端**：768px - 1200px
- **PC端**：≥ 1200px

#### 3.4.3 响应式配置

```typescript
interface ResponsiveProps {
  default: ListProps;      // 默认配置
  pc?: Partial<ListProps>; // PC端配置
  pad?: Partial<ListProps>; // 平板配置
  mobile?: Partial<ListProps>; // 移动端配置
}
```

## 4. 技术实现

### 4.1 状态管理

#### 4.1.1 统一状态管理

使用自定义 Hook `useListState` 管理所有列表状态：

```typescript
const useListState = ({
  externalCurrentPage,
  tabItems,
  defaultPageSize,
  onLoadData
}) => {
  // 内部状态管理逻辑
  const [state, setState] = useState(initialState);
  
  // 提供统一的状态更新接口
  return {
    state,
    actualCurrentPage,
    handleTabChange,
    handlePageChange,
    handleShowSizeChange,
    handleLoadMore,
    handleViewLess,
    handleScrollLoad,
    setStickyActive
  };
};
```

#### 4.1.2 状态结构

```typescript
interface ListState {
  activeTab: string;           // 当前活跃标签
  isStickyActive: boolean;     // 粘性头部状态
}
```

### 4.2 瀑布流算法

#### 4.2.1 核心算法

```typescript
const useWaterfall = (items: any[], options: WaterfallOptions) => {
  const calculateLayout = useCallback(() => {
    // 1. 初始化轨道高度数组
    const trackHeights = new Array(options.tracks).fill(0);
    
    // 2. 为每个项目计算位置
    const layout = items.map((item, index) => {
      // 找到最短的轨道
      const minHeightIndex = trackHeights.indexOf(Math.min(...trackHeights));
      
      // 计算项目位置
      const position = {
        x: minHeightIndex * (itemWidth + options.trackGap),
        y: trackHeights[minHeightIndex]
      };
      
      // 更新轨道高度
      trackHeights[minHeightIndex] += itemHeight + options.itemGap;
      
      return { ...item, position, index };
    });
    
    return layout;
  }, [items, options]);
  
  return {
    layout: calculateLayout(),
    registerItemRef,
    recalculateLayout
  };
};
```

#### 4.2.2 性能优化

- **虚拟化渲染**：仅渲染可视区域项目
- **位置缓存**：缓存已计算的位置信息
- **增量更新**：仅重新计算变化的项目

### 4.3 滚动处理

#### 4.3.1 滚动监听优化

```typescript
// 防抖滚动处理
const handleScroll = useMemo(
  () => debounce(() => {
    const element = listRef.current;
    const { scrollTop, scrollHeight, clientHeight } = element;
    const isNearEnd = scrollTop + clientHeight >= scrollHeight - 50;
    
    if (isNearEnd && hasMore && !loading) {
      handleScrollLoad();
    }
  }, 100),
  [hasMore, loading, handleScrollLoad]
);
```

#### 4.3.2 自动加载检测

```typescript
// 检测内容是否不足以产生滚动条
const checkAutoLoad = useCallback(() => {
  const element = listRef.current;
  const needsMoreContent = element.scrollHeight <= element.clientHeight;
  
  if (needsMoreContent && hasMore && !loading) {
    handleScrollLoad(); // 自动加载更多数据
  }
}, [hasMore, loading, handleScrollLoad]);
```

### 4.4 样式系统

#### 4.4.1 CSS 架构

- **BEM 命名规范**：保证样式的可维护性
- **模块化设计**：按功能拆分样式文件
- **CSS Variables**：支持主题定制

#### 4.4.2 响应式样式

```less
// 移动端优先的响应式设计
.pisell-list {
  // 基础样式（移动端）
  
  @media (min-width: 768px) {
    // 平板端样式
  }
  
  @media (min-width: 1200px) {
    // PC端样式
  }
}
```

### 4.5 性能优化策略

#### 4.5.1 渲染优化

- **useMemo**：缓存计算结果
- **useCallback**：缓存回调函数
- **React.memo**：子组件记忆化

#### 4.5.2 数据处理优化

- **数据扁平化**：减少嵌套计算
- **增量更新**：仅处理变化数据
- **懒加载**：按需加载数据

#### 4.5.3 事件优化

- **事件委托**：减少事件监听器数量
- **防抖节流**：优化高频事件处理
- **Passive 监听**：提升滚动性能

## 5. 扩展性设计

### 5.1 插槽系统

```typescript
// 支持自定义渲染函数
interface ListProps {
  renderItem?: (item: any, index: number) => ReactNode;
  children?: ReactNode;
}
```

### 5.2 主题定制

```less
// CSS 变量支持
:root {
  --list-primary-color: #1890ff;
  --list-border-color: #d9d9d9;
  --list-border-radius: 6px;
  --list-gap-size: 12px;
}
```

### 5.3 国际化支持

```typescript
// 多语言文本配置
const texts = {
  'en-US': {
    'pisell-list-empty-text-default': 'No data available',
    'pisell-list-load-more': 'Load More'
  },
  'zh-CN': {
    'pisell-list-empty-text-default': '暂无数据',
    'pisell-list-load-more': '查看更多'
  }
};
```

## 6. 测试策略

### 6.1 单元测试

- 核心逻辑函数测试
- Hook 功能测试
- 组件渲染测试

### 6.2 集成测试

- 组件交互测试
- 数据流测试
- 响应式测试

### 6.3 性能测试

- 渲染性能测试
- 内存使用测试
- 滚动流畅度测试

## 7. 版本规划

### 7.1 当前版本 (v1.0.0)

- 基础列表功能
- 多种布局模式
- 分页系统
- 响应式支持

### 7.2 后续版本规划

- **v1.1.0**：虚拟化滚动优化
- **v1.2.0**：拖拽排序功能
- **v1.3.0**：高级过滤搜索
- **v2.0.0**：架构重构优化

## 8. 最佳实践

### 8.1 性能最佳实践

- 合理使用 memo 优化
- 避免在渲染函数中创建对象
- 使用 key 优化列表渲染
- 控制数据量，避免一次性渲染过多项目

### 8.2 可维护性最佳实践

- 保持组件功能单一
- 使用 TypeScript 类型约束
- 编写完整的文档和示例
- 遵循代码规范和最佳实践

### 8.3 用户体验最佳实践

- 提供加载状态反馈
- 合理的错误处理
- 流畅的动画过渡
- 响应式设计适配