使用 exceljs 实现带样式和多 Sheet 的 Excel 导出

作者:慢半拍时间:2026-11-21 14:13:51浏览:503

本文系统讲解如何使用 exceljs 实现多工作表与单元格样式的 Excel 导出,涵盖 Workbook 对象模型、多 Sheet 视图配置、字体与背景填充、边框与数字格式化、自适应列宽计算,以及在 Node.js 服务端与浏览器前端的完整工程实现。

在 Web 业务系统与数据报表场景中,单纯的 CSV 格式无法保留单元格背景、自定义字体、边框样式以及多工作表(Multi-Sheet)的数据聚合结构。基于 ExcelJS 库,开发者能够以清晰的对象化方式在 Node.js 服务端或前端浏览器中构建符合商业交付标准的 .xlsx 文档。本文将从对象模型切入,分步讲解多工作表创建、样式体系装配、自适应列宽算法以及双端导出的完整工程实践。
使用 exceljs 实现带样式和多 Sheet 的 Excel 导出
图 0:ExcelJS 多工作表管理与单元格样式体系总览

一、ExcelJS 核心依赖与对象层次结构

在进入具体的样式与工作表配置前,必须先理清 ExcelJS 的物理对象模型。ExcelJS 遵循标准的 OpenXML 文档规范,将电子表格抽象为四个层级:Workbook(工作簿)、Worksheet(工作表)、Row / Column(行与列) 以及 Cell(单元格)。

使用 exceljs 实现带样式和多 Sheet 的 Excel 导出
图 1:ExcelJS 核心对象层级与样式承载关系架构图

在项目的根目录下通过 npm 或 yarn 安装依赖:

npm install exceljs

在代码中实例化工作簿后,所有的数据填充与样式挂载都建立在层级向下传递的基础之上:

import ExcelJS from 'exceljs';

// 初始化工作簿实例
const workbook = new ExcelJS.Workbook();

// 建议配置基本元数据,方便在 Office 属性中追溯文档来源
workbook.creator = '财务运营中台';
workbook.lastModifiedBy = '自动导出作业';
workbook.created = new Date();
workbook.modified = new Date();

需要明确的是,ExcelJS 的样式属性是直接依附在 Cell 实体上的。虽然可以在 Row 或 Column 上设置样式快捷方式,但当行数据生成时,底层的底层渲染仍会转化为每个具体单元格的样式属性。因此,若需要确保样式在每个单元格(特别是空单元格或合并区域)稳定生效,直接针对目标单元格或遍历行内单元格(row.eachCell)赋值是最可靠的做法。

二、多工作表(Multi-Sheet)的创建与视图定制

导出复杂业务报表时,通常需要将不同维度的数据拆分至独立的工作表中。例如,第一张表呈现“经营总览数据”,第二张表记录“详细交易流水”。

1. 添加独立工作表并设置标签主题色

通过 workbook.addWorksheet(name, options) 可以挂载新的工作表。参数中支持设置 properties.tabColor,为工作表标签设置醒目的指示色彩:

// 创建汇总工作表,标签色设置为砖红色
const summarySheet = workbook.addWorksheet('销售总览', {
  properties: {
    tabColor: { argb: 'FFB96555' }
  }
});

// 创建明细工作表,标签色设置为深炭灰
const detailSheet = workbook.addWorksheet('订单流水明细', {
  properties: {
    tabColor: { argb: 'FF30363C' }
  }
});

2. 视图偏好设置:显示网格线与冻结首行

在部分 Excel 软件中,自定义了背景填充的单元格可能会导致默认的浅灰网格线不可见。为了确保报表的可读性,建议在 views 中显式声明 showGridLines: true,并使用 state: 'frozen' 冻结表头首行,使读者在向下滚动数千行明细时依然能看清对应列头:

// 针对明细表配置首行冻结与网格线常显
detailSheet.views = [
  {
    state: 'frozen',
    xSplit: 0,
    ySplit: 1, // 冻结首行
    activeCell: 'A2',
    showGridLines: true
  }
];

