# List 列表组件

一个功能丰富、高度可配置的 React 列表组件，支持多种布局模式、分页方式和响应式设计。

## ✨ 特色功能

- 🎯 **多种布局模式**：网格布局、瀑布流布局，支持垂直/水平排版
- 📱 **响应式设计**：自动适配 PC、平板、移动端，支持自定义断点配置  
- 🚀 **智能分页**：支持滚动加载、分页器、查看更多等多种分页模式
- 🏷️ **灵活标签页**：支持切换模式和锚点模式，自动数据分组
- ⚡ **性能优化**：虚拟化渲染、智能缓存、防抖优化
- 🎨 **主题定制**：CSS 变量支持，完全可定制的样式系统
- 🌍 **国际化**：内置多语言支持
- 📦 **TypeScript**：完整的类型定义，支持泛型约束

## 🚀 快速开始

### 安装

```bash
npm install @pisell/private-materials
```

### 基础使用

```tsx
import React from 'react';
import { List } from '@pisell/private-materials';

const data = [
  { id: 1, title: '项目 1', category: 'frontend' },
  { id: 2, title: '项目 2', category: 'backend' },
  { id: 3, title: '项目 3', category: 'frontend' },
];

const App = () => {
  return (
    <List
      data={data}
      displayStyle="grid"
      columns={3}
      renderItem={(item) => (
        <div className="item-card">
          <h3>{item.title}</h3>
          <span>{item.category}</span>
        </div>
      )}
    />
  );
};

export default App;
```

## 📋 主要配置选项

### 布局配置

```tsx
<List
  displayStyle="grid"          // 'grid' | 'waterfall'
  layoutDirection="vertical"   // 'vertical' | 'horizontal'
  columns={3}                 // 网格列数
  rows={2}                    // 网格行数（水平布局）
  columnGap={16}              // 列间距
  rowGap={12}                 // 行间距
  width={800}                 // 容器宽度
  height={600}                // 容器高度
/>
```

### 分页配置

```tsx
<List
  paginationType="scroll"      // 'all' | 'scroll' | 'pager' | 'more'
  defaultPageSize={12}        // 每页显示数量
  pagination={{
    current: 1,               // 当前页码
    total: 10,                // 总页数
    totalCount: 120           // 总数据条数
  }}
  onLoadData={(params) => {
    // 处理数据加载
    console.log('加载数据:', params);
  }}
  loading={false}             // 加载状态
/>
```

### 标签页配置

```tsx
const tabData = [
  { key: 'all', label: '全部' },
  { key: 'frontend', label: '前端' },
  { key: 'backend', label: '后端' },
];

<List
  tabStyle="switch"           // 'switch' | 'anchor' | 'none'
  tabData={tabData}
  tabGroup="category"         // 分组字段
  stickyTop={true}           // 标签页固定在顶部
/>
```

## 🏗️ 响应式使用

```tsx
import { ResponsiveList, createResponsiveConfig } from '@pisell/private-materials';

const responsiveConfig = createResponsiveConfig({
  default: {    // 移动端 (<768px)
    columns: 1,
    columnGap: 8,
    defaultPageSize: 5
  },
  pad: {        // 平板端 (768px-1200px)
    columns: 2,
    columnGap: 12,
    defaultPageSize: 8
  },
  pc: {         // PC端 (≥1200px)
    columns: 3,
    columnGap: 16,
    defaultPageSize: 12
  }
});

<ResponsiveList
  responsive={responsiveConfig}
  data={data}
  renderItem={renderItem}
/>
```

## 🎨 布局模式展示

### 网格布局
适用于固定尺寸的内容展示，支持响应式列数调整。

```tsx
<List
  displayStyle="grid"
  layoutDirection="vertical"
  columns={4}
  data={data}
  renderItem={renderItem}
/>
```

### 瀑布流布局
适用于不同高度的内容展示，自动平衡各列高度。

