编写练习册

API

从数据生成电子表格字节（文件）

  1. var data = XLSX.write(workbook, opts);

write 方法尝试将工作簿中的数据打包到内存中的文件中。默认情况下，会生成 XLSX 文件，但可以使用 opts 参数的 bookType 属性进行控制。基于 type 选项，数据可以存储为 “二进制字符串”、JS 字符串、Uint8Array 或 Buffer。

第二个 opts 参数是必需的。“写作选项” 涵盖了支持的属性和行为。

生成并尝试保存文件

  1. XLSX.writeFile(workbook, filename, opts);

writeFile 方法打包数据并尝试保存新文件。导出文件格式由 filename 的扩展名决定（SheetJS.xlsx 信号 XLSX 导出，SheetJS.xlsb 信号 XLSB 导出等）。

第二个 opts 参数是可选的。“写作选项” 涵盖了支持的属性和行为。

生成并尝试保存 XLSX 文件

  1. XLSX.writeFileXLSX(workbook, filename, opts);

writeFile 方法嵌入了许多不同的导出函数。这对于开发者体验来说非常有用，但不适合使用当前的开发者工具进行树摇动。当仅需要 XLSX 导出时，此方法可以避免引用其他导出函数。

第二个 opts 参数是可选的。“写作选项” 涵盖了支持的属性和行为。

writeFile 和 writeFileXLSX 方法使用特定于平台的 API 来保存文件。API 通常不提供有关文件是否已创建的反馈。

示例

以下是一些常见的场景（点击每个字幕即可查看代码）。

demos 更详细地介绍了特殊部署。

示例：本地文件

XLSX.writeFile 支持在 NodeJS 等平台写入本地文件。在 React Native 等其他平台中，应该使用文件数据调用 XLSX.write。

  • Browser
  • NodeJS
  • Bun
  • Deno
  • Electron
  • React Native
  • Photoshop
  • Headless

XLSX.writeFile 包含了一些触发文件保存的技术：

  • URL 浏览器 API 为文件创建一个对象 URL，库通过创建链接并强制单击来使用该对象 URL。现代浏览器支持它。

  • msSaveBlob 是用于触发文件保存的 IE10+ API。

  • IE_FileSave 使用 VBScript 和 ActiveX 在 Windows XP 和 Windows 7 的 IE6+ 中编写文件。该填充程序必须包含在包含 HTML 页面中。

没有标准方法来确定实际文件是否已下载。

  1. /* output format determined by filename */XLSX.writeFile(workbook, "out.xlsb");/* at this point, out.xlsb will have been downloaded */

Web Worker

Web Workers 中没有一个文件写入 API 可以工作。生成文件：

  1. 使用 XLSX.write 和类型 array 生成 Uint8Array： 
  1. // in the web worker, generate the XLSX file as a Uint8Arrayconst u8 = XLSX.write(workbook, { type: "array", bookType: "xlsx" });
  1. 将数据发送回主线程： 
  1. // in the web worker, send the generated data back to the main thread
  2. postMessage({t: "export", v: u8 });
  1. 从主线程添加一个事件监听器以写入文件： 
  1. // in the main page
  2. worker.addEventListener('message', function(e) {
  3.   if(e && e.data && e.data.t == "export") {
  4.     e.stopPropagation();
  5.     e.preventDefault();
  6.     // data will be the Uint8Array from the worker
  7.     const data = e.data.v;
  9.     var blob = new Blob([data], {type:"application/octet-stream"});
  10.     var url = URL.createObjectURL(blob);
  11.     var a = document.createElement("a");
  12.     a.download = "SheetJSXPort.xlsx";
  13.     a.href = url;
  14.     document.body.appendChild(a);
  15.     a.click();
  16.   }
  17. });

SWF workaround for Windows 95+ (click to show)

Each moving part in this solution has been deprecated years ago:

  • Adobe stopped supporting Flash Player at the end of 2020
  • Microsoft stopped supporting IE8 in 2019 and stopped supporting IE9 in 2020
  • Downloadify support ended in 2010 and SWFObject support ended in 2016

New projects should strongly consider requiring modern browsers. This info is provided on an “as is” basis and there is no realistic way to provide support given that every related vendor stopped providing support for their software.

XLSX.writeFile techniques work for most modern browsers as well as older IE. For much older browsers, there are workarounds implemented by wrapper libraries.

Downloadify uses a Flash SWF button to generate local files, suitable for environments where ActiveX is unavailable:

  1. Downloadify.create(id,{  /* other options are required! read the downloadify docs for more info */  filename: "test.xlsx",  data: function() { return XLSX.write(wb, {bookType:"xlsx", type:"base64"}); },  append: false,  dataType: "base64"});

