DexSimpleReportExcel

基于 xlsx-js-style 的高级 Excel 导出工具，支持多工作表、多级表头、行/列合并、样式配置、序号列、图片链接等功能。

功能特性

• 多工作表导出：支持一次性导出多个 Sheet。
• 复杂表头：支持多级表头（通过 columns 嵌套配置）。
• 智能合并：
  • 支持按列值自动合并行（mergeOptions）。
  • 支持自定义合并策略（正则、自定义函数）。
• 样式定制：
  • 全局/特定样式配置（标题、表头、正文）。
  • 支持字体、颜色、对齐、边框等设置。
• 图片支持：自动识别图片 URL 并转换为“查看图片”链接。
• 序号列：支持自动生成序号列，并与合并行对齐。

安装

npm install dex-simple-report-excel

快速开始

Node.js (ES Module)

import { ExcelExporter } from 'dex-simple-report-excel';

// 1. 定义数据
const data = [
  { dept: '研发部', name: '张三', role: '前端', budget: 10000 },
  { dept: '研发部', name: '李四', role: '后端', budget: 12000 },
  { dept: '市场部', name: '王五', role: '销售', budget: 8000 },
  { dept: '市场部', name: '赵六', role: '推广', budget: 9000 }
];

// 2. 定义列结构
const columns = [
  { header: '部门', prop: 'dept', mergeable: true }, // 开启合并
  { header: '姓名', prop: 'name' },
  { header: '职位', prop: 'role' },
  { header: '预算', prop: 'budget' }
];

// 3. 导出
ExcelExporter.exportExcel({
  fileName: '部门预算表.xlsx',
  sheets: [
    {
      sheetName: 'Q1预算',
      title: '2024年第一季度部门预算表', // 表格大标题
      columns: columns,
      data: data,
      mergeOptions: {
        mergeKey: 'dept', // 按部门合并
        serialNumberColumn: true // 开启序号列
      }
    }
  ],
  styleOptions: {
    title: { fontSize: 20, bold: true, colorRgb: '4472C4' },
    header: { fontSize: 14, bold: true, horizontal: 'center' }
  }
});

API 详细说明

核心方法

ExcelExporter.exportExcel(options)

同步导出 Excel 文件。适用于中小规模数据量。

ExcelExporter.exportExcelAsync(options)

异步导出 Excel 文件。适用于大数据量，内部采用分块处理以避免阻塞主线程。

配置对象说明

1. ExportOptions (顶层配置)

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | sheets | SheetOptions[] | [] | 必填，工作表配置数组 | | fileName | string | '导出数据.xlsx' | 导出文件名 | | styleOptions | StyleOptions | {} | 全局样式简易配置（推荐） | | defaultStyles | DefaultStyles | {} | 底层样式对象直接配置（高级） | | showBorder | boolean | true | 是否显示单元格边框 |

2. SheetOptions (工作表配置)

| 属性 | 类型 | 说明 | | --- | --- | --- | | sheetName | string | 工作表名称（默认 Sheet1） | | title | string | 表格大标题，置于首行并整行合并 | | columns | ColumnNode[] | 必填，列定义（支持嵌套实现多级表头） | | data | Object[] | 必填，数据源数组 | | mergeOptions | MergeOptions | 行合并配置 | | customOptions | CustomOptions | 高级自定义选项（如行高、列宽等） |

3. ColumnNode (列定义)

| 属性 | 类型 | 说明 | | --- | --- | --- | | header | string | 表头显示文字 | | prop | string | 数据字段名 | | children | ColumnNode[] | 子表头数组（用于多级表头） | | mergeable | boolean | 是否允许该列参与行合并（需配合 mergeOptions 使用） | | hidden | boolean | 是否隐藏该列（隐藏列仍可作为 mergeKey 使用） | | cellType | 'text' \| 'image' | 单元格类型。image 会将 URL 转换为“查看图片”链接 | | width | number | 列宽（字符数） |

4. MergeOptions (合并配置)

用于控制行合并行为（例如：相同部门的行合并在一起）。

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | mergeKey | string | - | 必填，主要合并依据的字段名 | | rowMerge | boolean | true | 是否开启行合并功能 | | mergeNull | boolean | false | 是否合并空值（null/undefined） | | excludeColumns | string[] | [] | 排除参与合并的列名数组 | | childrenStrict | boolean | false | 子级合并是否严格依赖父级（通常用于多级合并） | | mergeChildrenByDefault | boolean | false | 是否默认合并所有子列（无需显式设 mergeable） | | mergeStrategy | 'auto' \| 'regex' \| 'custom' | 'auto' | 合并策略 | | regex | RegExp \| string | - | 正则表达式（当 strategy='regex' 时使用） | | customComparator | Function | - | 自定义比较函数（当 strategy='custom' 时使用） | | serialNumberColumn | boolean | false | 是否开启最左侧序号列 | | serialNumberHeader | string | '序号' | 序号列表头名称 | | serialNumberStartAt | number | 1 | 序号起始值 |