三、列元定义与智能自适应列宽算法

通过配置工作表的 columns 属性,可以一次性确立数据键名(key)、表头显示文本(header)以及预设宽度(width)。

summarySheet.columns = [
  { header: '业务部门', key: 'dept', width: 18 },
  { header: '季度销售总额 (元)', key: 'amount', width: 22 },
  { header: '目标达成率', key: 'completionRate', width: 16 },
  { header: '同比增长率', key: 'growthRate', width: 16 },
  { header: '统计基准日', key: 'statDate', width: 16 }
];

自适应列宽计算函数

固定列宽在遇到长度未知的动态文本(如长公司名、UUID、备注)时,容易出现文本被遮挡或单元格过宽留白的问题。中文字符在渲染时占用的物理宽度通常是英文字符与数字的 1.8 至 2 倍。可以通过以下实用函数,在数据填充完毕后根据内容动态修正列宽:

/**
 * 自动计算并调整 Worksheet 各列宽度
 * @param {ExcelJS.Worksheet} worksheet 
 * @param {number} minWidth 最小列宽
 * @param {number} padding 缓冲字符量
 */
function autoFitColumnWidths(worksheet, minWidth = 12, padding = 4) {
  worksheet.columns.forEach((column) => {
    let maxLength = 0;
    if (column.header) {
      maxLength = String(column.header).length * 2; // 中文表头加权
    }
    
    // 遍历当前列的所有单元格(跳过空值)
    column.eachCell({ includeEmpty: false }, (cell) => {
      const val = cell.value ? String(cell.value) : '';
      // 计算字符真实显示长度:双字节字符计 2,单字节字符计 1
      let cellLen = 0;
      for (let i = 0; i < val.length; i++) {
        cellLen += val.charCodeAt(i) > 255 ? 2 : 1;
      }
      if (cellLen > maxLength) {
        maxLength = cellLen;
      }
    });

    // 设置计算后的列宽,并保留安全边距
    column.width = Math.max(minWidth, Math.ceil(maxLength + padding));
  });
}

四、单元格样式系统深度定制

ExcelJS 具备完善的样式控制能力。所有与视觉相关的设置归整在 font、fill、alignment、border 以及 numFmt 这五个关键属性中。

使用 exceljs 实现带样式和多 Sheet 的 Excel 导出
图 2:ExcelJS 样式系统核心 API 配置对照规范

1. 字体配置(Font)与 ARGB 颜色规范

Excel 内部采用 ARGB(Alpha, Red, Green, Blue) 格式表示颜色,由 8 位十六进制字符组成。注意:不能带有前导的 # 符号。例如,白色为 FFFFFFFF,炭灰色 #30363C 对应的 ARGB 为 FF30363C,砖红色 #B96555 对应为 FFB96555。

cell.font = {
  name: 'Microsoft YaHei', // 首选字体名称
  size: 11,                // 字体大小 (pt)
  bold: true,              // 是否加粗
  color: { argb: 'FFFFFFFF' } // 白色字体
};

2. 背景填充(Fill)与斑马纹设计

最普遍的纯色背景需要声明 type: 'pattern' 与 pattern: 'solid',并将目标颜色赋值给 fgColor:

// 设置表头深色底色
headerRow.eachCell((cell) => {
  cell.fill = {
    type: 'pattern',
    pattern: 'solid',
    fgColor: { argb: 'FF30363C' } // 炭灰背景
  };
});

3. 文本对齐与自动折行(Alignment)

建议将数值列靠右对齐(方便核对小数点),文本列靠左对齐,枚举状态或短代码居中对齐,同时在首行统一设置垂直居中:

cell.alignment = {
  vertical: 'middle',
  horizontal: 'center',
  wrapText: true // 内容超出时在单元格内自动折行
};

4. 边框线型规范(Border)

边框对象可分别指定 top、bottom、left、right 四个方位,线型支持 thin(细实线)、medium(中实线)、dashed(虚线)或 double(双底线):

