From efc57df123eb01bdeb0a0a9e669cd2c4e7fdfefb Mon Sep 17 00:00:00 2001 From: SheetJS Date: Wed, 14 Jun 2023 15:32:34 -0400 Subject: [PATCH] aoa --- .../01-installation/02-frameworks.md | 70 +++++- docz/docs/03-demos/04-static/05-vitejs.md | 2 +- docz/docs/07-csf/07-features/02-hyperlinks.md | 21 +- docz/docs/07-csf/07-features/04-comments.md | 19 +- docz/docs/07-csf/07-features/05-names.md | 4 +- docz/docs/07-csf/07-features/07-vba.md | 4 +- docz/docs/08-api/07-utilities/01-array.md | 234 +++++++++++++++--- 7 files changed, 296 insertions(+), 58 deletions(-) diff --git a/docz/docs/02-getting-started/01-installation/02-frameworks.md b/docz/docs/02-getting-started/01-installation/02-frameworks.md index 3582658..5a8f594 100644 --- a/docz/docs/02-getting-started/01-installation/02-frameworks.md +++ b/docz/docs/02-getting-started/01-installation/02-frameworks.md @@ -7,17 +7,22 @@ sidebar_custom_props: --- import current from '/version.js'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; # Frameworks and Bundlers -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - Each standalone release package is available at . The NodeJS package is designed to be used with frameworks and bundlers. It is a proper ECMAScript Module release which can be optimized with developer tools. +

https://cdn.sheetjs.com/xlsx-{current}/xlsx-{current}.tgz is the URL for version {current}

+ +## Installation + +Tarballs can be directly installed using a package manager: + {`\ @@ -42,8 +47,7 @@ Once installed, the library can be imported under the name `xlsx`: import { read, writeFileXLSX } from "xlsx"; ``` -The ["Bundlers" demo](/docs/demos/bundler) includes examples for specific -bundler tools. +The ["Bundlers" demo](/docs/demos/bundler) includes examples for specific tools. :::info @@ -100,6 +104,62 @@ in `package.json` can control module resolution: ::: +### Vendoring + +For general stability, "vendoring" modules is the recommended approach: + +

1) Download the tarball (xlsx-{current}.tgz) for the desired version. The current + version is available at https://cdn.sheetjs.com/xlsx-{current}/xlsx-{current}.tgz