5. StyleOptions (样式配置)

用于快速调整表格各部分的视觉样式。

| 属性 | 类型 | 说明 | | --- | --- | --- | | title | StyleTuning | 标题行样式 | | header | StyleTuning | 表头行样式 | | body | StyleTuning | 正文数据行样式 |

StyleTuning 对象属性：

• fontName: 字体名称（如 "宋体"）
• fontSize: 字体大小
• bold: 是否加粗 (boolean)
• colorRgb: 字体颜色 (Hex, 如 "FF0000")
• horizontal: 水平对齐 ('left', 'center', 'right')
• vertical: 垂直对齐 ('top', 'center', 'bottom')
• wrapText: 是否自动换行 (boolean)

6. CustomOptions (高级选项)

| 属性 | 类型 | 说明 | | --- | --- | --- | | rowHeights | Object | 行高配置 { title: 30, header: 25, dataDefault: 20 } | | cols | Array | 手动指定列宽配置 [{ wch: 20 }, { wch: 10 }] |

场景示例

1. 基础多级表头与合并

const columns = [
  { header: '项目编号', prop: 'id', hidden: true }, // 隐藏列，用作合并主键
  { 
    header: '项目基本信息',
    children: [
      { header: '项目名称', prop: 'name', mergeable: true },
      { header: '负责人', prop: 'owner' }
    ]
  },
  {
    header: '进度详情',
    children: [
      { header: '阶段', prop: 'phase', mergeable: true },
      { header: '完成度', prop: 'percent' }
    ]
  }
];

const data = [
  { id: 1, name: '项目A', owner: 'Alice', phase: '设计', percent: '100%' },
  { id: 1, name: '项目A', owner: 'Alice', phase: '开发', percent: '50%' },
  { id: 2, name: '项目B', owner: 'Bob', phase: '测试', percent: '20%' }
];

ExcelExporter.exportExcel({
  sheets: [{
    sheetName: '多级表头示例',
    columns,
    data,
    mergeOptions: {
      mergeKey: 'id', // 按 id 合并
      serialNumberColumn: true // 自动生成序号
    }
  }]
});

2. 自定义合并策略

支持三种合并策略：

• 'auto': 全等比较（默认）。
• 'regex': 正则匹配（例如忽略大小写）。
• 'custom': 完全自定义函数。

// 示例：忽略大小写和连字符的合并
const customComparator = (a, b) => {
  const normalize = str => String(str).replace(/-/g, '').toLowerCase();
  return normalize(a) === normalize(b);
};

ExcelExporter.exportExcel({
  sheets: [{
    sheetName: '自定义合并',
    columns: [{ header: '代码', prop: 'code', mergeable: true }, { header: '值', prop: 'value' }],
    data: [
      { code: 'ABC-01', value: 10 },
      { code: 'abc01', value: 20 }, // 将与上一行合并
      { code: 'XYZ-99', value: 30 }
    ],
    mergeOptions: {
      mergeKey: 'code',
      mergeStrategy: 'custom',
      customComparator: customComparator
    }
  }]
});

3. 图片与样式定制

ExcelExporter.exportExcel({
  fileName: '图片与样式.xlsx',
  styleOptions: {
    // 标题样式：大号蓝色字
    title: { fontSize: 24, bold: true, colorRgb: '0000FF' },
    // 表头样式：黄色背景（需通过 defaultStyles 深入配置，此处仅演示字体）
    header: { fontSize: 14, bold: true },
    // 正文样式：左对齐
    body: { horizontal: 'left' }
  },
  sheets: [{
    sheetName: '产品图册',
    title: '2024新品展示',
    columns: [
      { header: '产品名称', prop: 'name' },
      { header: '产品图片', prop: 'imgUrl', cellType: 'image' } // 自动转为链接
    ],
    data: [
      { name: '运动鞋', imgUrl: 'https://example.com/shoe.jpg' },
      { name: 'T恤', imgUrl: 'not-a-url' } // 非URL保持原样
    ],
    // 自定义行高
    customOptions: {
      rowHeights: {
        title: 40,
        header: 30,
        dataDefault: 50 // 数据行高一点以便展示
      }
    }
  }]
});

注意事项

1. 图片导出：目前仅支持将图片 URL 导出为“查看图片”的超链接文本，不支持直接嵌入图片文件（受限于底层库）。
2. 序号列：启用 serialNumberColumn 时，序号是基于 mergeKey 的分段生成的，并且会与左侧合并行对齐。
3. 大数据量：对于超过几千行的数据，建议使用 exportExcelAsync，以避免浏览器或 Node.js 进程假死。
4. 边框：默认情况下，合并单元格的边框会自动补齐，无需手动处理。

License

MIT