Infinite Export

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

✨ 特性

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

📦 安装

npm install infinite-export

🚀 快速开始

基础用法 - 分页请求导出

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()

嵌套字段导出

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' },
]

直接导出已有数据

import { xslxExport } from 'infinite-export'

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

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 写入选项

返回值

{
    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>

列配置类型。

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

🎯 使用场景

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

🔧 开发

# 安装依赖
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！