SheetJS (xlsx) 基础教程:JS 实现数据导出 Excel

作者:异步漫步

时间:2026-11-21

浏览:658

深入讲解如何使用 SheetJS (xlsx) 在浏览器端使用 JavaScript 实现数据导出为 Excel (.xlsx) 文件,包括核心数据模型流转、基础四步导出、列宽自适应、合并单元格以及常见长数字精度和日期偏移避坑指南。

文章目录
技术教程 适用环境:浏览器前端 (ES6+ / CDN / Vue / React) 核心类库:SheetJS (xlsx)

在现代 Web 应用中,将表格数据导出为 Excel 文件是常见的数据交付需求。使用 SheetJS(npm 包名为 xlsx)可以在浏览器纯前端环境下直接完成 JSON 数据到 .xlsx 文件的组装与下载,无需服务端额外开辟接口。本文将从核心流转机制、环境引入、基础四步代码、列宽与合并定制,到高频长数字与日期避坑方案进行系统拆解。

SheetJS (xlsx) 基础教程:JS 实现数据导出 Excel
图 0: SheetJS (xlsx) 数据导出 Excel 全链路数据流转总览

一、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 (xlsx) 基础教程:JS 实现数据导出 Excel
图 1: SheetJS 核心对象与分层数据流转架构(等距堆叠视图)

二、环境准备与类库引入

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';

三、核心实现:四步完成基础数据导出

完成环境准备后,导出流程仅需四个标准步骤即可闭环。以下通过一个标准的员工花名册示例,展示完整的导出流程。

SheetJS (xlsx) 基础教程:JS 实现数据导出 Excel
图 2: SheetJS 四步导出执行时序链路(从数据清洗到文件落地)

完整可执行代码示例

以下为可以直接在浏览器运行的原生代码,点击按钮即可触发 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 对象的扩展属性来实现。

SheetJS (xlsx) 基础教程:JS 实现数据导出 Excel
图 3: 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");

五、高频问题排查与生产避坑指南

在真实业务环境中,直接调用导出可能会遭遇数据截断、时区偏差甚至浏览器卡死等问题。以下总结了生产中最常见的四大陷阱及其稳健解决方案。

SheetJS (xlsx) 基础教程:JS 实现数据导出 Excel
图 4: SheetJS 生产环境技术选型与避坑全景图
常见问题现象 根本原因解析 标准解决与防御策略
长数字精度丢失 / 科学计数法(如身份证、银行卡号末尾变 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 导出服务。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章