multi-header-xlsx

一个强大的 Excel 导出工具库，支持多表头、自定义样式和自定义文件名导出。

✨ 特性

• ✅ 支持单表头和多级表头（无限层级嵌套）
• ✅ 列宽自动适应（智能计算中英文混合内容宽度）
• ✅ 自定义对齐方式（左对齐、居中、右对齐）
• ✅ 丰富的样式自定义（表头、数据行、标题、表尾样式）
• ✅ 标题、副标题、表尾支持（自动分布对齐）
• ✅ 行级和单元格级样式（支持背景色、字体、边框等）
• ✅ 多 Sheet 导出（支持一次导出多个工作表）
• ✅ RGB/ARGB 颜色格式支持（自动转换颜色格式）
• ✅ 自定义文件名和工作表名称
• ✅ 跨平台支持（浏览器和 Node.js 环境）
• ✅ TypeScript 类型支持（完整的类型定义）

📦 安装

npm install multi-header-xlsx

或使用 yarn：

yarn add multi-header-xlsx

版本 1.0.2 更新：修复了单个 sheet 导出时 title、subTitles、footer 等参数不生效的问题。

🚀 快速开始

基础用法

const { downloadExcel, saveExcel } = require('multi-header-xlsx');

// 定义列配置
const columns = [
  { dataIndex: 'name', title: '姓名', align: 'center' },
  { dataIndex: 'age', title: '年龄', align: 'center' },
  { dataIndex: 'address', title: '地址', align: 'left' }
];

// 数据源
const dataSource = [
  { name: '张三', age: 28, address: '北京市朝阳区' },
  { name: '李四', age: 32, address: '上海市浦东新区' },
  { name: '王五', age: 25, address: '广州市天河区' }
];

// 浏览器环境 - 下载文件
downloadExcel(columns, dataSource, {
  filename: '员工信息',
  sheetName: 'Sheet1'
});

// Node.js 环境 - 保存到文件
await saveExcel(columns, dataSource, './output.xlsx', {
  sheetName: '员工信息'
});

多表头导出

const columns = [
  { dataIndex: 'id', title: '序号', align: 'center' },
  { dataIndex: 'name', title: '姓名', align: 'center' },
  {
    title: '基本信息',
    children: [
      { dataIndex: 'gender', title: '性别', align: 'center' },
      { dataIndex: 'age', title: '年龄', align: 'center' },
      { dataIndex: 'phone', title: '电话', align: 'left' }
    ]
  },
  {
    title: '工作信息',
    children: [
      { dataIndex: 'department', title: '部门', align: 'center' },
      { dataIndex: 'position', title: '职位', align: 'center' }
    ]
  }
];

const dataSource = [
  { 
    id: 1, 
    name: '张三', 
    gender: '男', 
    age: 28, 
    phone: '13800138001', 
    department: '技术部', 
    position: '前端工程师' 
  }
];

downloadExcel(columns, dataSource, { filename: '员工花名册' });

三级表头

const columns = [
  { dataIndex: 'name', title: '姓名' },
  {
    title: '考核成绩',
    children: [
      {
        title: '第一季度',
        children: [
          { dataIndex: 'q1_work', title: '工作' },
          { dataIndex: 'q1_attitude', title: '态度' }
        ]
      },
      {
        title: '第二季度',
        children: [
          { dataIndex: 'q2_work', title: '工作' },
          { dataIndex: 'q2_attitude', title: '态度' }
        ]
      }
    ]
  },
  { dataIndex: 'total', title: '总分' }
];

自定义样式

downloadExcel(columns, dataSource, {
  filename: '自定义样式表',
  headerStyle: {
    font: { 
      bold: true, 
      size: 12, 
      color: { argb: 'FFFFFFFF' }  // 白色字体
    },
    fill: { 
      type: 'pattern', 
      pattern: 'solid', 
      fgColor: { argb: 'FF2E7D32' } // 绿色背景
    }
  },
  bodyStyle: {
    font: { size: 11 },
    alignment: { 
      vertical: 'middle',
      wrapText: true 
    }
  }
});

标题、副标题和表尾

downloadExcel(columns, dataSource, {
  filename: '报表',
  title: '2024年度员工报表',  // 主标题（居中显示）
  titleStyle: {
    font: { size: 24, bold: true }
  },
  subTitles: ['部门：技术部', '日期：2024-01-01'],  // 副标题（左右分布）
  footer: ['制表人：张三', '审核人：李四', '日期：2024-01-01']  // 表尾（左右分布）
});

行级样式

const dataSource = [
  { name: '张三', age: 28, address: '北京' },
  { 
    name: '李四', 
    age: 32, 
    address: '上海',
    __rowStyle: {  // 行级样式
      fill: {
        type: 'pattern',
        pattern: 'solid',
        fgColor: { argb: 'FFFFE0E0' }  // 浅红色背景
      }
    }
  }
];

单元格级样式

const dataSource = [
  { 
    name: '张三', 
    age: {  // 单元格对象，包含值和样式
      value: 28,
      style: {
        font: { color: { argb: 'FFFF0000' }, bold: true },  // 红色加粗
        fill: {
          type: 'pattern',
          pattern: 'solid',
          fgColor: { argb: 'FFFFFF00' }  // 黄色背景
        }
      }
    },
    address: '北京'
  }
];

多 Sheet 导出