+ +2) Create a `vendor` subfolder at the root of your project and move the tarball + to that folder. Add it to your project repository. + +3) Install the tarball using a package manager: + + + +{`\ +npm i --save file:vendor/xlsx-${current}.tgz`} + + + +{`\ +pnpm install file:vendor/xlsx-${current}.tgz`} + + + +{`\ +yarn add file:vendor/xlsx-${current}.tgz`} + + + + +The package will be installed and accessible as `xlsx`. + +## Usage + +With most frameworks and bundler tools, named imports are recommended: + +```js +import { read, utils } from 'xlsx'; +``` + +Some legacy bundlers require the glob import: + +```js +import * as XLSX from 'xlsx'; +const { read, utils } = XLSX; +``` + +For legacy bundlers that support CommonJS, `require` will work: + +```js +var XLSX = require("xlsx"); +var read = XLSX.read, utils = XLSX.utils; +``` + +The ["Bundlers" demo](/docs/demos/bundler) includes examples for specific tools. + ## Encoding support If Encoding support is required, `cpexcel.full.mjs` must be manually imported: diff --git a/docz/docs/03-demos/04-static/05-vitejs.md b/docz/docs/03-demos/04-static/05-vitejs.md index f159339..d64ad37 100644 --- a/docz/docs/03-demos/04-static/05-vitejs.md +++ b/docz/docs/03-demos/04-static/05-vitejs.md @@ -336,7 +336,7 @@ npx http-server dist/ The terminal will display a URL ( `http://127.0.0.1:8080` ). Access that page with a web browser. -11) To confirm that only the raw data is present in the page, view the page +11) To confirm that the object data is not present in the page, view the page source. The code will reference some script like `/assets/index-HASH.js`. Open that script. Searching for `Bill Clinton` should yield no results. Searching for `BESSELJ` should match the code: diff --git a/docz/docs/07-csf/07-features/02-hyperlinks.md b/docz/docs/07-csf/07-features/02-hyperlinks.md index 1045fe3..4652935 100644 --- a/docz/docs/07-csf/07-features/02-hyperlinks.md +++ b/docz/docs/07-csf/07-features/02-hyperlinks.md @@ -7,17 +7,18 @@ sidebar_position: 2
File Format Support (click to show) -| Formats | Link | Tooltip | Storage Representation | -|:------------------|:-----:|:-------:|:-----------------------| -| XLSX / XLSM | ✔ | ✔ | Cell Link + Tooltip | -| XLSB | ✔ | ✔ | Cell Link + Tooltip | -| XLS (BIFF8) | ✔ | ✔ | Cell Link + Tooltip | -| XLML | ✔ | ✔ | Cell Link + Tooltip | -| ODS / FODS / UOS | ✔ | | Span Link + Tooltip | -| HTML | ✔ | * | Span Link | -| NUMBERS | | * | Span Link ** | +| Formats | Link | Tooltip | Link Type | +|:------------------|:-----:|:-------:|:----------| +| XLSX / XLSM | ✔ | ✔ | Cell Link | +| XLSB | ✔ | ✔ | Cell Link | +| XLS (BIFF8) | ✔ | ✔ | Cell Link | +| XLML | ✔ | ✔ | Cell Link | +| ODS / FODS / UOS | ✔ | | Span Link | +| HTML | ✔ | ✕ | Span Link | +| NUMBERS | ✔ | ✕ | Span Link | -Asterisks (*) mark features that are not supported by the file formats. +X (✕) marks features that are not supported by the file formats. For example, +the NUMBERS file format does not support custom tooltips. For "Span Link" formats, parsers apply the first hyperlink to the entire cell and writers apply the hyperlink to the entire cell text. diff --git a/docz/docs/07-csf/07-features/04-comments.md b/docz/docs/07-csf/07-features/04-comments.md index 1bf10f4..36213c0 100644 --- a/docz/docs/07-csf/07-features/04-comments.md +++ b/docz/docs/07-csf/07-features/04-comments.md @@ -20,7 +20,7 @@ allow users to "reply". The original "Comments" were renamed to "Notes". |:------------------|:-----:|:-------:|:--------:| | XLSX / XLSM | ✕ | ✔ | ✔ | | XLSB | ✕ | R | R | -| NUMBERS | ✕ | ✕ | R | +| NUMBERS | ✕ | ✕ | ✔ | | XLS (BIFF8) | ✕ | ✔ | ✕ | | XLML | ✕ | ✔ | ✕ | | ODS / FODS / UOS | ✕ | ✔ | ✕ | @@ -54,7 +54,9 @@ field is the plain text representation. For example, the following snippet appends a cell comment into cell `A1`: ```js +/* get cell A1, creating an empty cell if necessary */ var cell = ws["A1"]; +if(!ws["A1"]) ws["A1"] = { t: "z" }; /* create comment array if it does not exist */ if(!cell.c) cell.c = []; @@ -137,7 +139,8 @@ function SheetJSParseComments(props) { ## Visibility -To mark a comment as normally hidden, set the `hidden` property: +The `hidden` property of the comment block indicates comment visibility. If set +to `true`, the comment will not be visible until users hover over the comment. ```js if(!cell.c) cell.c = []; @@ -171,8 +174,8 @@ function SheetJSComments2() { ## Threaded Comments -Introduced in Excel 365, threaded comments are plain text comment snippets with -author metadata and parent references. They are supported in XLSX and XLSB. +Threaded comments are plain text comment snippets with author metadata and +parent references. They are supported in XLSX, XLSB, and NUMBERS files. To mark a comment as threaded, each comment part must have a true `T` property: @@ -202,16 +205,15 @@ There is no Active Directory or Office 365 metadata associated with authors. ```jsx live function SheetJSComments2() { - return (); + }}>Click me to generate a sample file ); } - ```
diff --git a/docz/docs/07-csf/07-features/05-names.md b/docz/docs/07-csf/07-features/05-names.md index 034ba4a..eff370c 100644 --- a/docz/docs/07-csf/07-features/05-names.md +++ b/docz/docs/07-csf/07-features/05-names.md @@ -19,10 +19,10 @@ Defined names have evolved over the decades, with new features added over time: | XLSB | ✔ | ✔ | ✔ | | XLS | ✔ | ✔ | ✔ | | XLML | ✔ | ✔ | | -| SYLK | ✔ | * | | +| SYLK | ✔ | ✕ | | | ODS / FODS / UOS | ✔ | ✔ | | -Asterisks (*) mark features that are not supported by the file formats. There is +X (✕) marks features that are not supported by the file formats. There is no way to specify a Unicode defined name in the SYLK format. diff --git a/docz/docs/07-csf/07-features/07-vba.md b/docz/docs/07-csf/07-features/07-vba.md index d7178a1..38b2ab3 100644 --- a/docz/docs/07-csf/07-features/07-vba.md +++ b/docz/docs/07-csf/07-features/07-vba.md @@ -18,11 +18,11 @@ identical to XLSX and supports macros. | Formats | Basic | Storage Representation | |:--------|:-----:|:-----------------------------------| | XLSM | ✔ | `vbaProject.bin` file in container | -| XLSX | * | Not supported in format (use XLSM) | +| XLSX | ✕ | Not supported in format (use XLSM) | | XLSB | ✔ | `vbaProject.bin` file in container | | XLS | ✔ | Intercalated in CFB container | -Asterisks (*) mark features that are not supported by the file formats. There is +X (✕) marks features that are not supported by the file formats. There is no way to embed VBA in the XLSX format. diff --git a/docz/docs/08-api/07-utilities/01-array.md b/docz/docs/08-api/07-utilities/01-array.md index 420788c..49e3ebe 100644 --- a/docz/docs/08-api/07-utilities/01-array.md +++ b/docz/docs/08-api/07-utilities/01-array.md @@ -6,14 +6,101 @@ title: Arrays of Data import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +export const r = {style: {backgroundColor:"red"}}; +export const b = {style: {backgroundColor:"blue"}}; +export const g = {style: {backgroundColor:"green"}}; +export const y = {style: {backgroundColor:"yellow"}}; + Arrays of objects are a common data format in JavaScript database connectors and other general data sources. Numeric datasets commonly use arrays of arrays of numbers. +The ["Data Storage"](#data-storage) section gives a general overview of common +array formats in JavaScript. + +The ["Functions"](#functions) section describes the related functions. + +## Data Storage + +### Array of Arrays + +The spiritual equivalent of the grid in JavaScript is an array of arrays: + +
SpreadsheetArray of Arrays
+ +![`pres.xlsx` data](pathname:///pres.png) + + + +```js +[ + ["Name", "Index"], + ["Bill Clinton", 42], + ["GeorgeW Bush", 43], + ["Barack Obama", 44], + ["Donald Trump", 45], + ["Joseph Biden", 46] +] +``` + +
+ +Each array within the structure corresponds to one row. Individual data points +can be read by indexing by row index and by column index: + +```js +var aoa = [ + ["Name", "Index"], + ["Bill Clinton", 42], + ["GeorgeW Bush", 43], + ["Barack Obama", 44], + ["Donald Trump", 45], + ["Joseph Biden", 46] +]; + +var value_at_B4 = aoa[3][1]; // 44 +var value_at_A2 = aoa[1][0]; // Bill Clinton +``` + +### Arrays of Objects + +Arrays of objects are commonly used to represent rows from a database: + +
SpreadsheetArray of Objects
+ +![`pres.xlsx` data](pathname:///pres.png) + + + +```js +[ + { Name: "Bill Clinton", Index: 42 }, + { Name: "GeorgeW Bush", Index: 43 }, + { Name: "Barack Obama", Index: 44 }, + { Name: "Donald Trump", Index: 45 }, + { Name: "Joseph Biden", Index: 46 } +] +``` + +
+ +Each object within the structure corresponds to one data row. The first row of +the spreadsheet is interpreted as the header row. + +## Functions + +The "Input" subsections describe functions that generate SheetJS worksheet +objects from arrays of data. + +The ["Array Output"](#array-output) subsection defines functions that extract +data from SheetJS worksheet objects. + +#### Example Sheet + :::note -The examples are based on the following worksheet: +The live examples are based on the following worksheet: @@ -23,9 +110,12 @@ The examples are based on the following worksheet:
SheetJS
4567890
+This table includes duplicate column labels ("e" and "S" appear twice in the +first row) and gaps (three data rows have missing fields). + ::: -## Array of Arrays Input +### Array of Arrays Input **Create a worksheet from an array of arrays** @@ -51,16 +141,27 @@ The function takes an options argument: |`sheetStubs` | false | Create cell objects of type `z` for `null` values | |`nullError` | false | If true, emit `#NULL!` error cells for `null` values | -The example worksheet can be generated with: +The following live example reproduces the [example worksheet](#example-sheet): -```js -var ws = XLSX.utils.aoa_to_sheet([ - ["S", "h", "e", "e", "t", "J", "S"], - [ 1, 2, , , 5, 6, 7], - [ 2, 3, , , 6, 7, 8], - [ 3, 4, , , 7, 8, 9], - [ 4, 5, 6, 7, 8, 9, 0] -]); +```jsx live +function SheetJSExportAOA() { + /* array of arrays of data */ + var aoa = [ + ["S", "h", "e", "e", "t", "J", "S"], + [ 1, 2, , , 5, 6, 7], + [ 2, 3, , , 6, 7, 8], + [ 3, 4, , , 7, 8, 9], + [ 4, 5, 6, 7, 8, 9, 0] + ]; + return ( ); +} ``` **Add data from an array of arrays to an existing worksheet** @@ -92,7 +193,29 @@ accepts an options argument: | (default) | Start from cell `A1` | -The example worksheet can be built up in the order `A1:G1, A2:B4, E2:G4, A5:G5`: +The [example worksheet](#example-sheet) can be built up in the following order: + +
SpreadsheetOperations
+ + + + + + + +
SheetJS
12 567
23 678
34 789
4567890
+ +		 + +1) `aoa_to_sheet` writes `A1:G1` (red) + +2) `sheet_add_aoa` writes `A2:B4` (blue) + +3) `sheet_add_aoa` writes `E2:G4` (green) + +4) `sheet_add_aoa` writes `A5:G5` (yellow) + +
```js /* Initial row */ @@ -108,7 +231,28 @@ XLSX.utils.sheet_add_aoa(ws, [[5,6,7], [6,7,8], [7,8,9]], {origin:{r:1, c:4}}); XLSX.utils.sheet_add_aoa(ws, [[4,5,6,7,8,9,0]], {origin: -1}); ``` -## Array of Objects Input +```jsx live +function SheetJSAddAOA() { return ( ); } +``` + +### Array of Objects Input **Create a worksheet from an array of objects** @@ -163,29 +307,61 @@ const aoo = data.map(obj => Object.fromEntries(Object.entries(obj).filter(r => h - Null values will be skipped by default. If `nullError` is true, an error cell corresponding to `#NULL!` will be written to the worksheet. -The example sheet cannot be reproduced using plain objects since JS object keys -must be unique. After replacing the second `e` and `S` with `e_1` and `S_1`: +```jsx live +function SheetJSExportAOO() { + /* array of arrays of data */ + var aoo = [ + { Name: "Bill Clinton", Index: 42 }, + { Name: "GeorgeW Bush", Index: 43 }, + { Name: "Barack Obama", Index: 44 }, + { Name: "Donald Trump", Index: 45 }, + { Name: "Joseph Biden", Index: 46 } + ]; + return ( ); +} +``` + + +:::info + +The [example sheet](#example-sheet) cannot be reproduced using plain objects +since JS object keys must be unique. + +Typically the original data source will have different column names. After +writing with `json_to_sheet`, the `aoa_to_sheet` method can rewrite the headers: ```js -var ws = XLSX.utils.json_to_sheet([ +/* original array of objects */ +var data = [ { S:1, h:2, t:5, J:6, S_1:7 }, { S:2, h:3, t:6, J:7, S_1:8 }, { S:3, h:4, t:7, J:8, S_1:9 }, { S:4, h:5, e:6, e_1:7, t:8, J:9, S_1:0 }, -], {header:["S","h","e","e_1","t","J","S_1"]}); +]; + +/* column order for the generated worksheet */ +// | A | B | C | D | E | F | G | +var data_headers = [ "S", "h", "e", "e_1", "t", "J", "S_1" ]; + +/* new headers for the first row of the worksheet */ +// | A | B | C | D | E | F | G | +var new_headers = [ "S", "h", "e", "e", "t", "J", "S" ]; + +/* write data with using data headers */ +var ws = XLSX.utils.json_to_sheet(data, { header: data_headers }); + +/* replace first row */ +XLSX.utils.sheet_add_aoa(worksheet, [new_headers], { origin: "A1" }); ``` -Alternatively, a different set of unique headers can be used with `skipHeader`: - -```js -var ws = XLSX.utils.json_to_sheet([ - { A: "S", B: "h", C: "e", D: "e", E: "t", F: "J", G: "S" }, - { A: 1, B: 2, E: 5, F: 6, G: 7 }, - { A: 2, B: 3, E: 6, F: 7, G: 8 }, - { A: 3, B: 4, E: 7, F: 8, G: 9 }, - { A: 4, B: 5, C: 6, D: 7, E: 8, F: 9, G: 0 }, -], {header:["A","B","C","D","E","F","G"], skipHeader:true}); -``` +::: **Add data from an array of objects to an existing worksheet** @@ -275,7 +451,7 @@ function SheetJSHeaderOrder() { ::: -## Array Output +### Array Output