@senlinz/import-export

面向浏览器的高阶 Excel 模板生成、导出与导入 API。

English

安装

pnpm add @senlinz/import-export

WASM 加载

• importExcel、importExcelDynamic、exportExcel、fromExcel、fromExcelDynamic、toExcel、downloadExcelTemplate、generateExcelTemplate 会在首次调用时自动加载并初始化内置 WASM 资源。
• 在 Vite 和其他浏览器 ESM bundler 中，使用高阶 core 包时不再需要手动调用 initializeWasm(...) 或自己处理 ?url。
• 如果你需要自行管理 WASM 模块，请直接使用 @senlinz/import-export-wasm，而不是这个高阶包。

import { toExcel } from '@senlinz/import-export';

const workbook = await toExcel({
  name: 'TomAndJerry',
  columns: [{ key: 'name', name: 'Name', dataType: 'text' }],
}, [{ name: 'Tom' }]);

支持的 API

稳定的 definition 字段

• name：模板 / 导出下载时使用的文件名
• sheetName：导出时使用、导入时优先匹配的工作表名称
• columns：表头、校验和行映射使用的稳定列定义
• author：可选的工作簿作者元数据
• createTime：可选的工作簿创建时间，支持 Date 或日期字符串
• maxFileSizeBytes：浏览器上传的字节大小上限（默认 25 MiB），在读取前先校验
• title、titleHeight、titleFormat：可选的合并标题行及其高度、样式
• defaultRowHeight、headerRowHeight：导出时数据行和表头行的行高
• dx、dy：表头写入前的横向、纵向偏移量
• isHeaderFreeze：冻结表头区域，滚动时仍保持列标题可见
• progressCallback：长时间导入 / 导出过程中的进度回调
• imageFetcher：导出 image 列时必需的图片数据解析回调
• escapeFormulas：导出时自动转义类似公式的文本，默认开启，可显式关闭以允许公式

稳定的列字段

• key：唯一的程序字段名
• name：工作表中显示的列表头
• width：导出列宽
• note：附加在表头单元格上的备注 / 注释
• dataType：标量单元格类型
• allowedValues：单元格允许值的校验列表
• parent：多级表头时的父级表头 key
• format：列的基础单元格格式
• valueFormat：导出值的直接或条件格式覆盖
• dataGroup：嵌套导出数据使用的逻辑分组标识
• dataGroupParent：嵌套导出数据使用的父级分组标识

支持的 dataType

• text：默认文本类型
• number：有限数值
• date：导出时支持 Date 实例或日期字符串
• image：通过 imageFetcher 解析图片 URL 或标识

导入 / 导出流程

import { downloadExcelTemplate, exportExcel, importExcel } from '@senlinz/import-export';

const definition = {
  name: 'TomAndJerry',
  sheetName: 'sheet1',
  columns: [
    { key: 'name', name: 'Name', dataType: 'text', width: 20, note: 'required' },
    { key: 'age', name: 'Age', dataType: 'number', width: 10 },
    { key: 'birthday', name: 'Birthday', dataType: 'date', width: 18 },
    { key: 'category', name: 'Category', allowedValues: ['Cat', 'Mouse'] },
    { key: 'image', name: 'Image', dataType: 'image', width: 10 },
  ],
  imageFetcher: async (url: string) => new Uint8Array(await (await fetch(url)).arrayBuffer()),
};

await downloadExcelTemplate(definition);

await exportExcel(definition, [
  { name: 'Tom', age: 12, birthday: '2024-11-01 00:00:00', category: 'Cat', image: '/Tom.jpg' },
  { name: 'Jerry', age: null, birthday: null, category: 'Mouse', image: '/Jerry.png' },
]);

const rows = await importExcel(definition);

动态导入

当你不想预先定义 columns，并希望直接使用浏览器文件选择框时，可使用 importExcelDynamic(options?)。

import { importExcelDynamic } from '@senlinz/import-export';

const result = await importExcelDynamic({
  sheetName: 'sheet1',
  headerRow: 1,
});

当你已经拿到工作簿字节数据时，可继续使用 fromExcelDynamic(buffer, options?)。

import { fromExcelDynamic } from '@senlinz/import-export';

const result = await fromExcelDynamic(fileBytes, {
  sheetName: 'sheet1',
  headerRow: 1,
});

• importExcelDynamic(...) 依赖 DOM / 浏览器文件上传 API。
• sheetName 可选，未提供或不存在时会回退到第一个工作表。
• headerRow 可选，使用从 1 开始的行号，默认会自动选择首个非空行。
• maxFileSizeBytes 可选，与 schema 导入相同，默认 25 MiB。
• 返回值结构为 { sheetName, headers, rows }。

导入行为

• 表头必须与 columns[].name 完全一致。
• number 列导入后返回数字。
• 空的 number / date 单元格导入后返回 null。
• date 列导入后返回格式化字符串。
• 非法或不完整的 schema 会在读取工作簿前立即失败。
• 浏览器上传会在读取前按 maxFileSizeBytes 校验文件大小（默认 25 MiB）。
• 无 schema 导入时，可使用 importExcelDynamic(...)（浏览器上传）或 fromExcelDynamic(...)（字节缓冲）。

导出行为

• null 和 undefined 会导出为空单元格。
• 数字列会拒绝非有限值。
• 日期列支持 Date 实例或日期字符串。
• 文本列默认会转义看起来像公式的值；如需导出公式，可设置 escapeFormulas: false。
• 分组导出对象必须使用 { value?, children: [...] } 结构。
• 图片列必须提供 imageFetcher。

已支持的高级能力

以下高级能力已纳入公开 API：

• 合并标题行
• 冻结表头
• 列备注
• 下拉候选值
• 条件 valueFormat
• 使用 dataGroup / dataGroupParent 的嵌套分组导出
• 通过 imageFetcher 导出图片

浏览器 / 运行时支持

• 主要面向浏览器 ESM 运行时。
• downloadExcelTemplate、exportExcel、importExcel、importExcelDynamic 依赖 DOM / 浏览器 API。
• 当运行时提供兼容的浏览器全局对象时，也可以使用 fromExcel、fromExcelDynamic、toExcel、generateExcelTemplate。
• core 包会在首次执行工作簿操作前，异步初始化构建产物中的内置 WASM 资源。

示例

• 基础浏览器示例
• 分组导出示例
• Definition 校验示例

这些示例由 ./tests/import-export.spec.ts 中的 Playwright 用例覆盖。

已知限制

• 父级表头和数据分组必须先于依赖它们的列声明。
• date 导入结果会规范化为字符串，而不是 Date 实例。
• 当前一次只校验一个工作表。