```tsx
<List
  displayStyle="waterfall"
  layoutDirection="vertical"
  columns={3}
  data={dataWithHeights}
  renderItem={renderItem}
/>
```

## 🔄 分页模式对比

| 模式 | 描述 | 适用场景 |
|------|------|----------|
| `all` | 全部显示，无分页 | 数据量小（<100条） |
| `scroll` | 滚动自动加载 | 移动端、无限滚动场景 |
| `pager` | 传统分页器 | PC端、需要跳页的场景 |
| `more` | 点击加载更多 | 渐进式内容发现 |

## 🎯 高级功能

### 子组件模式

```tsx
const ItemComponent = ({ item, index }) => (
  <div className="custom-item">
    <h3>{item.title}</h3>
    <p>索引: {index}</p>
  </div>
);

<List data={data}>
  <ItemComponent />
</List>
```

### 设备检测

```tsx
import { useDevice } from '@pisell/private-materials';

const MyComponent = () => {
  const device = useDevice();
  
  return (
    <List
      columns={device.isMobile ? 1 : device.isPad ? 2 : 3}
      data={data}
      renderItem={renderItem}
    />
  );
};
```

### 数据加载处理

```tsx
const handleLoadData = async (params) => {
  const { trigger, currentPage, pageSize, activeTab } = params;
  
  switch (trigger) {
    case 'tabChange':
      // 标签页切换
      await loadDataByCategory(activeTab);
      break;
    case 'scroll':
      // 滚动加载
      await loadMoreData(currentPage);
      break;
    case 'pagination':
      // 分页切换
      await loadPageData(currentPage, pageSize);
      break;
  }
};

<List
  onLoadData={handleLoadData}
  // ... 其他配置
/>
```

## 🎨 样式自定义

### CSS 变量

```css
.my-custom-list {
  --list-primary-color: #1890ff;
  --list-border-color: #d9d9d9;
  --list-border-radius: 6px;
  --list-gap-size: 12px;
}
```

### 自定义类名

```tsx
<List
  className="my-list"
  data={data}
  renderItem={(item) => (
    <div className="my-item">
      {item.title}
    </div>
  )}
/>
```

## 📚 文档和示例

- **[设计文档](./DESIGN.md)** - 详细的架构设计和技术实现
- **[使用指南](./USAGE.md)** - 完整的配置选项和使用方法
- **[在线示例](./examples/)** - 各种使用场景的示例代码

## 🛠️ 开发和调试

### 测试组件

```tsx
import { TestResponsiveWrapper } from '@pisell/private-materials';

// 用于测试不同设备配置的组件
<TestResponsiveWrapper />
```

### 类型支持

```tsx
import { ListProps, BaseListItem } from '@pisell/private-materials';

interface MyItem extends BaseListItem {
  id: string;
  title: string;
  category: string;
}

const MyList: React.FC<{ items: MyItem[] }> = ({ items }) => {
  return (
    <List<MyItem>
      data={items}
      renderItem={(item: MyItem) => (
        <div>{item.title}</div>
      )}
    />
  );
};
```

## ⚡ 性能优化建议

1. **合理设置页面大小**：避免一次性渲染过多项目
2. **使用React.memo**：优化列表项组件渲染
3. **提供稳定的key**：确保每个列表项都有唯一ID
4. **缓存渲染函数**：使用useCallback缓存renderItem
5. **预设尺寸信息**：为瀑布流提供height/width预设值

## 🐛 常见问题

**Q: 滚动加载不起作用？**  
A: 请确保为List组件设置了固定高度，`height="auto"`无法触发滚动事件。

**Q: 标签页分组不起作用？**  
A: 检查数据项中是否包含`tabGroup`指定的字段，以及字段值是否与`tabData`中的`key`匹配。

**Q: 瀑布流布局不平衡？**  
A: 为数据项提供`height`属性可以提前计算布局，获得更好的平衡效果。

## 📄 许可证

MIT License

## 🤝 贡献

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

---

⭐ 如果这个组件对你有帮助，请给我们一个 Star！