# 前端组件库文档

## 1. 简介

本组件库基于 React + Umi 框架开发，提供了一系列常用的 UI 组件和功能组件，旨在提高前端开发效率和代码复用性。

## 2. 安装

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

## 3. 核心组件

### 3.1 UI 组件

#### Button 按钮

```tsx
import { Button } from '@/components';

<Button type="primary" size="middle" onClick={() => console.log('点击了按钮')}>
  主要按钮
</Button>

<Button type="secondary" disabled>
  禁用按钮
</Button>

<Button type="danger" loading>
  加载中
</Button>
```

#### Input 输入框

```tsx
import { Input } from '@/components';

<Input
  label="用户名"
  placeholder="请输入用户名"
  value={username}
  onChange={(e) => setUsername(e.target.value)}
/>

<Input
  label="密码"
  type="password"
  error="密码长度至少8个字符"
  value={password}
  onChange={(e) => setPassword(e.target.value)}
/>
```

#### Card 卡片

```tsx
import { Card } from '@/components';

<Card title="卡片标题" footer={<Button>操作按钮</Button>}>
  卡片内容
</Card>

<Card shadow="lg" className="mb-4">
  带阴影的卡片
</Card>
```

### 3.2 功能组件

#### Table 表格

```tsx
import { Table } from '@/components';

const columns = [
  { title: '姓名', dataIndex: 'name', key: 'name' },
  { title: '年龄', dataIndex: 'age', key: 'age' },
  { title: '地址', dataIndex: 'address', key: 'address' },
  { 
    title: '操作', 
    key: 'action',
    render: (_, record) => (
      <Button size="small" onClick={() => handleEdit(record)}>
        编辑
      </Button>
    )
  },
];

const dataSource = [
  { id: 1, name: '张三', age: 32, address: '北京市朝阳区' },
  { id: 2, name: '李四', age: 28, address: '上海市浦东新区' },
];

<Table
  columns={columns}
  dataSource={dataSource}
  loading={loading}
  pagination={{
    current: page,
    pageSize: pageSize,
    total: total,
    onChange: (page, pageSize) => setPage(page),
  }}
  rowKey="id"
  onRowClick={(record) => console.log('点击了行', record)}
/>
```

#### VirtualList 虚拟列表

```tsx
import { VirtualList } from '@/components';

const data = Array.from({ length: 1000 }, (_, i) => ({
  id: i,
  name: `Item ${i}`,
}));

<VirtualList
  data={data}
  itemHeight={50}
  height={400}
  overscan={5}
  renderItem={(item) => (
    <div className="p-4 border-b">{item.name}</div>
  )}
  keyExtractor={(item) => item.id.toString()}
/>
```

#### LazyLoad 懒加载

```tsx
import { LazyLoad, LazyImage } from '@/components';

<LazyLoad placeholder={<div className="w-full h-40 bg-gray-100">加载中...</div>}>
  <div className="w-full h-40 bg-blue-100">
    懒加载的内容
  </div>
</LazyLoad>

<LazyImage
  src="https://example.com/image.jpg"
  alt="示例图片"
  className="w-full h-40 object-cover"
/>
```

## 4. 状态管理

组件库使用 React 的 useState 和 useCallback 钩子进行状态管理，并提供了 Model 分层的状态管理方案：

```tsx
import { useProductModel } from '@/models';

const { products, loading, setProducts, updateProduct } = useProductModel();
```

## 5. API 服务

组件库提供了完整的 API 服务层，用于与后端进行通信：

```tsx
import { productApi } from '@/services/api';

const fetchProducts = async () => {
  try {
    const response = await productApi.getList({ page: 1, pageSize: 10 });
    setProducts(response.data);
  } catch (error) {
    console.error('获取商品列表失败', error);
  }
};
```

## 6. 响应式设计

组件库支持响应式布局，提供了响应式工具函数：

```tsx
import { useResponsive } from '@/utils/responsive';

const { isMobile, isTablet, isDesktop } = useResponsive();

return (
  <div>
    {isMobile && <MobileComponent />}
    {isTablet && <TabletComponent />}
    {isDesktop && <DesktopComponent />}
  </div>
);
```

## 7. 性能优化

组件库内置了性能优化工具，包括：

- 虚拟列表：高效渲染大量数据
- 懒加载：按需加载图片和组件
- 性能测试：测量组件渲染时间

## 8. 安全措施

组件库提供了安全工具函数，包括：

- 输入 sanitize：防止 XSS 攻击
- CSRF 令牌生成：防止 CSRF 攻击
- 密码强度验证：确保密码安全性

## 9. 开发指南

### 9.1 添加新组件

1. 在 `src/components/ui` 目录下创建新的组件文件
2. 在 `src/components/index.ts` 中导出新组件
3. 在本文档中添加组件的使用示例

### 9.2 组件命名规范

- 组件名称使用 PascalCase（大驼峰命名法）
- 文件名称与组件名称保持一致
- 组件属性使用 camelCase（小驼峰命名法）

### 9.3 代码规范

- 使用 TypeScript 类型定义
- 遵循 React 最佳实践
- 保持代码简洁和可维护性

## 10. 示例应用

组件库包含了完整的示例应用，展示了组件的使用方法和最佳实践。

## 11. 贡献指南

欢迎贡献代码和提出建议，共同完善组件库。

## 12. 版本历史

- v1.0.0：初始版本，包含基础 UI 组件和功能组件
- v1.1.0：添加虚拟列表和懒加载组件
- v1.2.0：完善状态管理和 API 服务
- v1.3.0：添加响应式设计支持
- v1.4.0：增强性能优化和安全措施