const thinBorder = {
  top: { style: 'thin', color: { argb: 'FFE2DEC9' } },
  bottom: { style: 'thin', color: { argb: 'FFE2DEC9' } },
  left: { style: 'thin', color: { argb: 'FFE2DEC9' } },
  right: { style: 'thin', color: { argb: 'FFE2DEC9' } }
};

cell.border = thinBorder;

5. 原生数字与货币格式化(numFmt)

常见开发误区是将金额和百分比在 JavaScript 代码中直接格式化为字符串(如 "¥ 1,200.00" 或 "85.2%")后再写入单元格。这样会导致 Excel 无法对这批数据进行公式求和或二次统计。正确的做法是将单元格值保持为纯 Number,并通过 numFmt 指定展示格式:

// 金额千分位并保留两位小数
amountCell.value = 1485200.5;
amountCell.numFmt = '#,##0.00'; // Excel 中展示为 1,485,200.50

// 百分比格式化
rateCell.value = 0.8542;
rateCell.numFmt = '0.00%'; // Excel 中展示为 85.42%

// 标准日期格式
dateCell.value = new Date();
dateCell.numFmt = 'yyyy-mm-dd';

五、端到端完整实施流程与代码实战

导出流程可以分为五个阶段:初始化工作簿、添加多工作表、声明列与样式基线、逐行填充并美化数据、最后进行序列化输出。

使用 exceljs 实现带样式和多 Sheet 的 Excel 导出
图 3:ExcelJS 导出全流程流水线

以下提供了一份完整的、自包含的多 Sheet 导出脚本,同时演示了表头美化、交替斑马纹、数字格式化以及合计行样式的组合实现:

import ExcelJS from 'exceljs';