The oldie demo shows an IE-compatible fallback scenario.

writeFile 在底层使用 fs.writeFileSync：

  1. var XLSX = require("xlsx");/* output format determined by filename */XLSX.writeFile(workbook, "out.xlsb");

对于 Node ESM，必须手动加载 fs：

  1. import * as fs from "fs";import { writeFile, set_fs } from "xlsx";set_fs(fs);/* output format determined by filename */writeFile(workbook, "out.xlsb");

与 Node ESM 一样，必须手动加载 fs：

  1. import * as fs from "fs";import { writeFile, set_fs } from "xlsx";set_fs(fs);/* output format determined by filename */writeFile(workbook, "out.xlsb");

writeFile 在底层使用 Deno.writeFileSync：

  1. // @deno-types="https://cdn.sheetjs.com/xlsx-0.20.2/package/types/index.d.ts"import * as XLSX from 'https://cdn.sheetjs.com/xlsx-0.20.2/package/xlsx.mjs';XLSX.writeFile(workbook, "test.xlsx");

写入文件的应用必须使用 --allow-write 标志来调用。

writeFile 可以在渲染器进程中使用：

  1. /* From the renderer process */var XLSX = require("xlsx");XLSX.writeFile(workbook, "out.xlsb");

Electron API 随着时间的推移而发生变化。electron 演示 显示了完整的示例并详细说明了所需的特定于版本的设置。

React Native 演示 涵盖经过测试的插件。

writeFile 在 Photoshop 和其他 ExtendScript 目标中封装了 File 逻辑。指定的路径应该是绝对路径：

  1. #include "xlsx.extendscript.js"/* Ask user to select path */var thisFile = File.saveDialog("Select an output file", "*.xlsx;*.xls");/* output format determined by filename */XLSX.writeFile(workbook, thisFile.absoluteURI);

extendscript 演示 包括 Photoshop 和 InDesign 的完整示例。

headless 演示 包含使用 Puppeteer 和其他无头自动化工具将 HTML TABLE 元素转换为 XLSB 工作簿的完整示例。

无头浏览器可能无法访问文件系统，因此 XLSX.writeFile 可能会失败。强烈建议在浏览器上下文中生成文件字节，将字节发送到自动化上下文，然后从自动化写入。

Puppeteer 和 Playwright 是支持二进制字符串的 NodeJS 模块：

  1. /* from the browser context */var bin = XLSX.write(workbook, { type:"binary", bookType: "xlsb" });/* from the automation context */fs.writeFileSync("SheetJSansHead.xlsb", bin, { encoding: "binary" });

PhantomJS fs.write 支持从主进程写入文件。模式 wb 支持二进制字符串：

  1. /* from the browser context */var bin = XLSX.write(workbook, { type:"binary", bookType: "xlsb" });/* from the automation context */fs.write("SheetJSansHead.xlsb", bin, "wb");

示例：服务器响应

此示例重点关注 NodeJS 等服务器端平台中对网络请求的响应。虽然可以在网络浏览器中生成文件，但服务器端文件生成可以实现精确的审计跟踪，并具有更好的移动用户支持。

生产部署应该使用像 ExpressJS 这样的服务器框架。这些代码片段使用底层 API 来进行说明。

对于 Excel 导出（包括 XLSX），Content-Type 标头应设置为 application/vnd.ms-excel。可以使用默认的 application/octet-stream，但 iOS 不会自动建议在 Numbers 或 Excel for iOS 中打开文件

Content-Disposition 标头指示浏览器将响应下载到文件中。标头还可以包含所需的文件名。

  • NodeJS
  • Deno
  • Bun

NodeJS http.ServerResponse#end 可以接受 Buffer 对象。具有 buffer 类型的 XLSX.write 返回 Buffer 对象。

  1. /* generate Buffer */const buf = XLSX.write(wb, { type:"buffer", bookType:"xlsx" });/* prepare response headers */res.statusCode = 200;res.setHeader('Content-Disposition', 'attachment; filename="SheetJSNode.xlsx"');res.setHeader('Content-Type', 'application/vnd.ms-excel');res.end(buf);

Complete Example (click to show)

Install the library with

  1. npm i --save https://cdn.sheetjs.com/xlsx-0.20.2/xlsx-0.20.2.tgz

Save the following script to node.js and run with node node.js:

