docs.sheetjs.com/docz/docs/06-solutions/05-output.md

859 lines
25 KiB
Markdown
Raw Permalink Normal View History

2022-05-16 03:26:04 +00:00
---
title: Data Export
2022-05-16 03:26:04 +00:00
sidebar_position: 5
---
2022-06-21 12:26:53 +00:00
import current from '/version.js';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
2023-05-03 03:40:40 +00:00
import CodeBlock from '@theme/CodeBlock';
2022-06-21 12:26:53 +00:00
:::tip pass
The ["Export Tutorial"](/docs/getting-started/examples/export) is a gentle
introduction to data processing and export.
:::
2022-05-16 03:26:04 +00:00
## Writing Workbooks
2022-06-21 12:26:53 +00:00
### API
2022-05-16 03:26:04 +00:00
_Generate spreadsheet bytes (file) from data_
```js
var data = XLSX.write(workbook, opts);
```
The `write` method attempts to package data from the workbook into a file in
memory. By default, XLSX files are generated, but that can be controlled with
the `bookType` property of the `opts` argument. Based on the `type` option,
the data can be stored as a "binary string", JS string, `Uint8Array` or Buffer.
2022-10-30 05:45:37 +00:00
The second `opts` argument is required. ["Writing Options"](/docs/api/write-options)
2022-05-16 03:26:04 +00:00
covers the supported properties and behaviors.
_Generate and attempt to save file_
```js
XLSX.writeFile(workbook, filename, opts);
```
The `writeFile` method packages the data and attempts to save the new file. The
export file format is determined by the extension of `filename` (`SheetJS.xlsx`
signals XLSX export, `SheetJS.xlsb` signals XLSB export, etc).
2022-10-30 05:45:37 +00:00
The second `opts` argument is optional. ["Writing Options"](/docs/api/write-options)
2022-06-21 12:26:53 +00:00
covers the supported properties and behaviors.
2022-05-16 03:26:04 +00:00
_Generate and attempt to save an XLSX file_
```js
XLSX.writeFileXLSX(workbook, filename, opts);
```
The `writeFile` method embeds a number of different export functions. This is
great for developer experience but not amenable to tree shaking using the
current developer tools. When only XLSX exports are needed, this method avoids
referencing the other export functions.
2022-10-30 05:45:37 +00:00
The second `opts` argument is optional. ["Writing Options"](/docs/api/write-options)
2022-05-16 03:26:04 +00:00
covers the supported properties and behaviors.
2023-09-24 03:59:48 +00:00
:::note pass
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
The `writeFile` and `writeFileXLSX` methods uses platform-specific APIs to save
files. The APIs do not generally provide feedback on whether files were created.
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
:::
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
#### Examples
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
Here are a few common scenarios (click on each subtitle to see the code).
2022-05-16 03:26:04 +00:00
2022-10-30 05:45:37 +00:00
The [demos](/docs/demos) cover special deployments in more detail.
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
### Example: Local File
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
`XLSX.writeFile` supports writing local files in platforms like NodeJS. In other
platforms like React Native, `XLSX.write` should be called with file data.
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
<Tabs>
<TabItem value="browser" label="Browser">
2022-05-16 03:26:04 +00:00
`XLSX.writeFile` wraps a few techniques for triggering a file save:
- `URL` browser API creates an object URL for the file, which the library uses
by creating a link and forcing a click. It is supported in modern browsers.
- `msSaveBlob` is an IE10+ API for triggering a file save.
- `IE_FileSave` uses VBScript and ActiveX to write a file in IE6+ for Windows
XP and Windows 7. The shim must be included in the containing HTML page.
There is no standard way to determine if the actual file has been downloaded.
```js
/* output format determined by filename */
XLSX.writeFile(workbook, "out.xlsb");
/* at this point, out.xlsb will have been downloaded */
```
2022-07-17 03:47:27 +00:00
:::caution Web Workers
None of the file writing APIs work from Web Workers. To generate a file:
1) use `XLSX.write` with type `array` to generate a `Uint8Array`:
```js
// in the web worker, generate the XLSX file as a Uint8Array
const u8 = XLSX.write(workbook, { type: "array", bookType: "xlsx" });
```
2) send the data back to the main thread:
```js
// in the web worker, send the generated data back to the main thread
postMessage({t: "export", v: u8 });
```
3) from the main thread, add an event listener to write to file:
```js
// in the main page
worker.addEventListener('message', function(e) {
if(e && e.data && e.data.t == "export") {
e.stopPropagation();
e.preventDefault();
// data will be the Uint8Array from the worker
const data = e.data.v;
var blob = new Blob([data], {type:"application/octet-stream"});
var url = URL.createObjectURL(blob);
var a = document.createElement("a");
a.download = "SheetJSXPort.xlsx";
a.href = url;
document.body.appendChild(a);
a.click();
}
});
```
:::
2022-05-16 03:26:04 +00:00
<details>
2022-06-21 12:26:53 +00:00
<summary><b>SWF workaround for Windows 95+</b> (click to show)</summary>
:::danger pass
2022-06-21 12:26:53 +00:00
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.
:::
2022-05-16 03:26:04 +00:00
`XLSX.writeFile` techniques work for most modern browsers as well as older IE.
For much older browsers, there are workarounds implemented by wrapper libraries.
2023-01-09 17:25:32 +00:00
[`Downloadify`](/docs/demos/frontend/legacy#download-strategies) uses a Flash SWF button
2022-05-16 03:26:04 +00:00
to generate local files, suitable for environments where ActiveX is unavailable:
```js
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"
});
```
2023-01-09 17:25:32 +00:00
The [`oldie` demo](/docs/demos/frontend/legacy#internet-explorer) shows an IE-compatible fallback scenario.
2022-05-16 03:26:04 +00:00
</details>
2022-06-21 12:26:53 +00:00
</TabItem>
<TabItem value="nodejs" label="NodeJS">
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
`writeFile` uses `fs.writeFileSync` under the hood:
2022-05-16 03:26:04 +00:00
```js
2022-06-21 12:26:53 +00:00
var XLSX = require("xlsx");
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
/* output format determined by filename */
XLSX.writeFile(workbook, "out.xlsb");
```
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
For Node ESM, `fs` must be loaded manually:
```js
import * as fs from "fs";
2023-01-09 05:08:30 +00:00
import { writeFile, set_fs } from "xlsx";
2022-07-23 09:06:31 +00:00
set_fs(fs);
/* output format determined by filename */
writeFile(workbook, "out.xlsb");
```
</TabItem>
<TabItem value="bun" label="Bun">
As with Node ESM, `fs` must be loaded manually:
```js
import * as fs from "fs";
2023-01-09 05:08:30 +00:00
import { writeFile, set_fs } from "xlsx";
2022-06-21 12:26:53 +00:00
set_fs(fs);
/* output format determined by filename */
writeFile(workbook, "out.xlsb");
2022-05-16 03:26:04 +00:00
```
2022-06-21 12:26:53 +00:00
</TabItem>
<TabItem value="deno" label="Deno">
`writeFile` uses `Deno.writeFileSync` under the hood:
2023-05-07 13:58:36 +00:00
<CodeBlock language="ts">{`\
2022-06-21 12:26:53 +00:00
// @deno-types="https://cdn.sheetjs.com/xlsx-${current}/package/types/index.d.ts"
import * as XLSX from 'https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs';
2023-05-07 13:58:36 +00:00
\n\
2024-03-22 04:45:40 +00:00
XLSX.writeFile(workbook, "test.xlsx");`}
</CodeBlock>
2022-06-21 12:26:53 +00:00
2023-09-24 03:59:48 +00:00
:::note pass
2022-07-31 23:45:34 +00:00
Applications writing files must be invoked with the `--allow-write` flag.
:::
2022-06-21 12:26:53 +00:00
</TabItem>
<TabItem value="electron" label="Electron">
`writeFile` can be used in the renderer process:
```js
/* From the renderer process */
var XLSX = require("xlsx");
XLSX.writeFile(workbook, "out.xlsb");
```
2024-04-12 01:04:37 +00:00
Electron APIs have changed over time. The [`electron` demo](/docs/demos/desktop/electron)
2022-06-21 12:26:53 +00:00
shows a complete example and details the required version-specific settings.
</TabItem>
<TabItem value="reactnative" label="React Native">
2024-04-12 01:04:37 +00:00
[The React Native Demo](/docs/demos/mobile/reactnative#rn-file-plugins) covers tested plugins.
2022-06-21 12:26:53 +00:00
</TabItem>
<TabItem value="extendscript" label="Photoshop">
`writeFile` wraps the `File` logic in Photoshop and other ExtendScript targets.
The specified path should be an absolute path:
```js
#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);
```
2024-10-26 03:17:31 +00:00
The ["ExtendScript" demo](/docs/demos/extensions/extendscript) includes complete
2024-04-12 01:04:37 +00:00
examples for Photoshop and InDesign.
2022-06-21 12:26:53 +00:00
</TabItem>
<TabItem value="headless" label="Headless">
2022-05-16 03:26:04 +00:00
2024-04-12 01:04:37 +00:00
The [`headless` demo](/docs/demos/net/headless) includes complete
2022-07-07 04:05:14 +00:00
examples of converting HTML TABLE elements to XLSB workbooks using Puppeteer
and other headless automation tools.
Headless browsers may not have access to the filesystem, so `XLSX.writeFile`
may fail. It is strongly recommended to generate the file bytes in the browser
context, send the bytes to the automation context, and write from automation.
2022-05-16 03:26:04 +00:00
2022-07-07 04:05:14 +00:00
Puppeteer and Playwright are NodeJS modules that support binary strings:
2022-05-16 03:26:04 +00:00
```js
2022-07-07 04:05:14 +00:00
/* from the browser context */
var bin = XLSX.write(workbook, { type:"binary", bookType: "xlsb" });
2022-05-16 03:26:04 +00:00
2022-07-07 04:05:14 +00:00
/* from the automation context */
fs.writeFileSync("SheetJSansHead.xlsb", bin, { encoding: "binary" });
2022-05-16 03:26:04 +00:00
```
2022-07-07 04:05:14 +00:00
PhantomJS `fs.write` supports writing files from the main process. The mode
`wb` supports binary strings:
2022-05-16 03:26:04 +00:00
2022-07-07 04:05:14 +00:00
```js
/* from the browser context */
var bin = XLSX.write(workbook, { type:"binary", bookType: "xlsb" });
/* from the automation context */
fs.write("SheetJSansHead.xlsb", bin, "wb");
```
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
</TabItem>
</Tabs>
2022-05-16 03:26:04 +00:00
2022-07-10 22:17:34 +00:00
### Example: Server Responses
This example focuses on responses to network requests in a server-side platform
like NodeJS. While files can be generated in the web browser, server-side file
generation allows for exact audit trails and has better mobile user support.
2023-09-24 03:59:48 +00:00
:::caution pass
2022-07-10 22:17:34 +00:00
Production deployments should use a server framework like ExpressJS. These
snippets use low-level APIs for illustration purposes.
:::
The `Content-Type` header should be set to `application/vnd.ms-excel` for Excel
exports including XLSX. The default `application/octet-stream` can be used, but
iOS will not automatically suggest to open files in Numbers or Excel for iOS
The `Content-Disposition` header instructs browsers to download the response
into a file. The header can also include the desired file name.
<Tabs>
<TabItem value="nodejs" label="NodeJS">
NodeJS `http.ServerResponse#end` can accept `Buffer` objects. `XLSX.write` with
`buffer` type returns `Buffer` objects.
```js
/* 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);
```
<details>
<summary><b>Complete Example</b> (click to show)</summary>
2022-07-10 22:17:34 +00:00
Install the library with
2023-05-07 13:58:36 +00:00
<CodeBlock language="bash">{`\
2023-04-27 09:12:19 +00:00
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2022-07-10 22:17:34 +00:00
Save the following script to `node.js` and run with `node node.js`:
```js title="node.js"
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}/`);
});
```
</details>
</TabItem>
<TabItem value="deno" label="Deno">
2022-10-20 18:47:20 +00:00
Deno responses are expected to be `Response` objects. `XLSX.write` with `buffer`
type returns `Uint8Array` objects that can be used in the `Response`.
2022-07-10 22:17:34 +00:00
2022-10-20 18:47:20 +00:00
```js
/* 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"'
}
}));
```
<details>
<summary><b>Complete Example</b> (click to show)</summary>
2022-10-20 18:47:20 +00:00
Save the following script to `deno.ts` and run with `deno run -A deno.ts`. Open
2022-11-07 10:41:00 +00:00
a web browser and access `http://localhost:7262/` to download the workbook.
2022-10-20 18:47:20 +00:00
2023-05-03 03:40:40 +00:00
<CodeBlock language="ts" title="deno.ts">{`\
// @deno-types="https://cdn.sheetjs.com/xlsx-${current}/package/types/index.d.ts"
import * as XLSX from 'https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs';
\n\
2022-10-20 18:47:20 +00:00
const wb = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(wb, XLSX.utils.aoa_to_sheet([
["a","b","c"], [1,2,3]
]), "Sheet1");
2023-05-03 03:40:40 +00:00
\n\
2022-10-20 18:47:20 +00:00
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"'
}
}
));
}
2023-05-03 03:40:40 +00:00
\n\
2022-10-20 18:47:20 +00:00
/* standard Deno web server */
const server = Deno.listen({ port: 7262 });
2023-05-03 03:40:40 +00:00
console.log(\`HTTP webserver running. Access it at: http://localhost:7262/\`);
for await (const conn of server) doNotAwaitThis(conn);`}
</CodeBlock>
2022-10-20 18:47:20 +00:00
</details>
2022-07-10 22:17:34 +00:00
</TabItem>
<TabItem value="bun" label="Bun">
Bun responses are expected to be `Response` objects. `XLSX.write` with `buffer`
type returns `Buffer` objects that can be used in the `Response` constructor.
```js
/* 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"'
}
});
```
<details>
<summary><b>Complete Example</b> (click to show)</summary>
2022-07-10 22:17:34 +00:00
2023-05-03 03:40:40 +00:00
<p>Download <a href={`https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs`}><code>xlsx.mjs</code></a>.
Save the following script to <code>bun.js</code> and run with <code>bun bun.js</code>. Open a web
browser and access <code>http://localhost:7262/</code> to download the exported workbook.</p>
2022-07-10 22:17:34 +00:00
```js title="bun.js"
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"'
}
});
},
};
```
</details>
2022-07-25 20:48:10 +00:00
</TabItem>
2022-07-10 22:17:34 +00:00
</Tabs>
2022-06-21 12:26:53 +00:00
### Example: Remote File
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
This example focuses on uploading files ("Ajax" in browser parlance) using APIs
like `XMLHttpRequest` and `fetch` as well as third-party libraries.
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
<Tabs>
<TabItem value="browser" label="Browser">
2022-05-16 03:26:04 +00:00
2023-09-24 03:59:48 +00:00
:::caution pass
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
Some platforms like Azure and AWS will attempt to parse POST request bodies as
UTF-8 strings before user code can see the data. This will result in corrupt
data parsed by the server. There are some workarounds, but the safest approach
is to adjust the server process or Lambda function to accept Base64 strings.
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
:::
2022-05-16 03:26:04 +00:00
2024-04-12 01:04:37 +00:00
The [HTTP Uploads demo](/docs/demos/net/upload) includes examples using browser
APIs and wrapper libraries.
2022-08-25 08:22:28 +00:00
Under normal circumstances, a `Blob` can be generated from the `array` output:
2022-05-16 03:26:04 +00:00
```js
2022-08-25 08:22:28 +00:00
/* in this example, send a Blob to the server */
var wbout = XLSX.write(workbook, { bookType: "xlsx", type: "array" });
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
/* prepare data for POST */
2022-08-25 08:22:28 +00:00
var blob = new Blob([new Uint8Array(wbout)], {type:"application/octet-stream"});
2022-06-21 12:26:53 +00:00
var formdata = new FormData();
2022-08-25 08:22:28 +00:00
formdata.append("file", blob, "test.xlsx");
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
/* perform POST request */
2022-08-25 08:22:28 +00:00
fetch("/upload", { method: 'POST', body: formdata });
2022-06-21 12:26:53 +00:00
```
2022-08-25 08:22:28 +00:00
When binary data is not supported, Base64 strings should be passed along. This
will require the server to expect and decode the data:
2022-05-16 03:26:04 +00:00
```js
2022-08-25 08:22:28 +00:00
/* in this example, send a Base64 string to the server */
var wbout = XLSX.write(workbook, { bookType: "xlsx", type: "base64" });
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
/* prepare data for POST */
var formdata = new FormData();
2022-08-25 08:22:28 +00:00
formdata.append("file", "test.xlsx"); // <-- server expects `file` to hold name
formdata.append("data", wbout); // <-- `data` holds the data encoded in Base64
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
/* perform POST request */
2022-08-25 08:22:28 +00:00
var req = new XMLHttpRequest();
req.open("POST", "/upload", true);
req.send(formdata);
2022-05-16 03:26:04 +00:00
```
2022-06-21 12:26:53 +00:00
</TabItem>
<TabItem value="nodejs" label="NodeJS">
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
`XLSX.write` with `type: "buffer"` will generate a NodeJS `Buffer` which can be
used with standard NodeJS approaches for uploading data.
2022-05-16 03:26:04 +00:00
2023-05-07 13:58:36 +00:00
NodeJS releases starting from version 18.0 have native support for fetch:
2022-06-21 12:26:53 +00:00
```js
const XLSX = require("xlsx");
2022-11-12 09:16:51 +00:00
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);
2022-06-21 12:26:53 +00:00
2022-11-12 09:16:51 +00:00
/* perform POST request */
return fetch(url, { method: 'POST', body });
}
2022-06-21 12:26:53 +00:00
```
</TabItem>
</Tabs>
## Generating JSON and JS Data
2022-05-16 03:26:04 +00:00
JSON and JS data tend to represent single worksheets. The utility functions in
this section work with single worksheets.
2022-10-30 05:45:37 +00:00
The ["Common Spreadsheet Format"](/docs/csf/general) section describes
2022-05-16 03:26:04 +00:00
the object structure in more detail. `workbook.SheetNames` is an ordered list
of the worksheet names. `workbook.Sheets` is an object whose keys are sheet
names and whose values are worksheet objects.
The "first worksheet" is stored at `workbook.Sheets[workbook.SheetNames[0]]`.
2022-06-21 12:26:53 +00:00
### API
2022-05-16 03:26:04 +00:00
_Create an array of JS objects from a worksheet_
```js
var jsa = XLSX.utils.sheet_to_json(worksheet, opts);
```
_Create an array of arrays of JS values from a worksheet_
```js
var aoa = XLSX.utils.sheet_to_json(worksheet, {...opts, header: 1});
```
The `sheet_to_json` utility function walks a workbook in row-major order,
generating an array of objects. The second `opts` argument controls a number of
export decisions including the type of values (JS values or formatted text). The
2024-04-12 01:04:37 +00:00
["Array Output"](/docs/api/utilities/array#array-output) section describes
supported options.
2022-05-16 03:26:04 +00:00
By default, `sheet_to_json` scans the first row and uses the values as headers.
With the `header: 1` option, the function exports an array of arrays of values.
#### Examples
2022-06-21 12:26:53 +00:00
### Example: Data Grids
<Tabs>
<TabItem value="js" label="Vanilla JS">
2023-02-28 11:40:44 +00:00
[`x-spreadsheet`](/docs/demos/grid/xs) is an interactive data grid for
previewing and modifying structured data in the web browser.
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
</TabItem>
<TabItem value="react" label="React">
2022-05-16 03:26:04 +00:00
2023-04-19 08:50:07 +00:00
[`react-data-grid`](/docs/demos/grid/rdg) is a data grid built for
2022-11-12 09:16:51 +00:00
React. It uses two properties: `rows` of data objects and `columns` which
describe the columns. The grid API can play nice with an array of arrays.
2022-05-16 03:26:04 +00:00
This demo starts by fetching a remote file and using `XLSX.read` to extract:
```js
import { useEffect, useState } from "react";
import DataGrid from "react-data-grid";
import { read, utils } from "xlsx";
2023-04-19 08:50:07 +00:00
import 'react-data-grid/lib/styles.css';
2024-04-26 04:16:13 +00:00
const url = "https://docs.sheetjs.com/pres.xlsx";
2022-05-16 03:26:04 +00:00
export default function App() {
const [columns, setColumns] = useState([]);
const [rows, setRows] = useState([]);
useEffect(() => {(async () => {
2022-06-21 12:26:53 +00:00
const wb = read(await (await fetch(url)).arrayBuffer());
2022-05-16 03:26:04 +00:00
/* 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} />;
}
```
2022-06-21 12:26:53 +00:00
</TabItem>
<TabItem value="vue" label="VueJS">
2022-05-16 03:26:04 +00:00
2023-04-24 08:50:42 +00:00
[`vue3-table-lite`](/docs/demos/grid/vtl) is a VueJS 3 data table.
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
</TabItem>
</Tabs>
### Example: Data Loading
2022-05-16 03:26:04 +00:00
2024-01-03 06:47:00 +00:00
["TensorFlow.js"](/docs/demos/math/tensorflow) covers strategies for
2022-07-08 00:04:16 +00:00
generating typed arrays and tensors from worksheet data.
2022-05-16 03:26:04 +00:00
<details>
<summary><b>Populating a database (SQL or no-SQL)</b> (click to show)</summary>
2023-02-24 07:46:48 +00:00
The [`data` demo](/docs/demos/data/) includes examples of working with databases and query results.
2022-05-16 03:26:04 +00:00
</details>
2022-06-21 12:26:53 +00:00
## Generating HTML Tables
2022-05-16 03:26:04 +00:00
#### API
_Generate HTML Table from Worksheet_
```js
var html = XLSX.utils.sheet_to_html(worksheet);
```
The `sheet_to_html` utility function generates HTML code based on the worksheet
2024-07-16 01:40:51 +00:00
data. Each cell in the worksheet is mapped to a `<TD>` element.
[Merged cells](/docs/csf/features/merges) are serialized using the TR and TH
`colspan` and `rowspan` attributes.
2022-05-16 03:26:04 +00:00
#### Examples
The `sheet_to_html` utility function generates HTML code that can be added to
any DOM element by setting the `innerHTML`:
```js
var container = document.getElementById("tavolo");
container.innerHTML = XLSX.utils.sheet_to_html(worksheet);
```
Combining with `fetch`, constructing a site from a workbook is straightforward:
2022-06-21 12:26:53 +00:00
<Tabs>
<TabItem value="js" label="Vanilla JS">
This example assigns the `innerHTML` of a DIV element:
2022-05-16 03:26:04 +00:00
2023-05-03 03:40:40 +00:00
<CodeBlock language="html">{`\
2022-05-16 03:26:04 +00:00
<body>
<style>TABLE { border-collapse: collapse; } TD { border: 1px solid; }</style>
<div id="tavolo"></div>
2023-05-03 03:40:40 +00:00
<script src="https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js"></script>
2022-05-16 03:26:04 +00:00
<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());
2023-05-03 03:40:40 +00:00
\n\
2022-05-16 03:26:04 +00:00
let output = [];
/* loop through the worksheet names in order */
workbook.SheetNames.forEach(name => {
2023-05-03 03:40:40 +00:00
\n\
2022-05-16 03:26:04 +00:00
/* generate HTML from the corresponding worksheets */
const worksheet = workbook.Sheets[name];
const html = XLSX.utils.sheet_to_html(worksheet);
2023-05-03 03:40:40 +00:00
\n\
2022-05-16 03:26:04 +00:00
/* add a header with the title name followed by the table */
2023-05-03 03:40:40 +00:00
output.push(\`<H3>\${name}</H3>\${html}\`);
2022-05-16 03:26:04 +00:00
});
/* write to the DOM at the end */
2023-05-03 03:40:40 +00:00
tavolo.innerHTML = output.join("\\n");
2022-05-16 03:26:04 +00:00
})();
</script>
2023-05-03 03:40:40 +00:00
</body>`}
</CodeBlock>
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
</TabItem>
<TabItem value="react" label="React">
2022-05-16 03:26:04 +00:00
It is generally recommended to use a React-friendly workflow, but it is possible
to generate HTML and use it in React with `dangerouslySetInnerHTML`:
```jsx
2022-06-21 12:26:53 +00:00
import * as XLSX from 'xlsx';
2022-05-16 03:26:04 +00:00
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 */
2023-03-12 06:25:57 +00:00
setWorkbook(XLSX.read(await (await fetch("sheetjs.xlsx")).arrayBuffer()));
})(); }, []);
2022-05-16 03:26:04 +00:00
2023-02-28 11:40:44 +00:00
return workbook.SheetNames.map(name => ( <>
2022-05-16 03:26:04 +00:00
<h3>name</h3>
<div dangerouslySetInnerHTML={{
/* this __html mantra is needed to set the inner HTML */
__html: XLSX.utils.sheet_to_html(workbook.Sheets[name])
}} />
2023-02-28 11:40:44 +00:00
</> ));
2022-05-16 03:26:04 +00:00
}
```
2023-01-09 17:25:32 +00:00
The [`react` demo](/docs/demos/frontend/react) includes more React examples.
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
</TabItem>
<TabItem value="vue" label="VueJS">
2022-05-16 03:26:04 +00:00
It is generally recommended to use a VueJS-friendly workflow, but it is possible
to generate HTML and use it in VueJS with the `v-html` directive:
```jsx
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>`
};
```
2023-01-09 17:25:32 +00:00
The [`vuejs` demo](/docs/demos/frontend/vue) includes more React examples.
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
</TabItem>
</Tabs>
2022-05-16 03:26:04 +00:00
2022-06-21 12:26:53 +00:00
## Generating Single-Worksheet Snapshots
2022-05-16 03:26:04 +00:00
The `sheet_to_*` functions accept a worksheet object.
#### API
_Generate a CSV from a single worksheet_
```js
var csv = XLSX.utils.sheet_to_csv(worksheet, opts);
```
2022-08-25 08:22:28 +00:00
This snapshot is designed to replicate the "CSV UTF-8 (`.csv`)" output type.
2023-05-27 23:07:45 +00:00
["CSV and Text"](/docs/api/utilities/csv) describes the function and the
optional `opts` argument in more detail.
2022-05-16 03:26:04 +00:00
_Generate "Text" from a single worksheet_
```js
var txt = XLSX.utils.sheet_to_txt(worksheet, opts);
```
2022-08-25 08:22:28 +00:00
This snapshot is designed to replicate the "UTF-16 Text (`.txt`)" output type.
2023-05-27 23:07:45 +00:00
["CSV and Text"](/docs/api/utilities/csv) describes the function and the
optional `opts` argument in more detail.
2022-05-16 03:26:04 +00:00
_Generate a list of formulae from a single worksheet_
```js
var fmla = XLSX.utils.sheet_to_formulae(worksheet);
```
This snapshot generates an array of entries representing the embedded formulae.
Array formulae are rendered in the form `range=formula` while plain cells are
rendered in the form `cell=formula or value`. String literals are prefixed with
an apostrophe `'`, consistent with Excel's formula bar display.
2023-05-15 08:38:23 +00:00
["Formulae Output"](/docs/api/utilities/formulae) describes the function in more detail.
2022-06-21 12:26:53 +00:00
## Streaming Write
The streaming write functions are available in the `XLSX.stream` object. They
take the same arguments as the normal write functions but return a NodeJS
Readable Stream.
- `XLSX.stream.to_csv` is the streaming version of `XLSX.utils.sheet_to_csv`.
- `XLSX.stream.to_html` is the streaming version of `XLSX.utils.sheet_to_html`.
- `XLSX.stream.to_json` is the streaming version of `XLSX.utils.sheet_to_json`.
2024-07-18 22:19:02 +00:00
- `XLSX.stream.to_xlml` is the streaming SpreadsheetML2003 workbook writer.
2022-06-21 12:26:53 +00:00
2024-07-18 22:19:02 +00:00
["Stream Export"](/docs/api/stream) describes the function in more detail.