JS前端导出Excel:SheetJS (xlsx) 基础用法与下载实现

作者:像素漫游

时间:2026-11-19

浏览:652

本文深入讲解在前端使用 SheetJS (xlsx) 实现 Excel 导出与自动下载的完整方案,涵盖核心对象模型、三种常用数据转换方法、工作簿构建、文件下载实现以及列宽与性能边界等实用细节。

文章目录
JS前端导出Excel:SheetJS (xlsx) 基础用法与下载实现
图 0:SheetJS (xlsx) 前端表格数据转换与 Excel 本地导出整体架构

在日常前端后台系统或数据分析页面开发中,用户在筛选、核对完表格数据后,往往需要点击“导出 Excel”按钮将当前展示或选中的数据保存为 .xlsx 文件。过去常见的方案依赖后端提供专门的导出接口,后端接收查询参数后拉取数据库、生成二进制文件流再回传给浏览器。然而,对于数据量在数万行以内、前端已经持有完整列表或快照的场景,完全可以在浏览器端利用纯 JavaScript 完成数据组装与文件生成,避免服务端额外的 CPU 与 I/O 负担。

SheetJS(在 npm 社区生态中名为 xlsx)是目前 JavaScript 生态中使用广泛的电子表格解析与生成工具库。本文将围绕前端导出 Excel 这一具体需求,从 SheetJS 的内部数据模型、核心转换方法、工作簿组装以及浏览器下载实现展开完整讲解,并给出兼顾列宽设置与性能边界的生产实践指南。

一、前端导出 Excel 的核心执行流程

使用 SheetJS 完成前端导出的本质,是在浏览器运行内存中完成一次标准的数据结构组装:从我们持有的业务数组,转换为符合电子表格规范的“工作表(WorkSheet)”,再将一个或多个工作表挂载进“工作簿(WorkBook)”,最终通过二进制序列化输出为文件并触发浏览器下载行为。

JS前端导出Excel:SheetJS (xlsx) 基础用法与下载实现
图 1:SheetJS 前端导出 Excel 四步标准流水线

整个流程可以划分为四个清晰的阶段:

  1. 准备业务数据:准备好页面上需要导出的数据集合,可以是常见的接口返回的 JSON 对象数组,也可以是纯矩阵式的二维数组。
  2. 转换为 WorkSheet:调用 SheetJS 提供的转换工具方法(如 json_to_sheet 或 aoa_to_sheet),将扁平业务数据转为带有单元格坐标(如 A1、B2)的内存映射对象。
  3. 构建并装配 WorkBook:使用 book_new 创建工作簿,并通过 book_append_sheet 把前一步生成的工作表添加进工作簿中,支持定义表名与添加多个工作表。
  4. 生成文件并触发下载:调用 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 页面引入方式

如果是在没有打包工具的原生 HTML 页面或传统项目中,可以直接通过 CDN 引入。引入后,全局作用域下将自动挂载 window.XLSX 对象:

<script src="https://cdn.sheetjs.com/xlsx-latest/package/dist/xlsx.full.min.js"></script>

三、核心数据模型:WorkBook、WorkSheet 与 Cell

为了在写代码时清楚每一行调用的含义,我们需要先理解 SheetJS 在内存中的三层核心对象模型。它们自顶向下依次对应电子表格的容器层、工作表层与单元格数据层。

JS前端导出Excel:SheetJS (xlsx) 基础用法与下载实现
图 2: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 提供的现成辅助函数。根据手头数据格式的不同,主要有三种选择:

JS前端导出Excel:SheetJS (xlsx) 基础用法与下载实现
图 3:SheetJS 三大工作表转换函数选型对比

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

七、限制条件与生产环境考量

JS前端导出Excel:SheetJS (xlsx) 基础用法与下载实现
图 4:前端导出 Excel 生产落地决策与边界排查

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 导出需求。在实际业务中,结合列宽自动计算与长数字文本化保护,既能提升用户的导出体验,也能有效规避数据精度失真的隐患。

实用工具推荐

电子包浆

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

使用 ›
图片压缩

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

使用 ›
相关文章