深入讲解如何使用 SheetJS (xlsx) 在浏览器端使用 JavaScript 实现数据导出为 Excel (.xlsx) 文件,包括核心数据模型流转、基础四步导出、列宽自适应、合并单元格以及常见长数字精度和日期偏移避坑指南。
SheetJS (xlsx) 基础教程:JS 实现数据导出 Excel
时间:2026-11-21
浏览:658
文章目录
在现代 Web 应用中,将表格数据导出为 Excel 文件是常见的数据交付需求。使用 SheetJS(npm 包名为 xlsx)可以在浏览器纯前端环境下直接完成 JSON 数据到 .xlsx 文件的组装与下载,无需服务端额外开辟接口。本文将从核心流转机制、环境引入、基础四步代码、列宽与合并定制,到高频长数字与日期避坑方案进行系统拆解。
一、SheetJS 导出 Excel 的核心对象流转
初次使用 SheetJS 时,许多开发者容易被其丰富的 API 名称所混淆。实际上,SheetJS 的导出逻辑遵循严格的三层对象模型:原始数据 (Raw Data)、工作表对象 (Worksheet)、工作簿容器 (Workbook),最后由文件写入函数统一打包为二进制文件流并触发浏览器下载。
理解这一分层至关重要,各层承担的职能明确划分:
- 原始数据层 (Raw Data):通常为前端业务直接使用的 JavaScript 对象数组(例如后台返回的列表数据
[{ 姓名: "张三", 部门: "技术部" }])或二维数组。 - 工作表层 (Worksheet,缩写
ws):表示单个 Sheet 表格。在此层级中,数据被解析为平面坐标网格(如A1、B2),并在此处配置列宽(!cols)、行高(!rows)及单元格合并(!merges)。 - 工作簿层 (Workbook,缩写
wb):对应一个完整的 Excel 文件容器。一个工作簿可以挂载多个工作表,并管理底层的 Sheet 标签页顺序与名称。 - 导出层 (File Writer):通过
XLSX.writeFile函数,在客户端将工作簿内存对象序列化为符合 Office Open XML (OOXML) 规范的压缩包,并调起浏览器的原生下载保存窗口。
二、环境准备与类库引入
SheetJS 具备极强的运行环境兼容性,既可以在原生 HTML 中通过 CDN 脚本直引,也可以在 Vue、React、Angular 等现代工程化脚手架中按模块引入。
1. 原生页面 CDN 快速引入
若在轻量页面或内部工具中快速使用,直接在 HTML 文件的 <head> 或 <body> 底部加入 CDN 标签即可:
<!-- 引入 SheetJS 官方稳定版脚本 -->
<script src="https://cdn.jsdelivr.net/npm/xlsx@0.18.5/dist/xlsx.full.min.js"></script>
2. 工程化模块引入 (NPM / Yarn / PNPM)
在 Node.js 或打包工具(Vite、Webpack)项目中,执行以下命令安装依赖:
npm install xlsx
在 JavaScript 或 TypeScript 业务代码中导入:
import * as XLSX from 'xlsx';
三、核心实现:四步完成基础数据导出
完成环境准备后,导出流程仅需四个标准步骤即可闭环。以下通过一个标准的员工花名册示例,展示完整的导出流程。
完整可执行代码示例
以下为可以直接在浏览器运行的原生代码,点击按钮即可触发 Excel 文件下载:
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>SheetJS 导出示例</title>
<script src="https://cdn.jsdelivr.net/npm/xlsx@0.18.5/dist/xlsx.full.min.js"></script>
</head>
<body>
<button id="exportBtn">导出员工信息表</button>
<script>
function exportToExcel() {
// 步骤 1:准备原始数据 (键名为表头,值为单元格内容)
const userList = [
{ "工号": "EMP001", "姓名": "张三", "部门": "技术研发部", "入职日期": "2023-03-15", "基本薪资": 12500 },
{ "工号": "EMP002", "姓名": "李四", "部门": "市场运营部", "入职日期": "2022-07-01", "基本薪资": 9800 },
{ "工号": "EMP003", "姓名": "王五", "部门": "产品设计部", "入职日期": "2024-01-10", "基本薪资": 11000 }
];
// 步骤 2:将 JSON 数据转换为工作表 (Worksheet)
const worksheet = XLSX.utils.json_to_sheet(userList);
// 步骤 3:创建新的工作簿 (Workbook),并将工作表挂载到工作簿中
const workbook = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(workbook, worksheet, "员工花名册");
// 步骤 4:生成 .xlsx 文件并触发浏览器下载
XLSX.writeFile(workbook, "2026年度员工花名册.xlsx");
}
document.getElementById('exportBtn').addEventListener('click', exportToExcel);
</script>
</body>
</html>
XLSX.utils.json_to_sheet() 会自动提取对象数组中第一项的所有键名作为 Excel 的第一行表头,并依次将后续对象的键值对应填入相应列。对象的属性声明顺序直接决定了 Excel 中列的排列顺序。
四、进阶定制:列宽自适应、单元格合并与多 Sheet
基础导出虽然快捷,但在实际业务交付中,默认列宽往往过窄导致内容被截断,或者需要定制表头合并和多标签页。这些需求都可以通过直接操作 Worksheet 对象的扩展属性来实现。
1. 动态自适应列宽配置 (!cols)
默认导出的 Excel 每列宽度均等,中文或长字符容易显示不全。我们可以遍历每列数据,统计其最大字符宽度,然后通过 ws['!cols'] 设置宽度:
function autoFitColumns(data, worksheet) {
if (!data || !data.length) return;
// 获取所有列名
const headers = Object.keys(data[0]);
// 计算每列最大宽度 (中文字符按 2 字符计算)
const colWidths = headers.map(header => {
let maxLength = Math.max(
// 表头宽度
getStringByteLength(header),
// 遍历所有数据行的当前列内容宽度
...data.map(row => getStringByteLength(row[header] ? String(row[header]) : ''))
);
// 留出 3 个字符的安全边距,并设定最小列宽 10
return { wch: Math.max(maxLength + 3, 10) };
});
worksheet['!cols'] = colWidths;
}
function getStringByteLength(str) {
let len = 0;
for (let i = 0; i < str.length; i++) {
// 判断是否为非单字节字符(如汉字、全角符号)
len += str.charCodeAt(i) > 255 ? 2 : 1;
}
return len;
}
2. 单元格合并配置 (!merges)
若需要在大标题、分组报表等场景下合并单元格,可以使用 ws['!merges']。该属性接收一个数组,每个元素包含起始单元格 s (start) 与结束单元格 e (end),坐标基于从 0 开始的数字索引(r 代表行,c 代表列):
// 示例:合并第 1 行的第 1 列至第 4 列 (对应 Excel 中的 A1:D1)
worksheet['!merges'] = [
{
s: { r: 0, c: 0 }, // 起始坐标:第0行,第0列 (A1)
e: { r: 0, c: 3 } // 结束坐标:第0行,第3列 (D1)
}
];
3. 导出一个包含多个工作表 (Multi-Sheet) 的 Excel
一个 Workbook 容器可以多次调用 book_append_sheet,从而在一个文件内输出多个标签页:
const workbook = XLSX.utils.book_new();
// 创建研发部与运营部两个工作表
const wsDev = XLSX.utils.json_to_sheet(devUserData);
const wsOps = XLSX.utils.json_to_sheet(opsUserData);
// 分别挂载到工作簿,并赋予独立的 Tab 名称
XLSX.utils.book_append_sheet(workbook, wsDev, "研发部清单");
XLSX.utils.book_append_sheet(workbook, wsOps, "运营部清单");
// 统一输出
XLSX.writeFile(workbook, "各部门人员分表明细.xlsx");
五、高频问题排查与生产避坑指南
在真实业务环境中,直接调用导出可能会遭遇数据截断、时区偏差甚至浏览器卡死等问题。以下总结了生产中最常见的四大陷阱及其稳健解决方案。
| 常见问题现象 | 根本原因解析 | 标准解决与防御策略 |
|---|---|---|
| 长数字精度丢失 / 科学计数法(如身份证、银行卡号末尾变 0) | Excel 遵循 IEEE 754 规范,将纯数字当做双精度浮点数存储,超过 15 位时自动截断为 0 并采用科学计数法(如 1.10101E+17)。 |
在转换前,通过数据清洗将长数字强制转换为字符串;或在构建单元格时显式指定类型为文本 { t: 's', v: idStr }。 |
| 日期时间相差 8 小时 | 前端直接传递 JavaScript Date 对象时,SheetJS 默认按照 UTC 0 时区进行时间戳折算,导致本地(UTC+8)时间被扣减 8 小时。 |
避免直接向数据源写入原始 Date 对象,统一在前端先格式化为标准文本(如 "2026-11-18 10:30:00")再导入工作表。 |
| 大数据量导出页面卡顿甚至崩溃 | json_to_sheet 和 writeFile 均为同步执行的大内存开销计算,当数据量达到几万行时,主线程被长时间占用,容易导致浏览器无响应或内存溢出 (OOM)。 |
· 1万行以内:前端直接执行; · 1万 ~ 5万行:使用 Web Worker 在后台线程处理数据并导出;· 5万行以上:建议由服务端流式生成 CSV 或 Excel 并提供下载。 |
| 工作表名称乱码或抛出异常 | Excel 对 Sheet 标签页名称有严格规范,长度不能超过 31 个字符,且严禁包含特殊符号 : \ / ? * [ ]。 |
在调用 book_append_sheet 之前,对 Sheet 名称进行正则过滤并截断长度:sheetName.replace(/[\/:?*\[\]]/g, '').slice(0, 31)。 |
六、总结
SheetJS 凭借轻量、纯前端、无 DOM 强依赖的特性,成为了 Web 领域处理 Excel 导出的行业标准工具库。在掌握了 原始数据 → Worksheet → Workbook → writeFile 的标准流转主线后,开发者可以轻松应对 90% 以上的基础导出需求。
在实际工程落地时,始终牢记“数据预清洗先于图表组装”的原则:长数字转字符、日期先格式化、列宽计算加冗余、大批量走异步。遵循这套规范,即可在前端构建出既美观、高效又兼具鲁棒性的 Excel 导出服务。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。