使用 exceljs 实现带样式和多 Sheet 的 Excel 导出
本文系统讲解如何使用 exceljs 实现多工作表与单元格样式的 Excel 导出,涵盖 Workbook 对象模型、多 Sheet 视图配置、字体与背景填充、边框与数字格式化、自适应列宽计算,以及在 Node.js 服务端与浏览器前端的完整工程实现。
.xlsx 文档。本文将从对象模型切入,分步讲解多工作表创建、样式体系装配、自适应列宽算法以及双端导出的完整工程实践。
一、ExcelJS 核心依赖与对象层次结构
在进入具体的样式与工作表配置前,必须先理清 ExcelJS 的物理对象模型。ExcelJS 遵循标准的 OpenXML 文档规范,将电子表格抽象为四个层级:Workbook(工作簿)、Worksheet(工作表)、Row / Column(行与列) 以及 Cell(单元格)。
在项目的根目录下通过 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 这五个关键属性中。
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';
五、端到端完整实施流程与代码实战
导出流程可以分为五个阶段:初始化工作簿、添加多工作表、声明列与样式基线、逐行填充并美化数据、最后进行序列化输出。
以下提供了一份完整的、自包含的多 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),其交付方式有所不同。
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 报表。
JS优化超大JSON文件解析性能的策略
2026-11-21 10:28:25
Node.js使用child_process调用本地exe程序
2026-11-21 09:54:48
怎么批量将项目中的JS文件编码统一转换为UTF-8
2026-11-20 10:56:24
JavaScript 局域网聊天怎么实现用户自动发现
2026-11-18 12:19:49
Node.js环境中怎么输出变量
2026-11-18 08:26:24