export async function buildBusinessReport() {
  const workbook = new ExcelJS.Workbook();
  workbook.creator = '数据中台系统';
  workbook.created = new Date();

  // -------------------------------------------------------------
  // Sheet 1: 销售业绩汇总
  // -------------------------------------------------------------
  const summarySheet = workbook.addWorksheet('销售业绩汇总', {
    properties: { tabColor: { argb: 'FFB96555' } },
    views: [{ showGridLines: true }]
  });

  // 1. 设置列定义
  summarySheet.columns = [
    { header: '业务部门', key: 'dept', width: 20 },
    { header: '季度销售总额 (元)', key: 'amount', width: 22 },
    { header: '目标达成率', key: 'rate', width: 16 },
    { header: '统计日期', key: 'date', width: 18 }
  ];

  // 2. 润色表头行样式
  const headerRow1 = summarySheet.getRow(1);
  headerRow1.height = 32;
  headerRow1.eachCell((cell) => {
    cell.font = { name: 'Microsoft YaHei', size: 11, bold: true, color: { argb: 'FFFFFFFF' } };
    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FF30363C' } };
    cell.alignment = { vertical: 'middle', horizontal: 'center' };
    cell.border = {
      bottom: { style: 'medium', color: { argb: 'FFB96555' } }
    };
  });

  // 3. 注入数据行并应用交替斑马纹
  const summaryData = [
    { dept: '华东企业服务部', amount: 1485200, rate: 1.185, date: '2026-03-31' },
    { dept: '华北智能制造组', amount: 986400,  rate: 0.942, date: '2026-03-31' },
    { dept: '华南海外业务组', amount: 2120800, rate: 1.326, date: '2026-03-31' }
  ];

  summaryData.forEach((item, index) => {
    const row = summarySheet.addRow(item);
    row.height = 24;

    // 奇偶行斑马纹背景
    const isOdd = index % 2 === 1;
    const rowBg = isOdd ? 'FFFAF9F5' : 'FFFFFFFF';

    row.eachCell((cell, colNumber) => {
      cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: rowBg } };
      cell.border = {
        top: { style: 'thin', color: { argb: 'FFE2DEC9' } },
        bottom: { style: 'thin', color: { argb: 'FFE2DEC9' } }
      };
      cell.alignment = { vertical: 'middle', horizontal: 'left' };

      // 针对第 2 列销售额做金额格式化
      if (colNumber === 2) {
        cell.numFmt = '¥ #,##0.00';
        cell.alignment = { vertical: 'middle', horizontal: 'right' };
      }
      // 针对第 3 列达成率做百分比格式化
      if (colNumber === 3) {
        cell.numFmt = '0.00%';
        cell.alignment = { vertical: 'middle', horizontal: 'right' };
      }
    });
  });

  // 4. 追加合计行
  const totalRow = summarySheet.addRow({
    dept: '总计',
    amount: { formula: 'SUM(B2:B4)' },
    rate: { formula: 'AVERAGE(C2:C4)' },
    date: '-'
  });
  totalRow.height = 26;
  totalRow.eachCell((cell, colNumber) => {
    cell.font = { name: 'Microsoft YaHei', size: 11, bold: true, color: { argb: 'FFB96555' } };
    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFF5ECE8' } };
    cell.border = {
      top: { style: 'medium', color: { argb: 'FFB96555' } },
      bottom: { style: 'double', color: { argb: 'FFB96555' } }
    };
    if (colNumber === 2) {
      cell.numFmt = '¥ #,##0.00';
      cell.alignment = { vertical: 'middle', horizontal: 'right' };
    }
    if (colNumber === 3) {
      cell.numFmt = '0.00%';
      cell.alignment = { vertical: 'middle', horizontal: 'right' };
    }
  });

  // -------------------------------------------------------------
  // Sheet 2: 订单流水明细 (多工作表形态)
  // -------------------------------------------------------------
  const detailSheet = workbook.addWorksheet('订单流水明细', {
    properties: { tabColor: { argb: 'FF30363C' } },
    views: [{ state: 'frozen', ySplit: 1, showGridLines: true }]
  });

  detailSheet.columns = [
    { header: '订单流水编号', key: 'orderNo', width: 24 },
    { header: '客户主体全称', key: 'client', width: 28 },
    { header: '成交金额 (元)', key: 'price', width: 18 },
    { header: '支付渠道', key: 'channel', width: 14 },
    { header: '下单时间', key: 'createTime', width: 22 }
  ];

  // 美化明细表头
  const headerRow2 = detailSheet.getRow(1);
  headerRow2.height = 30;
  headerRow2.eachCell((cell) => {
    cell.font = { name: 'Microsoft YaHei', size: 10.5, bold: true, color: { argb: 'FFFFFFFF' } };
    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FF4D555E' } };
    cell.alignment = { vertical: 'middle', horizontal: 'center' };
  });

  // 填充明细演示数据
  const details = [
    { orderNo: 'ORD-20260331-001', client: '上海远航信息科技发展有限公司', price: 450000, channel: '公对公汇款', createTime: '2026-03-31 09:22:15' },
    { orderNo: 'ORD-20260331-002', client: '北京恒峰智能物流股份有限公司', price: 186000, channel: '企业网银',   createTime: '2026-03-31 10:45:00' },
    { orderNo: 'ORD-20260331-003', client: '深圳星河微电子技术研究所',   price: 849200, channel: '国际电汇',   createTime: '2026-03-31 14:10:32' }
  ];

  details.forEach((item) => {
    const r = detailSheet.addRow(item);
    r.height = 22;
    r.getCell('price').numFmt = '#,##0.00';
    r.getCell('price').alignment = { horizontal: 'right', vertical: 'middle' };
    r.getCell('channel').alignment = { horizontal: 'center', vertical: 'middle' };
  });

  // 应用列宽自动适配
  autoFitColumnWidths(summarySheet);
  autoFitColumnWidths(detailSheet);

  return workbook;
}

六、Node.js 服务端与浏览器前端的导出落地

完成工作簿构建后,针对 Node.js 后端与浏览器单页应用(SPA),其交付方式有所不同。