node.js

  1. const http = require('http');const XLSX = require('xlsx');const hostname = '127.0.0.1';const port = 7262;/* fixed sample worksheet */const wb = XLSX.utils.book_new();XLSX.utils.book_append_sheet(wb, XLSX.utils.aoa_to_sheet([  ["a","b","c"], [1,2,3]]), "Sheet1");const server = http.createServer((req, res) => {  const buf = XLSX.write(wb, { type:"buffer", bookType:"xlsx" });  res.statusCode = 200;  res.setHeader('Content-Disposition', 'attachment; filename="SheetJSNode.xlsx"');  res.setHeader('Content-Type', 'application/vnd.ms-excel');  res.end(buf);});server.listen(port, hostname, () => {  console.log(`Server running at http://${hostname}:${port}/`);});

Deno 响应预计为 Response 对象。XLSX.write 和 buffer 类型返回可以在 Response 中使用的 Uint8Array 对象。

  1. /* generate Buffer */const buf = XLSX.write(wb, { type:"buffer", bookType:"xlsx" });/* return Response */evt.respondWith(new Response(buf, {  status: 200,  headers: {    "Content-Type": "application/vnd.ms-excel",    "Content-Disposition": 'attachment; filename="SheetJSDeno.xlsx"'  }}));

Complete Example (click to show)

Save the following script to deno.ts and run with deno run -A deno.ts. Open a web browser and access http://localhost:7262/ to download the workbook.

deno.ts

  1. // @deno-types="https://cdn.sheetjs.com/xlsx-0.20.2/package/types/index.d.ts"import * as XLSX from 'https://cdn.sheetjs.com/xlsx-0.20.2/package/xlsx.mjs';const wb = XLSX.utils.book_new();XLSX.utils.book_append_sheet(wb, XLSX.utils.aoa_to_sheet([  ["a","b","c"], [1,2,3]]), "Sheet1");async function doNotAwaitThis(conn: Deno.Conn) {  for await (const e of Deno.serveHttp(conn)) e.respondWith(new Response(    XLSX.write(wb, {type:"buffer", bookType:"xlsx"}),    {      status: 200,      headers: {        "Content-Type": "application/vnd.ms-excel",        "Content-Disposition": 'attachment; filename="SheetJSDeno.xlsx"'      }    }  ));}/* standard Deno web server */const server = Deno.listen({ port: 7262 });console.log(`HTTP webserver running.  Access it at:  http://localhost:7262/`);for await (const conn of server) doNotAwaitThis(conn);

Bun 响应预计为 Response 对象。具有 buffer 类型的 XLSX.write 返回可在 Response 构造函数中使用的 Buffer 对象。

  1. /* generate Buffer */const buf = XLSX.write(wb, { type:"buffer", bookType:"xlsx" });/* return Response */return new Response(buf, {  headers: {    "Content-Type": "application/vnd.ms-excel",    "Content-Disposition": 'attachment; filename="SheetJSBun.xlsx"'  }});

Complete Example (click to show)

