JS前端导出Excel:SheetJS (xlsx) 基础用法与下载实现
本文深入讲解在前端使用 SheetJS (xlsx) 实现 Excel 导出与自动下载的完整方案,涵盖核心对象模型、三种常用数据转换方法、工作簿构建、文件下载实现以及列宽与性能边界等实用细节。
在日常前端后台系统或数据分析页面开发中,用户在筛选、核对完表格数据后,往往需要点击“导出 Excel”按钮将当前展示或选中的数据保存为 .xlsx 文件。过去常见的方案依赖后端提供专门的导出接口,后端接收查询参数后拉取数据库、生成二进制文件流再回传给浏览器。然而,对于数据量在数万行以内、前端已经持有完整列表或快照的场景,完全可以在浏览器端利用纯 JavaScript 完成数据组装与文件生成,避免服务端额外的 CPU 与 I/O 负担。
SheetJS(在 npm 社区生态中名为 xlsx)是目前 JavaScript 生态中使用广泛的电子表格解析与生成工具库。本文将围绕前端导出 Excel 这一具体需求,从 SheetJS 的内部数据模型、核心转换方法、工作簿组装以及浏览器下载实现展开完整讲解,并给出兼顾列宽设置与性能边界的生产实践指南。
一、前端导出 Excel 的核心执行流程
使用 SheetJS 完成前端导出的本质,是在浏览器运行内存中完成一次标准的数据结构组装:从我们持有的业务数组,转换为符合电子表格规范的“工作表(WorkSheet)”,再将一个或多个工作表挂载进“工作簿(WorkBook)”,最终通过二进制序列化输出为文件并触发浏览器下载行为。
整个流程可以划分为四个清晰的阶段:
- 准备业务数据:准备好页面上需要导出的数据集合,可以是常见的接口返回的 JSON 对象数组,也可以是纯矩阵式的二维数组。
- 转换为 WorkSheet:调用 SheetJS 提供的转换工具方法(如
json_to_sheet或aoa_to_sheet),将扁平业务数据转为带有单元格坐标(如 A1、B2)的内存映射对象。 - 构建并装配 WorkBook:使用
book_new创建工作簿,并通过book_append_sheet把前一步生成的工作表添加进工作簿中,支持定义表名与添加多个工作表。 - 生成文件并触发下载:调用
XLSX.writeFile直接落盘保存,或者调用XLSX.write生成二进制 ArrayBuffer 并利用 Blob URL 由<a download>标签触发保存。
二、在工程中安装与引入 SheetJS
在现代前端工程中,推荐通过 npm、yarn 或 pnpm 将 xlsx 安装为项目的正式依赖:
# 使用 npm 安装
npm install xlsx
# 或使用 pnpm 安装
pnpm add xlsx
在组件或工具函数中,可以通过 ESM 语法导入完整的 XLSX 命名空间:
import * as XLSX from 'xlsx';
如果是在没有打包工具的原生 HTML 页面或传统项目中,可以直接通过 CDN 引入。引入后,全局作用域下将自动挂载 window.XLSX 对象:
<script src="https://cdn.sheetjs.com/xlsx-latest/package/dist/xlsx.full.min.js"></script>
三、核心数据模型:WorkBook、WorkSheet 与 Cell
为了在写代码时清楚每一行调用的含义,我们需要先理解 SheetJS 在内存中的三层核心对象模型。它们自顶向下依次对应电子表格的容器层、工作表层与单元格数据层。
1. WorkBook(工作簿)
WorkBook 代表整个 Excel 文件。在 JavaScript 中它是一个普通的 Plain Object,包含两个最核心的属性:
SheetNames:一个字符串数组(如['销售数据', '退款统计']),保存当前工作簿中所有 Sheet 的名称顺序。Sheets:一个字典对象,键名为SheetNames中声明的表名,键值则是对应的 WorkSheet 对象。
2. WorkSheet(工作表)
WorkSheet 代表 Excel 中的某一个标签页。它的内部数据结构非常直观——使用单元格坐标字符串作为键名(如 A1、B2、C10),映射到该单元格对应的 Cell Object。同时包含以 ! 开头的元数据控制字段:
!ref:标记该工作表的坐标有效范围(如"A1:D20")。Excel 解析器会依据该范围进行矩阵渲染,若缺失该字段可能导致打开文件为空白。!cols:列属性定义数组,用于指定各列的默认宽度、隐藏状态等。!merges:单元格合并范围数组,用于定义复杂跨行跨列表头。
3. Cell Object(单元格原子对象)
每个单元格都由一个独立的 JavaScript 对象表示,常见的属性包括:
t:单元格类型代码。常见有's'(String 文本)、'n'(Number 数值)、'b'(Boolean 布尔值)、'd'(Date 日期)。v:单元格的真实原始值(Raw Value)。w:格式化展示后的字符串文本(Formatted Text)。z:数字格式化字符串(Number Format)。
四、数据源转换实战:三大常用转换方法
在实际编码中,我们极少手动去逐个手写 A1: { t: 's', v: '...' } 字典,而是使用 XLSX.utils 提供的现成辅助函数。根据手头数据格式的不同,主要有三种选择:
1. 对象数组转换:json_to_sheet(最常用)
业务中最常见的是后端 API 返回的列表数据(包含对象的数组)。json_to_sheet 会自动抓取对象的 key 作为 Excel 第一行表头,剩余字段按序作为行记录:
import * as XLSX from 'xlsx';
// 模拟业务数据源
const userList = [
{ id: 1001, name: '张三', department: '技术部', salary: 15000 },
{ id: 1002, name: '李四', department: '产品部', salary: 16500 },
{ id: 1003, name: '王五', department: '运营部', salary: 13000 }
];
// 转换为 WorkSheet
const ws = XLSX.utils.json_to_sheet(userList);
如果希望自定义表头显示的文字或者调整导出的字段顺序,可以传递配置参数或预先映射数据字典:
// 方式 A:在转换前重构键名与顺序(直观无冗余)
const exportData = userList.map(item => ({
'员工工号': item.id,
'员工姓名': item.name,
'所属部门': item.department,
'薪酬预算': item.salary
}));
const wsFormatted = XLSX.utils.json_to_sheet(exportData);
2. 二维矩阵数组转换:aoa_to_sheet
若你的表格具有复杂的自定义结构、多级复合表头,或者需要在首行添加“报表生成日期”等非结构化文本,aoa_to_sheet(Array of Arrays to Sheet)是最佳选择:
// 构造二维矩阵数组
const aoaData = [
['公司 2026 年度第一季度财务概览', null, null], // 标题行
['统计周期: 2026-01-01 至 2026-03-31', null, null],
['项目编号', '项目名称', '实际金额 (元)'], // 表头
['P-01', '服务器采购', 48500],
['P-02', '带宽与专线', 12000],
['合计', null, 60500]
];
// 转换为工作表
const wsFromAoa = XLSX.utils.aoa_to_sheet(aoaData);
3. 原生 HTML Table DOM 抓取:table_to_sheet
若当前页面已有渲染好的原生 <table> 标签,希望直接导出其展示的内容,可以直接传入 DOM 元素:
const tableElement = document.getElementById('report-table');
const wsFromTable = XLSX.utils.table_to_sheet(tableElement);
注意:table_to_sheet 仅能抓取当前 DOM 树中渲染出来的节点。如果表格采用了前端分页或虚拟滚动,视口外的未渲染行不会被导出。
五、组装工作簿与触发文件下载实现
得到 WorkSheet 后,接下来需要将其放入 WorkBook,并调用下载逻辑保存到本地磁盘。下面介绍两种成熟的下载实现方案。
方案一:一行代码极简导出(XLSX.writeFile)
SheetJS 在浏览器环境中内置了下载逻辑,XLSX.writeFile 会自动在内部创建一个隐藏的 <a download> 标签,挂载文件 Blob 并触发点击,随后清理临时对象。这是最便捷的做法:
import * as XLSX from 'xlsx';
export function exportUsersToExcel(data, filename = '用户数据表.xlsx') {
// 1. 转换数据为工作表
const ws = XLSX.utils.json_to_sheet(data);
// 2. 创建新工作簿
const wb = XLSX.utils.book_new();
// 3. 将工作表添加进工作簿,命名为 "人员清单"
XLSX.utils.book_append_sheet(wb, ws, '人员清单');
// 4. 直接输出并触发本地保存
XLSX.writeFile(wb, filename);
}
方案二:底层控制生成 Blob(适用于需要自定义流或上传的场景)
如果业务中需要在导出前对文件流进行加密、通过接口同步上传至服务器对象存储(OSS),或者对下载行为有特殊的防拦截策略,可以使用 XLSX.write 输出二进制 ArrayBuffer,再封装为原生 Blob:
import * as XLSX from 'xlsx';
export function exportCustomBlob(wb, filename = '报表.xlsx') {
// 生成 Excel 二进制字节流
const wbout = XLSX.write(wb, {
bookType: 'xlsx',
type: 'array' // 产出标准的 ArrayBuffer
});
// 封装为标准 MIME 类型的 Blob 对象
const blob = new Blob([wbout], {
type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
});
// 创建临时下载链接
const objectUrl = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = objectUrl;
a.download = filename;
// 挂载至 DOM、触发下载并清理资源
document.body.appendChild(a);
a.click();
document.body.removeChild(a);
// 释放内存中的 URL 映射
setTimeout(() => URL.revokeObjectURL(objectUrl), 1000);
}
六、实用业务技巧:列宽设置与多 Sheet 导出
1. 设置自适应或固定列宽
默认生成的 Excel 文件各列宽度通常为固定紧缩宽度,如果内容较长(如订单流水号、时间戳),在 Excel 中打开往往会显示为 ### 或发生重叠。可以通过配置 WorkSheet 的 !cols 属性指定列宽:
// wch 代表大致容纳的英文字符数(宽度)
ws['!cols'] = [
{ wch: 10 }, // 第 A 列宽度
{ wch: 18 }, // 第 B 列宽度
{ wch: 25 }, // 第 C 列宽度
{ wch: 15 } // 第 D 列宽度
];
若希望根据数据内容自动计算列宽,可以编写一个通用的列宽自适应函数:
function autoFitColumns(data) {
if (!data || !data.length) return [];
const keys = Object.keys(data[0]);
return keys.map(key => {
// 获取表头及所有单元格中文本最大长度
let maxLen = key.toString().length;
for (let i = 0; i < data.length; i++) {
const cellVal = data[i][key] ? data[i][key].toString() : '';
// 简单中文双字符权重处理
let len = 0;
for (let ch of cellVal) {
len += ch.charCodeAt(0) > 255 ? 2 : 1;
}
if (len > maxLen) maxLen = len;
}
return { wch: Math.min(Math.max(maxLen + 4, 12), 50) };
});
}
// 结合使用
ws['!cols'] = autoFitColumns(exportData);
2. 导出一个工作簿包含多个工作表
只需多次调用 book_append_sheet,即可轻松在一个 .xlsx 文件中创建多个 Sheet 页:
const wb = XLSX.utils.book_new();
// 工作表 1:明细数据
const wsDetail = XLSX.utils.json_to_sheet(orderList);
XLSX.utils.book_append_sheet(wb, wsDetail, '订单明细');
// 工作表 2:统计汇总
const wsSummary = XLSX.utils.aoa_to_sheet([
['指标', '数值'],
['订单总量', 1250],
['成交总额', 892000]
]);
XLSX.utils.book_append_sheet(wb, wsSummary, '数据汇总');
// 保存为包含两个 Sheet 的 Excel
XLSX.writeFile(wb, '财务月报综合表.xlsx');
七、限制条件与生产环境考量
1. 内存与数据量瓶颈
在前端运行环境导出数据具有天然的硬件限制:
- 单次导出行数建议在 3 万至 5 万行以内:当数据量达到数十万级别时,JSON 转换为庞大的 AST 字典树并在主线程执行 ZIP 压缩序列化,会导致浏览器标签页内存暴涨甚至触发崩溃(Out of Memory)。
- 避免主线程阻塞:如果数据量在数万行之间,计算过程可能会导致页面 UI 出现短暂卡顿。对于追求平滑体验的项目,可将 SheetJS 运算放到
Web Worker中执行,生成 ArrayBuffer 后再 postMessage 回传主线程下载。 - 海量数据采用后端流式导出:若导出需求达到 10 万行以上,最佳方案依然是由后端以流式(如 Node.js Stream / Java EasyExcel)边查库边写入压缩流传输给前端。
2. 社区开源版的样式限制
很多开发者在初次使用 SheetJS 时会尝试设置单元格字体颜色、背景高亮或粗边框。需要特别注意:SheetJS 社区开源免费版(Community Edition)不支持写入单元格样式(如字体、填充、边框等)。即使在 cell 对象上附加 s: { fill: ... },在输出时也会被默认忽略。
如果业务强依赖高亮警示色、自定义字体大小或表格斑马线样式,有以下替代解法:
- 使用 ExcelJS(
exceljs):完全开源且原生支持完整的单元格样式、公式、边框与图片插入。 - 采购 SheetJS Pro 商业授权版本,享有官方完整的样式引擎。
3. 长数字与身份证号精度丢失问题
在导出身份证号、银行卡号或 19 位的雪花算法 ID 时,Excel 默认会将其解析为浮点数,超过 15 位的部分会被强制截断替换为 0 并采用科学计数法展示(如 1.10101E+17)。
解决方案:在导出前显式将长数字处理为纯字符串,或者在数值前后拼接不可见空格/制表符 ,或者在 AOA 转换时显式指定单元格类型:
// 方式 A:拼接制表符(简单直接)
item.idCard = item.idCard + ' ';
// 方式 B:使用 aoa 显式构建字符串 Cell
const cell = { t: 's', v: '110101199003072345' };
八、总结与核心用法速查表
| 操作环节 | 核心方法 / 属性 | 入参类型 | 关键说明 |
|---|---|---|---|
| 数据转工作表 | XLSX.utils.json_to_sheet |
Array<Object> |
将对象列表转为 Sheet,Key 自动提取为第一行表头 |
| 矩阵转工作表 | XLSX.utils.aoa_to_sheet |
Array<Array> |
将二维数组转为 Sheet,支持自由布局与多级表头 |
| DOM转工作表 | XLSX.utils.table_to_sheet |
HTMLTableElement |
抓取页面已有原生 table 节点,所见即所得 |
| 创建工作簿 | XLSX.utils.book_new() |
无 | 返回空工作簿对象 { SheetNames: [], Sheets: {} } |
| 挂载工作表 | XLSX.utils.book_append_sheet |
(wb, ws, name) |
将 Sheet 关联至 Workbook 并指定标签名称 |
| 调整列宽 | ws['!cols'] = [...] |
Array<{ wch: number }> |
设置每列字符宽度,避免长文字被遮挡 |
| 触发下载保存 | XLSX.writeFile(wb, filename) |
(wb, string) |
单行调用,自动生成二进制并在浏览器端唤起保存 |
掌握了上述数据模型、转换逻辑与下载封装,便能从容应对绝大部分前端轻量级 Excel 导出需求。在实际业务中,结合列宽自动计算与长数字文本化保护,既能提升用户的导出体验,也能有效规避数据精度失真的隐患。
JS原生实现图片自动轮播:定时器控制与DOM切换逻辑
2026-11-19 22:18:51
JS使用DOMParser解析HTML字符串并提取内容
2026-11-19 21:13:24
JS怎么遍历HTML表格获取所有行数据
2026-11-19 17:34:26
JS动态商品列表点击无效?用事件委托优化购物车性能
2026-11-19 15:11:55
JS双向绑定常见面试题:响应式原理与内存泄漏排查
2026-11-19 15:10:39








