# infinite-export

**Repository Path**: shy9120/infinite-export

## Basic Information

- **Project Name**: infinite-export
- **Description**: 利用分页等方式在前端实现无限级的 excel 数据导出
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://4z3wzq-2850.csb.app/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-04-04
- **Last Updated**: 2025-12-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 导出

## README

# Infinite Export

一个强大的前端无限级 Excel 数据导出库，支持分页请求、嵌套字段、自定义渲染等功能。

## ✨ 特性

- 🚀 **无限级数据导出** - 通过分页请求方式支持导出任意数量的数据
- 📊 **自动分 Sheet** - 自动将大量数据分割到多个 Sheet 页（每页最多 10000 条）
- 🔗 **嵌套字段支持** - 支持导出嵌套对象字段（如 `author.id`）
- 🎨 **自定义渲染** - 支持自定义列渲染函数，灵活处理数据格式
- 📈 **进度回调** - 实时显示导出进度，支持取消操作
- 💪 **TypeScript 支持** - 完整的 TypeScript 类型定义
- 📦 **轻量级** - 基于 xlsx 库，体积小，性能好

## 📦 安装

```bash
npm install infinite-export
```

## 🚀 快速开始

### 基础用法 - 分页请求导出

```typescript
import { fetchExport, ExportColumnType } from 'infinite-export'

interface User {
    id: number
    name: string
    email: string
    created_at: string
}

const columns: ExportColumnType<User>[] = [
    { title: 'ID', dataIndex: 'id' },
    { title: '姓名', dataIndex: 'name' },
    { title: '邮箱', dataIndex: 'email' },
    { 
        title: '创建时间', 
        dataIndex: 'created_at',
        render: (value) => new Date(value).toLocaleString('zh-CN')
    },
]

const { cancel } = fetchExport({
    body: '/api/users?page=1', // 初始请求参数
    fetch: async (body: string) => {
        const response = await fetch(body)
        const data = await response.json()
        
        return {
            result: {
                list: data.users,
                total: data.total,
            },
            columns,
            body: data.nextPageUrl || undefined, // 返回下一页 URL，没有则停止
        }
    },
    onProcess: (loaded, total, appended) => {
        console.log(`已加载: ${loaded}/${total}, 已追加: ${appended}`)
    },
    filename: '用户列表.xlsx',
})

// 取消导出
// cancel()
```

### 嵌套字段导出

```typescript
interface Order {
    id: number
    user: {
        id: number
        name: string
        profile: {
            email: string
        }
    }
    amount: number
}

const columns: ExportColumnType<Order>[] = [
    { title: '订单ID', dataIndex: 'id' },
    { title: '用户ID', dataIndex: 'user.id' },
    { title: '用户名', dataIndex: 'user.name' },
    { title: '用户邮箱', dataIndex: 'user.profile.email' },
    { title: '金额', dataIndex: 'amount' },
]
```

### 直接导出已有数据

```typescript
import { xslxExport } from 'infinite-export'

const data = [
    { id: 1, name: '张三', email: 'zhangsan@example.com' },
    { id: 2, name: '李四', email: 'lisi@example.com' },
    // ... 更多数据
]

await xslxExport(data, {
    columnsType: [
        { title: 'ID', dataIndex: 'id' },
        { title: '姓名', dataIndex: 'name' },
        { title: '邮箱', dataIndex: 'email' },
    ],
    filename: '用户列表.xlsx',
})
```

## 📖 API 文档

### `fetchExport<T, F>(options: FetchExportProps<T, F>)`

通过分页请求方式导出数据。

#### 参数

- `body?: F` - 初始请求参数
- `fetch: (body: F) => Promise<{ result: Page<T>, columns: ExportColumnType<T>[], body?: F }>` - 数据获取函数
  - `result.list` - 当前页数据列表
  - `result.total` - 数据总数
  - `columns` - 列配置（支持动态修改）
  - `body` - 下一页请求参数，为空时停止循环
- `onProcess?: (loaded: number, total: number, appended: number) => void` - 进度回调
  - `loaded` - 已加载的数据条数
  - `total` - 总数据条数
  - `appended` - 已追加到 Excel 的数据条数
- `filename: string` - 导出文件名
- `sheet_size?: number` - 每个 Sheet 页最大数据条数（默认 10000）
- `sheet_name?: string | ((index: number, total: number) => string)` - Sheet 页名称
  - 字符串：固定名称
  - 函数：动态生成名称（默认格式：`1~10000`）
- `writingOptions?: xlsx.WritingOptions` - xlsx 写入选项

#### 返回值

```typescript
{
    cancel: () => void  // 取消导出函数
}
```

### `xslxExport<T>(list: T[], options: ExportProps<T>)`

直接导出已有数据列表。

#### 参数

- `list: T[]` - 要导出的数据列表
- `options: ExportProps<T>` - 导出配置
  - `columnsType: ExportColumnType<T>[]` - 列配置
  - `filename: string` - 导出文件名
  - `sheet_size?: number` - 每个 Sheet 页最大数据条数（默认 10000）
  - `sheet_name?: string | ((index: number, total: number) => string)` - Sheet 页名称
  - `writingOptions?: xlsx.WritingOptions` - xlsx 写入选项

### `ExportColumnType<T>`

列配置类型。

```typescript
type ExportColumnType<T extends object> = {
    title: string  // 列标题
    dataIndex: FieldKey<T>  // 字段路径，支持嵌套（如 'user.id'）
    render?: (value?: any, record?: T, index?: number) => string  // 自定义渲染函数
}
```

## 🎯 使用场景

- 📊 大数据量报表导出
- 📈 分页数据批量导出
- 🔄 需要实时进度反馈的导出任务
- 🎨 需要自定义数据格式的导出需求
- 📋 嵌套数据结构导出

## 🔧 开发

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 编译 TypeScript
npm run tsc
```

## 📝 注意事项

1. **数据量限制**：虽然支持无限级导出，但建议单次导出不超过 100 万条数据，避免浏览器内存溢出
2. **Sheet 页限制**：Excel 单个文件最多支持 255 个 Sheet 页
3. **浏览器兼容性**：需要支持 ES6+ 和 FileSaver API 的现代浏览器
4. **网络请求**：分页请求导出需要确保 API 支持分页，且返回格式符合要求

## 📄 License

ISC

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！