Download xlsx.mjs. Save the following script to bun.js and run with bun bun.js. Open a web browser and access [http://localhost:7262/](http://localhost:7262/) to download the exported workbook.

bun.js

  1. import * as XLSX from "./xlsx.mjs";/* fixed sample worksheet */const wb = XLSX.utils.book_new();XLSX.utils.book_append_sheet(wb, XLSX.utils.aoa_to_sheet([  ["a","b","c"], [1,2,3]]), "Sheet1");export default {  port: 7262,  fetch(request) {    /* generate Buffer */    const buf = XLSX.write(wb, {type:"buffer", bookType:"xlsx"});    /* return Response */    return new Response(buf, {      headers: {        "Content-Type": "application/vnd.ms-excel",        "Content-Disposition": 'attachment; filename="SheetJSBun.xlsx"'      }    });  },};

示例：远程文件

此示例重点介绍使用 XMLHttpRequest 和 fetch 等 API 以及第三方库上传文件（浏览器用语中的 “Ajax”）。

  • Browser
  • NodeJS

Azure 和 AWS 等某些平台会尝试将 POST 请求正文解析为 UTF-8 字符串，然后用户代码才能看到数据。这将导致服务器解析的数据损坏。有一些解决方法，但最安全的方法是调整服务器进程或 Lambda 函数以接受 Base64 字符串。

HTTP 上传演示 包括使用浏览器 API 和封装器库的示例。

正常情况下，可以从 array 输出生成一个 Blob：

  1. /* in this example, send a Blob to the server */var wbout = XLSX.write(workbook, { bookType: "xlsx", type: "array" });/* prepare data for POST */var blob = new Blob([new Uint8Array(wbout)], {type:"application/octet-stream"});var formdata = new FormData();formdata.append("file", blob, "test.xlsx");/* perform POST request */fetch("/upload", { method: 'POST', body: formdata });

当不支持二进制数据时，应传递 Base64 字符串。这将要求服务器预期并解码数据：

  1. /* in this example, send a Base64 string to the server */var wbout = XLSX.write(workbook, { bookType: "xlsx", type: "base64" });/* prepare data for POST */var formdata = new FormData();formdata.append("file", "test.xlsx"); // <-- server expects `file` to hold nameformdata.append("data", wbout); // <-- `data` holds the data encoded in Base64/* perform POST request */var req = new XMLHttpRequest();req.open("POST", "/upload", true);req.send(formdata);

XLSX.write 和 type: "buffer" 将生成一个 NodeJS Buffer，它可以与标准 NodeJS 方法一起使用来上传数据。

NodeJS 从 18.0 版开始发布，原生支持 fetch：

  1. const XLSX = require("xlsx");async function upload_wb(workbook, url, name="test.xlsx", field="file") {  const buf = XLSX.write(workbook, { bookType: "xlsx", type: "buffer" });  const blob = new Blob([buf], {type:"application/octet-stream"});  const body = new FormData();  body.append(field, blob, name);  /* perform POST request */  return fetch(url, { method: 'POST', body });}

生成 JSON 和 JS 数据

JSON 和 JS 数据往往代表单个工作表。本节中的实用函数适用于单个工作表。

“通用电子表格格式” 部分更详细地描述了对象结构。workbook.SheetNames 是工作表名称的有序列表。workbook.Sheets 是一个对象，其键是工作表名称，其值是工作表对象。

“第一个工作表” 存储在 workbook.Sheets[workbook.SheetNames[0]] 中。

API

从工作表创建 JS 对象数组

  1. var jsa = XLSX.utils.sheet_to_json(worksheet, opts);

从工作表创建 JS 值数组的数组

  1. var aoa = XLSX.utils.sheet_to_json(worksheet, {...opts, header: 1});

sheet_to_json 实用程序函数按行优先顺序遍历工作簿，生成对象数组。第二个 opts 参数控制许多导出决策，包括值的类型（JS 值或格式化文本）。“数组输出” 部分描述了支持的选项。

默认情况下，sheet_to_json 扫描第一行并使用这些值作为标题。使用 header: 1 选项，该函数导出值数组的数组。

示例

示例：数据网格

  • Vanilla JS
  • React
  • VueJS

x-spreadsheet 是一个交互式数据网格，用于在网络浏览器中预览和修改结构化数据。

react-data-grid 是为 React 构建的数据网格。它使用两个属性：数据对象的 rows 和描述列的 columns。网格 API 可以很好地处理数组数组。

该演示首先获取远程文件并使用 XLSX.read 进行提取：

  1. import { useEffect, useState } from "react";import DataGrid from "react-data-grid";import { read, utils } from "xlsx";import 'react-data-grid/lib/styles.css';const url = "https://xlsx.nodejs.cn/pres.xlsx";export default function App() {  const [columns, setColumns] = useState([]);  const [rows, setRows] = useState([]);  useEffect(() => {(async () => {    const wb = read(await (await fetch(url)).arrayBuffer());    /* use sheet_to_json with header: 1 to generate an array of arrays */    const data = utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]], { header: 1 });    /* see react-data-grid docs to understand the shape of the expected data */    setColumns(data[0].map((r) => ({ key: r, name: r })));    setRows(data.slice(1).map((r) => r.reduce((acc, x, i) => {      acc[data[0][i]] = x;      return acc;    }, {})));  })(); });  return <DataGrid columns={columns} rows={rows} />;}

vue3-table-lite 是 VueJS 3 数据表。

示例：数据加载

“TensorFlow.js” 涵盖了从工作表数据生成类型化数组和张量的策略。

Populating a database (SQL or no-SQL) (click to show)

The data demo includes examples of working with databases and query results.

生成 HTML 表格

API

从工作表生成 HTML 表格

  1. var html = XLSX.utils.sheet_to_html(worksheet);

sheet_to_html 实用程序函数根据工作表数据生成 HTML 代码。工作表中的每个单元格都映射到 <TD> 元素。工作表中的合并单元格通过设置 colspan 和 rowspan 属性进行序列化。

示例

sheet_to_html 实用程序函数生成 HTML 代码，可以通过设置 innerHTML 将其添加到任何 DOM 元素：

  1. var container = document.getElementById("tavolo");container.innerHTML = XLSX.utils.sheet_to_html(worksheet);

与 fetch 结合，从工作簿构建站点非常简单：

  • Vanilla JS
  • React
  • VueJS