使用 exceljs 实现带样式和多 Sheet 的 Excel 导出
图 4:Node.js 与浏览器端导出方案决策树

1. Node.js 服务端返回响应流

在基于 Express 或 Koa 的 Web 服务中,最简便的方法是通过 workbook.xlsx.writeBuffer() 生成内存 Buffer,并设置标准的 HTTP 下载响应头:

import express from 'express';
const app = express();

app.get('/api/export/report', async (req, res) => {
  try {
    const workbook = await buildBusinessReport();

    // 声明 xlsx 专用的 MIME 类型
    res.setHeader(
      'Content-Type',
      'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
    );
    // 处理中文文件名的 URL 编码
    const fileName = encodeURIComponent('2026季度经营与流水报表.xlsx');
    res.setHeader('Content-Disposition', `attachment; filename="${fileName}"`);

    // 写入响应体
    const buffer = await workbook.xlsx.writeBuffer();
    res.send(buffer);
  } catch (error) {
    res.status(500).send('导出报表失败');
  }
});

海量数据流式写入注意点:

当单次导出的明细数据超过 10 万行时,全部驻留在内存中的 Workbook 对象会导致 Node.js 进程内存激增。此时推荐使用 ExcelJS.stream.xlsx.WorkbookWriter:

const workbook = new ExcelJS.stream.xlsx.WorkbookWriter({ stream: res });
const sheet = workbook.addWorksheet('海量明细');
// 每写入一行调用一次 row.commit(),将数据刷入磁盘或网络,维持内存低水位
row.commit();
await workbook.commit();

2. 浏览器端单页应用直接触发下载

在 Vue 或 React 项目中,无需后端中转即可在浏览器内存中直接生成文件。核心步骤是将 writeBuffer() 得到的 ArrayBuffer 封装为 Blob,并通过 URL.createObjectURL 触发模拟点击:

export async function downloadReportInBrowser() {
  const workbook = await buildBusinessReport();

  // 1. 生成 ArrayBuffer
  const buffer = await workbook.xlsx.writeBuffer();

  // 2. 包装为 Blob 实体
  const blob = new Blob([buffer], {
    type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
  });

  // 3. 创建临时 ObjectURL 触发原生下载
  const downloadUrl = window.URL.createObjectURL(blob);
  const link = document.createElement('a');
  link.href = downloadUrl;
  link.download = '2026季度经营与流水报表.xlsx';
  document.body.appendChild(link);
  link.click();

  // 4. 释放 URL 内存引用
  document.body.removeChild(link);
  window.URL.revokeObjectURL(downloadUrl);
}

七、生产环境核心避坑指南

在将基于 ExcelJS 的导出模块接入生产系统时,以下三项经验能够避免常见的样式与解析异常:

常见问题表现 诱发原因 标准解决与排查方案
导出的单元格背景变黑或样式失效 将十六进制颜色直接写为了 CSS 格式(如 #B96555),或者写成了 6 位 Hex 必须使用 8 位 ARGB 字符串,且严禁添加 # 前缀,如 FFB96555(前两位 FF 代表不透明度 100%)。
数值列在 Excel 中左上角出现绿三角警告 传入的值为格式化后的 String,导致 Excel 将其视作存为文本的数字 保持原始 cell.value 为纯 Number 类型,格式化统一通过 cell.numFmt = '#,##0.00' 或 0.00% 处理。
流式导出(Stream)生成的 Excel 文件损坏或无法打开 未显式调用 row.commit() 或在末尾遗漏了 await workbook.commit() WorkbookWriter 依赖 commit 推进 XML 片段的闭合与压缩打包,必须在数据循环完毕后完整调用 commit。

通过掌握对象层级流向、合理分离工作表与视图、严格规范 ARGB 与数字格式,再结合动态列宽计算,即可利用 ExcelJS 在企业级 Web 架构中稳定、高质量地交付各类复杂的 Excel 报表。

作者最新文章
相关文章
更多