downloadExcel(null, null, {
  filename: '多工作表',
  sheets: [
    {
      sheetName: '员工信息',
      columns: [
        { dataIndex: 'name', title: '姓名' },
        { dataIndex: 'age', title: '年龄' }
      ],
      dataSource: [
        { name: '张三', age: 28 },
        { name: '李四', age: 32 }
      ]
    },
    {
      sheetName: '部门信息',
      columns: [
        { dataIndex: 'dept', title: '部门' },
        { dataIndex: 'count', title: '人数' }
      ],
      dataSource: [
        { dept: '技术部', count: 50 },
        { dept: '销售部', count: 30 }
      ]
    }
  ]
});

获取 Excel 数据（不下载）

const { exportExcel } = require('multi-header-xlsx');

// 浏览器环境 - 返回 Blob
const blob = await exportExcel(columns, dataSource, { filename: 'test' });
// 可以用于上传到服务器或其他处理

// Node.js 环境 - 返回 Buffer
const buffer = await exportExcel(columns, dataSource, { filename: 'test' });
// 可以保存到文件或发送到其他服务

📚 API 文档

Column 列配置

| 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | dataIndex | string | 是 | 数据字段名 | | title | string | 是 | 列标题 | | width | string | number | 否 | 列宽度（已废弃，现使用内容自适应） | | align | 'left' | 'center' | 'right' | 否 | 对齐方式，默认 'left' | | children | Column[] | 否 | 子列配置（用于多表头） |

ExportOptions 导出选项

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | filename | string | 'export' | 导出文件名（不含扩展名） | | sheetName | string | 'Sheet1' | 工作表名称 | | headerStyle | CellStyle | - | 表头样式 | | bodyStyle | CellStyle | - | 数据行样式 | | sheets | SheetConfig[] | - | 多sheet配置，传入后columns/dataSource参数将被忽略 | | title | string | - | 标题（放在表头前，居中显示） | | titleStyle | CellStyle | - | 标题样式 | | subTitles | string[] | - | 副标题（同一行，左右分布显示） | | subTitleStyle | CellStyle | - | 副标题样式 | | footer | string[] | - | 表尾（同一行，左右分布显示） | | footerStyle | CellStyle | - | 表尾样式 |

CellStyle 样式配置

interface CellStyle {
  font?: {
    bold?: boolean;
    size?: number;
    color?: { argb: string };  // 支持 'FFFFFF' 或 'FFFFFFFF' 格式
    name?: string;
    italic?: boolean;
  };
  fill?: {
    type?: 'pattern' | 'gradient';
    pattern?: 'solid' | 'none';
    fgColor?: { argb: string };  // 前景色
    bgColor?: { argb: string };  // 背景色
  };
  border?: {
    top?: { style: string; color?: { argb: string } };
    left?: { style: string; color?: { argb: string } };
    bottom?: { style: string; color?: { argb: string } };
    right?: { style: string; color?: { argb: string } };
  };
  alignment?: {
    vertical?: 'top' | 'middle' | 'bottom';
    horizontal?: 'left' | 'center' | 'right';
    wrapText?: boolean;
  };
}

方法

exportExcel(columns, dataSource, options?)

导出 Excel 文件，返回 Blob（浏览器）或 Buffer（Node.js）。

参数：

• columns: Column[] - 列配置
• dataSource: RowData[] - 数据源
• options?: ExportOptions - 导出选项

返回： Promise<Blob | Buffer>

downloadExcel(columns, dataSource, options?)

导出并下载 Excel 文件（浏览器环境）。

参数：

• columns: Column[] - 列配置
• dataSource: RowData[] - 数据源
• options?: ExportOptions - 导出选项

返回： Promise<void>

saveExcel(columns, dataSource, filePath, options?)

导出 Excel 文件到指定路径（Node.js 环境）。

参数：

• columns: Column[] - 列配置
• dataSource: RowData[] - 数据源
• filePath: string - 文件路径
• options?: ExportOptions - 导出选项

返回： Promise<void>

辅助函数

getHeaderDepth(columns)

计算表头的层级深度。

参数： columns: Column[]

返回： number

getLeafColumns(columns)

获取所有叶子列（实际数据列）。

参数： columns: Column[]

返回： Column[]

getColSpan(column)

计算列的跨列数。

参数： column: Column

返回： number

🎨 样式优先级

样式应用优先级（从高到低）：

1. 单元格级样式（{ value: xxx, style: {...} }）
2. 行级样式（__rowStyle）
3. 全局 bodyStyle
4. 默认样式

💡 使用技巧

1. 颜色格式转换

库会自动将 6 位 RGB 格式（如 'FFFFFF'）转换为 8 位 ARGB 格式（如 'FFFFFFFF'）。你也可以直接使用 ARGB 格式。

2. 列宽自适应

列宽会根据内容自动调整，中文字符按 2 个字符宽度计算，英文按 1 个字符宽度计算。最小列宽为 10，最大列宽为 50。

3. 多表头合并

多表头会自动计算并合并单元格，支持无限层级嵌套。

4. 标题和表尾布局

• title: 单行文本，居中显示
• subTitles: 字符串数组，多个文本用空格分隔显示在同一行
• footer: 字符串数组，多个文本用空格分隔显示在同一行

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT

🔗 相关链接

• ExcelJS - 底层 Excel 操作库
• FileSaver.js - 文件保存工具