📦 @sparta-utils/excel-exporter

一个开箱即用、支持样式控制、合并单元格、多表头、模板样式克隆的 TypeScript Excel 导出工具库，基于 ExcelJS。

✨ 特性亮点

• ✅ 支持多级表头配置（支持合并单元格）
• 🧩 表头支持动态样式、行高、对齐、字体等配置
• 🗒️ 支持说明行配置（例如：导入说明、注意事项）
• 🎨 内置样式工具，支持字体、颜色、边框、填充、对齐等
• 🔗 支持单元格合并（自动或自定义）
• 🔽 下拉选项配置
• 🧠 列格式化函数（日期、枚举、金额等）
• 🧬 支持从模板复制样式（支持中）
• 📤 支持导出为 Blob 或直接下载

📦 安装

npm install @sparta-utils/excel-exporter

🚀 快速示例：多表头 + 说明行 + 样式控制

import { exportAndDownloadExcel, formatters } from '@sparta-utils/excel-exporter';

await exportAndDownloadExcel({
  fileName: '预设计检波点导入模板.xlsx',
  sheetName: 'Sheet1',
  title: {
    label: '预设计检波点数据导入模板',
    height: 30,
    style: {
      font: { size: 18, bold: true },
      alignment: { vertical: 'middle', horizontal: 'center' },
    },
  },
  description: {
    label: `注意事项：
1、红色为必填项目
2、表格导入坐标均为平面坐标
3、请勿修改表格的格式`,
    height: 40,
    style: {
      font: { size: 12, color: { argb: 'FFFF0000' } },
      alignment: { vertical: 'top', horizontal: 'left', wrapText: true },
    },
  },
  columns: [
    [
      { title: '线路号', key: 'lineNo', required: true },
      { title: '炮点号', key: 'shotPointNo', required: true },
      { title: 'X坐标', key: 'x', required: true },
      { title: 'Y坐标', key: 'y', required: true },
    ],
    [
      { title: 'Z坐标', key: 'z' },
      { title: '备注', key: 'remark' },
    ],
  ],
  data: [
    { lineNo: 'A', shotPointNo: '001', x: 100, y: 200, z: 300, remark: '无' },
    { lineNo: 'B', shotPointNo: '002', x: 110, y: 210, z: 310, remark: '测试' },
  ],
  rowHeight: 20, // 数据行固定高度
});

🧩 API 说明

exportAndDownloadExcel(params: ExcelExportParams & { fileName: string }) 导出并直接下载 Excel 文件。

ExcelExportParams

interface ExcelExportParams {
  fileName: string;
  sheetName: string;

  // 标题行（支持样式、合并）
  title?: {
    label: string;
    height?: number;
    style?: Partial<Excel.Style>;
  };

  // 描述行（支持换行、样式）
  description?: {
    label: string;
    height?: number;
    style?: Partial<Excel.Style>;
  };

  // 多表头支持（二维数组）
  columns: Array<Array<{
    key: string;
    title: string;
    dropdown?: string[];
    formatter?: (val: any, row: any, rowIndex: number) => any;
    required?: boolean;
    width?: number;
    style?: Partial<Excel.Style>;
  }>>;

  // 数据内容
  data: any[];

  // 合并配置（可选）
  merges?: string[];

  // 样式模板克隆（可选）
  cloneFromTemplate?: Excel.Workbook;

  // 默认数据行高
  rowHeight?: number;
}

🎨 样式控制

使用 StyleManager 快速应用内置样式或自定义样式。

import { StyleManager } from '@sparta-utils/excel-exporter';

// 应用默认表头样式
StyleManager.applyStyle(cell, StyleManager.defaultHeaderStyle);

你也可以自定义字体、对齐、边框、颜色等：

cell.style = {
  font: { size: 12, bold: true },
  alignment: { horizontal: 'center', vertical: 'middle' },
  border: { top: { style: 'thin' }, bottom: { style: 'thin' } },
};

🧠 格式化函数

import { formatters } from '@sparta-utils/excel-exporter';

formatter: formatters.date('yyyy-MM-dd')
formatter: formatters.currency('¥')
formatter: formatters.percent(2)
formatter: formatters.enum({ 1: '启用', 0: '禁用' })