sheetjs/docs.sheetjs.com
1
Fork 4
Code Issues 2 Pull Requests 1 Projects Releases Wiki Activity

nits

Browse Source
This commit is contained in:
SheetJS 2022-10-19 17:12:12 -04:00
parent a6a981226f
commit 22720fd7a6
3 changed files with 142 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docz/docs/03-demos/04-grid.md
View File

@ -202,7 +202,7 @@ many additional features including massive data streaming, sorting and styling.
### Tabulator
[Tabulator](http://tabulator.info/docs/5.3/download#xlsx) includes deep support
[Tabulator](https://tabulator.info/docs/5.4/download#xlsx) includes deep support
through a special Export button. It handles the SheetJS operations internally.

18
docz/docs/03-demos/07-worker.md
View File

@ -100,7 +100,8 @@ In the following example, the script:
- generates a workbook object in the Web Worker
- generates a XLSB file using `XLSX.write` in the Web Worker
- sends the file (`Uint8Array`) to the main browser context
- generates an object URL in the Web Worker
- sends the object URL to the main browser context
- performs a download action in the main browser context
```jsx live
@ -124,11 +125,14 @@ SheetJS,in,Web,Workers
1,2,3,4\`;
const wb = XLSX.read(csv, { type: "string" });
/* Write XLSB data */
/* Write XLSB data (Uint8Array) */
const u8 = XLSX.write(wb, { bookType: "xlsb", type: "buffer" });
/* Generate URL */
const url = URL.createObjectURL(new Blob([u8]));
/* Reply with result */
postMessage({data: u8});
postMessage({ url });
} catch(e) {
/* Pass the error message back */
postMessage({error: String(e.message || e).bold() });
@ -142,7 +146,7 @@ SheetJS,in,Web,Workers
/* this mantra is the standard HTML5 download attribute technique */
const a = document.createElement("a");
a.download = "SheetJSWriteFileWorker.xlsb";
a.href = URL.createObjectURL(new Blob([e.data.data]));
a.href = e.data.url;
document.body.appendChild(a);
a.click();
document.body.removeChild(a);
@ -176,10 +180,10 @@ In the following example, the script:
```jsx live
function SheetJSDragDropWorker() {
const [html, setHTML] = React.useState("");
/* suppress default behavior for dragover and drop */
/* suppress default behavior for drag and drop */
function suppress(e) { e.stopPropagation(); e.preventDefault(); }
return ( <>
<div onDragOver={suppress} onDrop={(e) => {
<div onDragOver={suppress} onDragEnter={suppress} onDrop={(e) => {
suppress(e);
/* this mantra embeds the worker source in the function */
@ -188,7 +192,7 @@ function SheetJSDragDropWorker() {
importScripts("https://cdn.sheetjs.com/xlsx-latest/package/dist/xlsx.full.min.js");
/* this callback will run once the main context sends a message */
self.addEventListener('message', async(e) => {
self.addEventListener('message', (e) => {
try {
/* Read file data */
const ab = new FileReaderSync().readAsArrayBuffer(e.data.file);

199
docz/docs/03-demos/33-localfile.md
View File

@ -2,10 +2,11 @@
title: Local File Access
---
Reading and writing files require native support. `readFile` and `writeFile`
include support for some approaches but do not support every API. When an API
is not supported by `readFile` or `writeFile`, the underlying `read` and
`write` methods can be used.
Reading and writing files require native platform support. `XLSX.readFile` and
`XLSX.writeFile` include support for some APIs.
For other APIs, user code can pass data to `XLSX.read` or use data generated by
`XLSX.write` directly. Both methods work with a number of common storage types.
This demo looks at various web APIs. More specific approaches for deployments
like mobile apps are covered in their respective demos.
@ -35,20 +36,63 @@ Modern browser APIs typically use typed arrays or `Blob` or `File` structures.
_Reading Binary Data_
Given a `Blob` or `File`, the underlying data cannot be read synchronously!
`XLSX.read` supports `Uint8Array` and `ArrayBuffer` data. For `Blob` or `File`
objects, the underlying data must be pulled into an `ArrayBuffer`.
The callback-based approach uses a `FileReader`:
```js
const reader = new FileReader();
reader.onload = function(e) {
/* e.target.result is an ArrayBuffer */
const wb = XLSX.read(e.target.result);
console.log(XLSX.utils.sheet_to_csv(wb.Sheets[wb.SheetNames[0]]));
// usage: file_to_wb(file, function(wb) { /* wb is a workbook object */ });
function file_to_wb(file, callback) {
var reader = new FileReader();
reader.onload = function(e) {
/* e.target.result is an ArrayBuffer */
callback(XLSX.read(e.target.result));
};
reader.readAsArrayBuffer(file);
}
reader.readAsArrayBuffer(file);
```
<details><summary><b>FileReaderSync in Web Workers</b> (click to show)</summary>
`FileReaderSync` is only available in Web Workers:
```js
// assuming main thread called worker.postMessage({ file: file_object })
self.addEventListener('message', (e) => {
/* get file object from message */
var file = e.data.file;
/* Read file data */
const ab = new FileReaderSync().readAsArrayBuffer(file);
/* Parse file */
const wb = XLSX.read(ab);
/* DO SOMETHING WITH wb HERE */
});
```
["User-Submitted File" example](./worker#user-submitted-file) has a live demo.
</details>
<details><summary><b>IE10 Binary Strings</b> (click to show)</summary>
In IE10, binary strings are more performant than `ArrayBuffer`. `XLSX.read`
supports binary strings with `type: "binary"`:
```js
// usage: file_bs_to_wb(file, function(wb) { /* wb is a workbook object */ });
function file_bs_to_wb(file, callback) {
var reader = new FileReader();
reader.onload = function(e) {
/* e.target.result is a binary string */
callback(XLSX.read(e.target.result, { type: "binary" }));
};
reader.readAsBinaryString(file);
}
```
</details>
The Promise-based approach uses `Blob#arrayBuffer`:
```js
@ -60,8 +104,9 @@ async function blob_to_wb(blob) {
_Writing Binary Data_
`XLSX.write` can generate `Uint8Array` results by passing `type: "buffer"`. A
`Blob` can be created by using the constructor:
`XLSX.write` can generate `Uint8Array` results by passing `type: "buffer"`.
A `Blob` can be created by using the constructor:
```js
const u8 = XLSX.write(workbook, { type: "buffer", bookType: "xlsx" });
@ -78,6 +123,17 @@ _Writing Files_
XLSX.writeFile(wb, "SheetJS.xlsx");
```
:::caution Web Workers
`XLSX.writeFile` requires DOM access and will not work in a Web Worker!
The workaround is to generate the file data from the Worker (using `XLSX.write`)
and send the data back to the main context for the actual download action.
["Creating a Local File" includes a live demo](./worker#creating-a-local-file).
:::
## File API
_Reading Files_
@ -93,7 +149,7 @@ async function handleFileAsync(e) {
/* data is an ArrayBuffer */
const workbook = XLSX.read(data);
/* do something with the workbook here */
console.log(XLSX.utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]]))
console.log(XLSX.utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]]));
}
input_dom_element.addEventListener("change", handleFileAsync, false);
```
@ -105,8 +161,12 @@ _Reading Files_
The `dataTransfer` property of the `drop` event holds a list of files:
```js
/* suppress default behavior for drag and drop events */
function suppress(e) { e.stopPropagation(); e.preventDefault(); }
/* handle data from drop event */
async function handleDropAsync(e) {
e.stopPropagation(); e.preventDefault();
suppress(e);
/* get first file */
const f = e.dataTransfer.files[0];
/* get raw data */
@ -114,9 +174,12 @@ async function handleDropAsync(e) {
/* data is an ArrayBuffer */
const wb = XLSX.read(data);
/* do something with the workbook here */
console.log(XLSX.utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]]))
console.log(XLSX.utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]]));
}
drop_dom_element.addEventListener("drop", handleDropAsync, false);
drop_dom_element.addEventListener("dragover", suppress, false);
drop_dom_element.addEventListener("dragenter", suppress, false);
```
## File System Access API
@ -128,6 +191,45 @@ the feature in version 86. Safari did not support File System Access API.
:::
<details><summary><b>Live Example</b> (click to show) </summary>
This live example reads a file then tries to save as XLSX.
```jsx live
function SheetJSRoundTripFileSystemAPI() { return ( <button onClick={async () => {
/* Show picker and get data */
const [rFile] = await window.showOpenFilePicker({
types: [{
description: 'Spreadsheets',
accept: { 'application/vnd.ms-excel': ['.xlsx', '.xls', '.xlsb', /*...*/] }
}],
excludeAcceptAllOption: true,
multiple: false
});
const ab = await (await rFile.getFile()).arrayBuffer();
/* parse */
const wb = XLSX.read(ab);
/* Show picker and get handle to file */
const wFile = await window.showSaveFilePicker({
suggestedName: "SheetJSRT.xlsx",
types: [ { description: 'XLSX', accept: { 'application/vnd.ms-excel': ['.xlsx'] } } ]
});
const wstream = await wFile.createWritable();
/* write */
const buf = XLSX.write(wb, { bookType: "xlsx", type: "buffer" });
wstream.write(buf);
/* close stream to commit file */
wstream.close();
}}>Click to read then save as XLSX</button> ) }
```
</details>
_Reading Files_
`window.showOpenFilePicker` shows a file picker and resolves to an array of
@ -182,47 +284,6 @@ wstream.write(XLSX.write(wb, { bookType: ext, type: "buffer" }))
wstream.close();
```
### Demo
<details><summary><b>Live Example</b> (click to show) </summary>
This live example reads a file then tries to save as XLSX.
```jsx live
function SheetJSRoundTripFileSystemAPI() { return ( <button onClick={async () => {
/* Show picker and get data */
const [rFile] = await window.showOpenFilePicker({
types: [{
description: 'Spreadsheets',
accept: { 'application/vnd.ms-excel': ['.xlsx', '.xls', '.xlsb', /*...*/] }
}],
excludeAcceptAllOption: true,
multiple: false
});
const ab = await (await rFile.getFile()).arrayBuffer();
/* parse */
const wb = XLSX.read(ab);
/* Show picker and get handle to file */
const wFile = await window.showSaveFilePicker({
suggestedName: "SheetJSRT.xlsx",
types: [ { description: 'XLSX', accept: { 'application/vnd.ms-excel': ['.xlsx'] } } ]
});
const wstream = await wFile.createWritable();
/* write */
const buf = XLSX.write(wb, { bookType: "xlsx", type: "buffer" });
wstream.write(buf);
/* close stream to commit file */
wstream.close();
}}>Click to read then save as XLSX</button> ) }
```
</details>
## File and Directory Entries API
:::caution Deprecated
@ -263,7 +324,8 @@ Internet Explorer offered proprietary APIs that were not adopted by Chromium.
_Writing Files_
IE10 and IE11 support `navigator.msSaveBlob`. `writeFile` will use the method.
IE10 and IE11 support `navigator.msSaveBlob`. `XLSX.writeFile` will use this
method if it is available.
#### VBScript
@ -304,8 +366,8 @@ import { readFile, writeFile, set_fs } from 'xlsx';
import * as fs from 'fs';
set_fs(fs);
var wb = XLSX.readFile("sheetjs.numbers");
XLSX.writeFile(wb, "sheetjs.xlsx");
var wb = readFile("sheetjs.numbers");
writeFile(wb, "sheetjs.xlsx");
```
### ExtendScript
@ -322,8 +384,7 @@ XLSX.writeFile(wb, "sheetjs.csv");
### Deno
`Deno.readFileSync` and `Deno.writeFileSync` are supported by `readFile` and
`writeFile` out of the box:
`readFile` uses `Deno.readFileSync` and `writeFile` uses `Deno.writeFileSync`:
```js
// @deno-types="https://cdn.sheetjs.com/xlsx-latest/package/types/index.d.ts"
@ -333,11 +394,11 @@ const wb = XLSX.readFile("sheetjs.numbers");
XLSX.writeFile(wb, "sheetjs.xlsx");
```
:::note
:::caution Deno entitlements
Any script using `XLSX.readFile` requires the `--allow-read` permission.
Any Deno script using `XLSX.readFile` requires the `--allow-read` entitlement.
Any script using `XLSX.writeFile` requires the `--allow-write` permission.
Any Deno script using `XLSX.writeFile` requires the `--allow-write` entitlement.
:::
@ -346,12 +407,12 @@ Any script using `XLSX.writeFile` requires the `--allow-write` permission.
Bun requires the `fs` module:
```js
import * as XLSX from 'xlsx';
import { readFile, writeFile, set_fs } from 'xlsx';
import * as fs from 'fs';
XLSX.set_fs(fs);
set_fs(fs);
var wb = XLSX.readFile("sheetjs.numbers");
XLSX.writeFile(wb, "sheetjs.xlsx");
var wb = readFile("sheetjs.numbers");
writeFile(wb, "sheetjs.xlsx");
```
### Apps