此示例分配 DIV 元素的 innerHTML：

  1. <body>  <style>TABLE { border-collapse: collapse; } TD { border: 1px solid; }</style>  <div id="tavolo"></div>  <script src="https://cdn.sheetjs.com/xlsx-0.20.2/package/dist/xlsx.full.min.js"></script>  <script type="text/javascript">(async() => {  /* fetch and parse workbook -- see the fetch example for details */  const workbook = XLSX.read(await (await fetch("sheetjs.xlsx")).arrayBuffer());  let output = [];  /* loop through the worksheet names in order */  workbook.SheetNames.forEach(name => {    /* generate HTML from the corresponding worksheets */    const worksheet = workbook.Sheets[name];    const html = XLSX.utils.sheet_to_html(worksheet);    /* add a header with the title name followed by the table */    output.push(`<H3>${name}</H3>${html}`);  });  /* write to the DOM at the end */  tavolo.innerHTML = output.join("\n");})();  </script></body>

通常建议使用 React 友好的工作流程，但可以生成 HTML 并在 React 中使用 dangerouslySetInnerHTML：

  1. import * as XLSX from 'xlsx';function Tabeller(props) {  /* the workbook object is the state */  const [workbook, setWorkbook] = React.useState(XLSX.utils.book_new());  /* fetch and update the workbook with an effect */  React.useEffect(() => { (async() => {    /* fetch and parse workbook -- see the fetch example for details */    setWorkbook(XLSX.read(await (await fetch("sheetjs.xlsx")).arrayBuffer()));  })(); }, []);  return workbook.SheetNames.map(name => ( <>    <h3>name</h3>    <div dangerouslySetInnerHTML={{      /* this __html mantra is needed to set the inner HTML */      __html: XLSX.utils.sheet_to_html(workbook.Sheets[name])    }} />  </> ));}

react 演示 包含更多 React 示例。

通常建议使用 VueJS 友好的工作流程，但可以生成 HTML 并通过 v-html 指令在 VueJS 中使用它：

  1. import { read, utils } from 'xlsx';import { reactive } from 'vue';const S5SComponent = {  mounted() { (async() => {    /* fetch and parse workbook -- see the fetch example for details */    const workbook = read(await (await fetch("sheetjs.xlsx")).arrayBuffer());    /* loop through the worksheet names in order */    workbook.SheetNames.forEach(name => {      /* generate HTML from the corresponding worksheets */      const html = utils.sheet_to_html(workbook.Sheets[name]);      /* add to state */      this.wb.wb.push({ name, html });    });  })(); },  /* this state mantra is required for array updates to work */  setup() { return { wb: reactive({ wb: [] }) }; },  template: `  <div v-for="ws in wb.wb" :key="ws.name">    <h3>{{ ws.name }}</h3>    <div v-html="ws.html"></div>  </div>`};

vuejs 演示 包含更多 React 示例。

生成单个工作表快照

sheet_to_* 函数接受工作表对象。

API

从单个工作表生成 CSV

  1. var csv = XLSX.utils.sheet_to_csv(worksheet, opts);

此快照旨在复制“CSV UTF-8 (.csv)”输出类型。“CSV 和文本” 更详细地描述了该函数和可选的 opts 参数。

从单个工作表生成 “文本”

  1. var txt = XLSX.utils.sheet_to_txt(worksheet, opts);

此快照旨在复制“UTF-16 Text (.txt)”输出类型。“CSV 和文本” 更详细地描述了该函数和可选的 opts 参数。

从单个工作表生成公式列表

  1. var fmla = XLSX.utils.sheet_to_formulae(worksheet);

该快照生成表示嵌入公式的条目数组。数组公式以 range=formula 形式渲染，而普通单元格以 cell=formula or value 形式渲染。字符串字面量以撇号 ' 为前缀，与 Excel 的编辑栏显示一致。

“公式输出” 更详细地描述了该功能。

流式写入

XLSX.stream 对象中提供了流式写入功能。它们采用与普通写入函数相同的参数，但返回 NodeJS 可读流。

  • XLSX.stream.to_csv 是 XLSX.utils.sheet_to_csv 的流式版本。

    ¥XLSX.stream.to_csv is the streaming version of XLSX.utils.sheet_to_csv.

  • XLSX.stream.to_html 是 XLSX.utils.sheet_to_html 的流式版本。

    ¥XLSX.stream.to_html is the streaming version of XLSX.utils.sheet_to_html.

  • XLSX.stream.to_json 是 XLSX.utils.sheet_to_json 的流式版本。

    ¥XLSX.stream.to_json is the streaming version of XLSX.utils.sheet_to_json.

示例包含在 “大型数据集” 中