针对 JavaScript 导出 Excel 需求,通过 exceljs 库完整实现多工作表组织、表头定制、ARGB 背景颜色、网格边框、数字格式化以及浏览器端 Blob 一键下载。
JS 导出 Excel 带样式和多 Sheet 页:exceljs 实战指南
时间:2026-11-20
浏览:397
文章目录
在前端或 Node.js 环境生成报表时,原生 CSV 格式无法保留任何排版,而广泛使用的 SheetJS (xlsx) 社区开源版将单元格样式划入商业授权,难以满足企业级报表对字体、背景色、边框及冻结窗格的诉求。exceljs 是一款功能完整且采用 MIT 协议开源的 JavaScript 电子表格工具库,支持在浏览器端和服务端以一致的 API 构造多 Sheet 工作表,并对单元格进行像素级样式控制。本文将提供一套标准化实现流程,涵盖依赖选型、对象模型装配、细粒度样式定制、多 Sheet 独立视窗锁定以及二进制文件分流下载。
一、方案定位与技术选型差异
前端导出 Excel 文件常见的实现路径主要有三类:构造 Data URI 的纯 HTML Table 伪装导出、基于 SheetJS (xlsx) 社区版以及采用 exceljs。理解三者的能力边界有助于明确选用依据:
| 技术方案 | 样式控制能力 | 多 Sheet 支持 | 开源协议 / 限制 | 适用典型场景 |
|---|---|---|---|---|
| HTML Table / CSV 转存 | 无或仅靠内嵌 CSS(极不稳定) | 不支持 | 原生代码实现 | 轻量纯文本数据离线导出 |
| SheetJS (xlsx) 社区版 | 不支持(Pro 商业版专属) | 支持 | Apache-2.0 | 纯数据读写、无需格式排版的场景 |
| exceljs(本文方案) | 完整支持(ARGB 填充/字体/边框/对齐) | 完整支持(带标签染色与独立冻结) | MIT 开源免费 | 中大型管理系统、正式财务与业务交付报表 |
exceljs 严格基于 OpenXML 标准协议进行底层打包,生成的 .xlsx 文件可被 Microsoft Excel、WPS Office、Numbers 以及各类云文档软件无损解析。
二、开发准备与依赖引入
针对不同执行环境,exceljs 提供了对应的包分发形态。在工程化项目中,可以通过标准包管理器安装:
# 使用 npm 安装
npm install exceljs file-saver
# 或使用 yarn
yarn add exceljs file-saver
# 或使用 pnpm
pnpm add exceljs file-saver
在纯前端无需构建工具的静态 HTML 原型开发中,也可以直接通过 CDN 链接按需引入独立预编译包:
<!-- 浏览器端 CDN 快速引入 -->
<script src="https://cdn.jsdelivr.net/npm/exceljs/dist/exceljs.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/file-saver/dist/FileSaver.min.js"></script>
三、核心操作流程与导出流水线
构建一份具有格式规范的 Excel 报表应遵循清晰的生命周期:实例化顶层工作簿、装配多个工作表、定义列结构、遍历数据行注入样式,最后将内存对象转换为二进制流并交付用户。
将数据填充与样式绑定解耦是维护复杂表格的关键。先通过列定义(columns)确定字段标识与物理列的映射,再按行(addRow)填充业务数据,最后针对特定单元格或整行套用样式,可以保证代码的逻辑层次分明。
四、对象模型与配置层级关系
在调用 API 之前,理清 exceljs 内部对象的包含关系可以避免常见的属性挂载错误。
整个结构呈现严密的树状层级:
- Workbook:代表整个 Excel 文档,负责管理全部工作表,并记录作者、最后修改时间等元属性。
- Worksheet:代表工作簿中的一个 Sheet 页,掌管当前表的行高、列宽、标签底色(
tabColor)以及首行冻结等视窗规则。 - Column / Row:列与行的轴线集合。列定义负责横向字段映射与基准宽度,行对象负责承载纵向单元格实例。
- Cell:最基础的交互单元,存储单元格的实际值(
value)与运算公式(formula),所有视觉排版参数均挂载在cell.style对象上。
五、多 Sheet 页的构建与视窗控制
在综合报表中,通常需要将原始流水明细与汇总分析分开存放。通过 workbook.addWorksheet(name, options) 可以建立独立的工作表,并通过配置项完成标签染色与视图冻结。
// 1. 创建工作簿
const workbook = new ExcelJS.Workbook();
workbook.creator = '财务运营系统';
workbook.lastModifiedBy = 'Admin';
workbook.created = new Date();
// 2. 创建第一个 Sheet:销售明细表
const detailSheet = workbook.addWorksheet('销售明细表', {
properties: {
tabColor: { argb: 'FF477DAD' } // 自定义标签底色:稳重蓝
},
views: [
{ state: 'frozen', xSplit: 0, ySplit: 1 } // 冻结首行表头,向下滚动时常驻
]
});
// 3. 创建第二个 Sheet:指标汇总表
const summarySheet = workbook.addWorksheet('指标汇总表', {
properties: {
tabColor: { argb: 'FF2E7D32' } // 自定义标签底色:森林绿
},
views: [
{ showGridLines: true } // 显式保持网格线可见
]
});
views 数组中的 ySplit: 1 表示冻结第 1 行上方;若需要同时冻结前两列和第一行,可设置 xSplit: 2, ySplit: 1。该配置只作用于当前 Sheet,多 Sheet 间视窗互不干扰。
六、单元格细粒度样式定制规范
exceljs 的样式系统包含 fill(填充)、font(字体)、border(边框)、alignment(对齐)以及 numFmt(格式化)五大维度。
1. 颜色与 ARGB 规范
在 Excel OpenXML 协议中,颜色以 8 位十六进制 ARGB 字符串表示。前两位为 Alpha 通道(FF 为完全不透明),后六位为 RGB 颜色代码,且字符串前不能带 # 号。例如,普通 CSS 颜色 #477DAD 对应转换为 FF477DAD,白色为 FFFFFFFF。
2. 表头背景填充与字体排版
为表头设置主色调填充与纯白加粗文字,可建立清晰的视觉层级:
// 选取表头行并逐个单元格注入样式
const headerRow = detailSheet.getRow(1);
headerRow.height = 28; // 设置行高
headerRow.eachCell((cell) => {
// 背景填充
cell.fill = {
type: 'pattern',
pattern: 'solid',
fgColor: { argb: 'FF477DAD' }
};
// 字体配置
cell.font = {
name: '微软雅黑',
size: 11,
bold: true,
color: { argb: 'FFFFFFFF' }
};
// 对齐与排版
cell.alignment = {
vertical: 'middle',
horizontal: 'center'
};
});
3. 会计汇总边框与数字格式化
在统计行中,通常采用顶部细线、底部双线的国际会计样式,同时金额字段应采用带千分位和两位小数的格式化模板:
// 针对合计行单元格注入边框
totalCell.border = {
top: { style: 'thin', color: { argb: 'FFCBD5E1' } },
bottom: { style: 'double', color: { argb: 'FF4F6272' } }
};
// 数字与货币格式化
amountCell.numFmt = '¥#,##0.00';
dateCell.numFmt = 'yyyy-mm-dd';
七、完整可执行代码示例
以下给出一段可以直接复制运行的综合导出函数。该脚本在浏览器端运行,使用 writeBuffer 配合 Blob 机制完成文件生成:
import ExcelJS from 'exceljs';
import { saveAs } from 'file-saver';
export async function exportMultiSheetStyledExcel() {
// 步骤 1:新建工作簿
const workbook = new ExcelJS.Workbook();
workbook.creator = '数据分析系统';
workbook.created = new Date();
// -------------------------------------------------------------
// 工作表 1:订单明细表
// -------------------------------------------------------------
const sheet1 = workbook.addWorksheet('订单明细', {
properties: { tabColor: { argb: 'FF477DAD' } },
views: [{ state: 'frozen', ySplit: 1 }]
});
// 定义字段映射与列宽
sheet1.columns = [
{ header: '订单编号', key: 'orderNo', width: 16 },
{ header: '客户名称', key: 'client', width: 22 },
{ header: '合同金额', key: 'amount', width: 18 },
{ header: '签约日期', key: 'signDate', width: 14 },
{ header: '审核状态', key: 'status', width: 14 }
];
// 填充业务数据
const orders = [
{ orderNo: 'ORD-2026-001', client: '智慧物流科技有限公司', amount: 125000.5, signDate: '2026-10-12', status: '已履约' },
{ orderNo: 'ORD-2026-002', client: '云端计算技术集团', amount: 89000.0, signDate: '2026-10-18', status: '执行中' },
{ orderNo: 'ORD-2026-003', client: '数智零售发展中心', amount: 43200.75, signDate: '2026-11-05', status: '待审批' }
];
orders.forEach(item => sheet1.addRow(item));
// 表头行样式修饰
const sheet1Header = sheet1.getRow(1);
sheet1Header.height = 26;
sheet1Header.eachCell(cell => {
cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FF477DAD' } };
cell.font = { name: '微软雅黑', size: 11, bold: true, color: { argb: 'FFFFFFFF' } };
cell.alignment = { vertical: 'middle', horizontal: 'center' };
});
// 数据行网格边框与对齐控制
sheet1.eachRow((row, rowNumber) => {
if (rowNumber === 1) return; // 忽略表头
row.height = 22;
// 订单号:居中
row.getCell('orderNo').alignment = { vertical: 'middle', horizontal: 'center' };
// 金额列:居右对齐 + 千分位格式化
const amountCell = row.getCell('amount');
amountCell.alignment = { vertical: 'middle', horizontal: 'right' };
amountCell.numFmt = '¥#,##0.00';
// 状态列:居中 + 条件着色
const statusCell = row.getCell('status');
statusCell.alignment = { vertical: 'middle', horizontal: 'center' };
if (statusCell.value === '已履约') {
statusCell.font = { bold: true, color: { argb: 'FF137333' } };
statusCell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFE6F4EA' } };
}
// 全单元格加上浅灰色细边框
row.eachCell(cell => {
cell.border = {
top: { style: 'thin', color: { argb: 'FFE2E8F0' } },
left: { style: 'thin', color: { argb: 'FFE2E8F0' } },
bottom: { style: 'thin', color: { argb: 'FFE2E8F0' } },
right: { style: 'thin', color: { argb: 'FFE2E8F0' } }
};
});
});
// -------------------------------------------------------------
// 工作表 2:季度指标汇总
// -------------------------------------------------------------
const sheet2 = workbook.addWorksheet('季度汇总', {
properties: { tabColor: { argb: 'FF2E7D32' } }
});
sheet2.columns = [
{ header: '统计维度', key: 'metric', width: 20 },
{ header: '统计数值', key: 'val', width: 22 }
];
sheet2.addRow({ metric: '订单总数', val: 3 });
sheet2.addRow({ metric: '总交易额', val: 257201.25 });
// 格式化汇总表第二行金额
sheet2.getRow(3).getCell(2).numFmt = '¥#,##0.00';
// -------------------------------------------------------------
// 步骤 5:导出为二进制文件
// -------------------------------------------------------------
const buffer = await workbook.xlsx.writeBuffer();
const blob = new Blob([buffer], {
type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
});
saveAs(blob, `经营业绩报表_${new Date().toISOString().slice(0, 10)}.xlsx`);
}
八、双端导出差异与运行总结
exceljs 在浏览器与 Node.js 服务端使用了相同的核心数据结构,但在文件落盘环节具有不同适配方式。
1. 浏览器环境写入细节
浏览器沙箱不允许直接调用本地文件写入系统,因此必须通过 workbook.xlsx.writeBuffer() 生成 ArrayBuffer,再包装为标准 MIME 类型的 Blob 对象(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet),利用 file-saver 或虚拟 <a download> 触发系统下载对话框。
2. 服务端 Node.js 环境写入与流式处理
在服务端,可以通过 workbook.xlsx.writeFile('filepath.xlsx') 直接写入磁盘。当导出行数超过数万行时,一次性在内存中构建全部单元格对象容易造成 V8 内存溢出(OOM)。针对大数据场景,建议选用 exceljs 提供的流式写入器:
// Node.js 端流式处理应对十万级大数据量
const options = {
filename: './stream_export.xlsx',
useStyles: true, // 启用样式流支持
useSharedStrings: true
};
const streamWorkbook = new ExcelJS.stream.xlsx.WorkbookWriter(options);
const streamSheet = streamWorkbook.addWorksheet('海量明细');
// 循环分批写入并提交
for (let i = 0; i < records.length; i++) {
const row = streamSheet.addRow(records[i]);
row.commit(); // 提交单行写入,释放前置内存
}
streamSheet.commit(); // 提交工作表
await streamWorkbook.commit(); // 提交完成关闭文件流
九、高频常见问题与注意事项
在批量给单元格赋予样式时,若将同一个 JavaScript 对象赋值给多个单元格(如 cell.border = commonBorder),由于对象引用的存在,后续对某一单元格样式的变更将意外影响到所有引用该对象的单元格。应通过工厂函数或深解构({ ...commonBorder })分配独立对象。
在 Excel 中,width: 10 表示容纳 10 个半角字符的宽度。中文字符在排版时占据两个半角字符位,若根据 str.length 计算列宽,中文内容会被右侧单元格遮挡或显示为 ###。计算列宽时,可使用简易字符加权算法:
// 估算自适应列宽
function calculateColWidth(str) {
if (!str) return 10;
let len = 0;
for (let i = 0; i < str.length; i++) {
len += str.charCodeAt(i) > 255 ? 2.1 : 1.1;
}
return Math.max(Math.ceil(len) + 2, 10);
}
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。