From 9088dfd4308221d9b677d8f5a6f132ae559c3aa1 Mon Sep 17 00:00:00 2001 From: SheetJS Date: Mon, 8 Jul 2024 04:18:18 -0400 Subject: [PATCH] Notes on Worksheet Ranges --- docz/docs/03-demos/19-desktop/01-electron.md | 2 +- docz/docs/03-demos/19-desktop/02-nwjs.md | 12 +++-- docz/docs/03-demos/27-local/02-websql.md | 21 ++++++-- docz/docs/07-csf/03-sheet.md | 48 +++++++++++------ docz/docs/07-csf/index.md | 17 +++++- docz/docs/08-api/03-parse-options.md | 21 ++++++-- docz/docs/08-api/05-write-options.md | 54 ++++++++++++++++---- 7 files changed, 134 insertions(+), 41 deletions(-) diff --git a/docz/docs/03-demos/19-desktop/01-electron.md b/docz/docs/03-demos/19-desktop/01-electron.md index dff29fb..60dfbbf 100644 --- a/docz/docs/03-demos/19-desktop/01-electron.md +++ b/docz/docs/03-demos/19-desktop/01-electron.md @@ -279,7 +279,7 @@ The program will run on ARM64 Windows. | `win10-x64` |`.\out\sheetjs-electron-win32-x64\sheetjs-electron.exe` | | `win11-arm` |`.\out\sheetjs-electron-win32-x64\sheetjs-electron.exe` | | `linux-x64` |`./out/sheetjs-electron-linux-x64/sheetjs-electron` | -| `linux-x64` |`./out/sheetjs-electron-linux-arm64/sheetjs-electron` | +| `linux-arm` |`./out/sheetjs-electron-linux-arm64/sheetjs-electron` | #### Electron API diff --git a/docz/docs/03-demos/19-desktop/02-nwjs.md b/docz/docs/03-demos/19-desktop/02-nwjs.md index bfb8526..70a2ada 100644 --- a/docz/docs/03-demos/19-desktop/02-nwjs.md +++ b/docz/docs/03-demos/19-desktop/02-nwjs.md @@ -117,7 +117,7 @@ This demo was tested in the following environments: | macOS 14.5 | `darwin-arm` | `0.88.0` | 2024-05-28 | | | Windows 10 | `win10-x64` | `0.83.0` | 2024-03-04 | | | Windows 11 | `win11-arm` | `0.88.0` | 2024-05-28 | | -| Linux (HoloOS) | `linux-x64` | `0.85.0` | 2024-03-12 | | +| Linux (HoloOS) | `linux-x64` | `0.89.0` | 2024-07-07 | | | Linux (Debian) | `linux-arm` | `0.60.0` | 2024-05-23 | Unofficial build[^1] | ::: @@ -138,7 +138,7 @@ cd sheetjs-nwjs "version": "0.0.0", "main": "index.html", "dependencies": { - "nw": "0.88.0", + "nw": "0.89.0", "xlsx": "https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz" } }`} @@ -182,9 +182,15 @@ file can be opened in Excel or another spreadsheet editor. 5) To build a standalone app, run the builder: ```bash -npx -p nw-builder nwbuild --mode=build --version=0.88.0 --glob=false --outDir=../out ./ +npx -p nw-builder nwbuild --mode=build --version=0.89.0 --glob=false --outDir=../out ./ ``` This will generate the standalone app in the `..\out\` folder. +6) Launch the generated application: + +| Architecture | Command | +|:-------------|:--------------------------------------------------------------| +| `linux-x64` | `../out/sheetjs-nwjs` | + [^1]: The [`nw60-arm64_2022-01-08` release](https://github.com/LeonardLaszlo/nw.js-armv7-binaries/releases/tag/nw60-arm64_2022-01-08) included an ARM64 version of `nw`. \ No newline at end of file diff --git a/docz/docs/03-demos/27-local/02-websql.md b/docz/docs/03-demos/27-local/02-websql.md index 5074fce..3c14ad3 100644 --- a/docz/docs/03-demos/27-local/02-websql.md +++ b/docz/docs/03-demos/27-local/02-websql.md @@ -11,17 +11,28 @@ import CodeBlock from '@theme/CodeBlock'; :::danger pass -WebSQL is no longer enabled by default in Chrome. Chrome 123 will officially -remove support. For SQL in the browser, there are a few alternatives: +WebSQL is no longer supported in Chrome or Safari. + +For SQL in the browser, there are a few alternatives: - [SQL.js](/docs/demos/data/sqlite#browser) is a compiled version of SQLite - [AlaSQL](/docs/demos/data/alasql) is a pure-JS SQL engine backed by IndexedDB ::: -WebSQL (formally "Web SQL Database") is a popular SQL-based in-browser database -available in Chromium and related browsers including Google Chrome. In practice, -it is powered by SQLite. Many SQLite-compatible queries work as-is in WebSQL. +WebSQL (formally "Web SQL Database") was a popular SQL-based in-browser database +available in Chromium and Safari. In practice, it was powered by SQLite. Many +SQLite-compatible queries were supported by WebSQL engines. + +:::note Historical Context + +Google and Apple developed and supported WebSQL. Legacy browser vendors fought +against standardization and ultimately broke the web by forcing the deprecation +of the storied API. + +Leveraging new technologies, many websites ship with an in-browser SQL database. + +::: The public demo https://sheetjs.com/sql generates a database from workbook. diff --git a/docz/docs/07-csf/03-sheet.md b/docz/docs/07-csf/03-sheet.md index 8c39773..599917b 100644 --- a/docz/docs/07-csf/03-sheet.md +++ b/docz/docs/07-csf/03-sheet.md @@ -17,10 +17,38 @@ Excel supports 4 different types of "sheets": Generic sheets are plain JavaScript objects. Each key that does not start with `!` is an `A1`-style address whose corresponding value is a cell object. +### Worksheet Range + +The `!ref` property stores the [A1-style range](/docs/csf/general#a1-style-1). + +Functions that work with sheets should use this property to determine the range. +Cells that are assigned outside of the range are not processed. + +For example, in the following sparse worksheet, the cell `A3` will be ignored +since it is outside of the worksheet range (`A1:B2`): + +```js +var ws = { + // worksheet range is A1:B2 + "!ref": "A1:B2", + + // A1 is in the range and will be included + "A1": { t: "s", v: "SheetJS" }, + + // cell A3 is outside of the range and will be ignored + "A3": { t: "n", v: 5433795 }, +}; +``` + +[Utility functions](/docs/api/utilities/) and functions that handle sheets +should test for the presence of the `!ref` field. If the `!ref` is omitted or is +not a valid range, functions should treat the sheet as empty. + ### Cell Storage -By default, the parsers and utility functions generate "sparse-mode" worksheet -objects. `sheet[address]` returns the cell object for the specified address. +By default, the parsers and utility functions generate "sparse-mode" worksheets. +For a given [A1-style address](/docs/csf/general#a1-style), `sheet[ref]` is the +corresponding cell object. #### Dense Mode @@ -127,27 +155,13 @@ _`json_to_sheet`_ +var sheet = XLSX.utils.json_to_sheet([{x:1,y:2}], {...opts, dense: true}); ``` - - ### Sheet Properties Each key starts with `!`. The properties are accessible as `sheet[key]`. -- `sheet['!ref']`: A-1 based range representing the sheet range. Functions that - work with sheets should use this parameter to determine the range. Cells that - are assigned outside of the range are not processed. In particular, when - writing a sheet by hand, cells outside of the range are not included - - Functions that handle sheets should test for the presence of `!ref` field. - If the `!ref` is omitted or is not a valid range, functions are free to treat - the sheet as empty or attempt to guess the range. The standard utilities that - ship with this library treat sheets as empty (for example, the CSV output is - empty string). - - When reading a worksheet with the `sheetRows` property set, the ref parameter - will use the restricted range. The original range is set at `ws['!fullref']` +- `sheet['!ref']`: [A1-style sheet range string](#worksheet-range) - `sheet['!margins']`: Object representing the page margins. The default values follow Excel's "normal" preset. Excel also has a "wide" and a "narrow" preset diff --git a/docz/docs/07-csf/index.md b/docz/docs/07-csf/index.md index 81a7576..03a2004 100644 --- a/docz/docs/07-csf/index.md +++ b/docz/docs/07-csf/index.md @@ -14,6 +14,19 @@ features are only accessible by inspecting and modifying the objects directly. This section covers the JS representation of workbooks, worksheets, cells, ranges, addresses and other features. +:::info Historical Context + +[Web Workers](/docs/demos/bigdata/worker), a popular API for parallelism in the +web browser, uses message passing. The "structured clone algorithm"[^1] is used +to pass data between the main renderer thread and Worker instances. + +The structured clone algorithm does not preserve functions or prototypes. + +In the SheetJS data model, each structure is a simple object. There are no +classes or prototype methods. + +::: + ### Contents \ No newline at end of file +})} + +[^1]: See [the HTML Living Standard](https://html.spec.whatwg.org/multipage/structured-data.html#structured-cloning) for more details on the "structured clone algorithm". diff --git a/docz/docs/08-api/03-parse-options.md b/docz/docs/08-api/03-parse-options.md index fa8942a..d31df84 100644 --- a/docz/docs/08-api/03-parse-options.md +++ b/docz/docs/08-api/03-parse-options.md @@ -46,7 +46,7 @@ The read functions accept an options argument: |:------------|:--------|:-----------------------------------------------------| |`type` | | [Input data representation](#input-type) | |`raw` | `false` | If true, plain text parsing will not parse values ** | -|`dense` | `false` | If true, use a dense worksheet representation ** | +|`dense` | `false` | If true, use a [dense sheet representation](#dense) | |`codepage` | | If specified, use code page when appropriate ** | |`cellFormula`| `true` | Save [formulae to the `.f` field](#formulae) | |`cellHTML` | `true` | Parse rich text and save HTML to the `.h` field | @@ -93,13 +93,22 @@ The read functions accept an options argument: - `WTF` is mainly for development. By default, the parser will suppress read errors on single worksheets, allowing you to read from the worksheets that do parse properly. Setting `WTF:true` forces those errors to be thrown. -- By default, "sparse" mode worksheets are generated. Individual cells are - accessed by indexing the worksheet object with an A1-Style address. "dense" - worksheets store cells in an array of arrays at `sheet["!data"]`. - `UTC` applies to CSV, Text and HTML formats. When explicitly set to `false`, the parsers will assume the files are specified in local time. By default, as is the case for other file formats, dates and times are interpreted in UTC. +#### Dense + +The ["Cell Storage"](/docs/csf/sheet#cell-storage) section of the SheetJS Data +Model documentation explains the worksheet representation in more detail. + +:::note pass + +[Utility functions that process SheetJS workbook objects](/docs/api/utilities/) +typically process both sparse and dense worksheets. + +::: + #### Range Some file formats, including XLSX and XLS, can self-report worksheet ranges. The @@ -107,7 +116,9 @@ self-reported ranges are used by default. If the `sheetRows` option is set, up to `sheetRows` rows will be parsed from the worksheets. `sheetRows-1` rows will be generated when looking at the JSON object -output (since the header row is counted as a row when parsing the data). +output (since the header row is counted as a row when parsing the data). The +`!ref` property of the worksheet will hold the adjusted range. For formats that +self-report sheet ranges, the `!fullref` property will hold the original range. The `nodim` option instructs the parser to ignore self-reported ranges and use the actual cells in the worksheet to determine the range. This addresses known diff --git a/docz/docs/08-api/05-write-options.md b/docz/docs/08-api/05-write-options.md index 7ebdf4e..9c644e0 100644 --- a/docz/docs/08-api/05-write-options.md +++ b/docz/docs/08-api/05-write-options.md @@ -9,7 +9,18 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; -**`XLSX.write(wb, options)`** +The main SheetJS method for writing workbooks is `write`. Scripts receive common +[JavaScript data representations](#output-type) and are expected to write or +share files using platform-specific APIs. + +The `writeFile` helper method accepts a filename and tries to write to a local +file using [standard APIs](/docs/demos/local/file). + +**Export a SheetJS workbook object in a specified file format** + +```js +var file_data = XLSX.write(wb, opts); +``` `write` attempts to write the workbook `wb` and return the file. @@ -17,7 +28,11 @@ The `options` argument is required. It must specify - [`bookType`](#supported-output-formats) (file format of the exported file) - [`type`](#output-type) (return value type) -**`XLSX.writeFile(wb, filename, options)`** +**Export a SheetJS workbook object and attempt to write a local file** + +```js +XLSX.writeFile(wb, filename, options); +``` `writeFile` attempts to write `wb` to a local file with specified `filename`. @@ -27,9 +42,16 @@ It also supports NodeJS, ExtendScript applications, and Chromium extensions. If `options` is omitted or if `bookType` is missing from the `options` object, the output file format will be deduced from the filename extension. -**`XLSX.writeXLSX(wb, options)`** +**Special functions for exporting data in the XLSX format** -**`XLSX.writeFileXLSX(wb, filename, options)`** +```js +// limited form of `write` +var file_data = XLSX.writeXLSX(wb, options); + + +// limited form of `writeFile` +XLSX.writeFileXLSX(wb, filename, options); +``` `writeXLSX` and `writeFileXLSX` are limited versions of `write` and `writeFile`. They support writing to the XLSX file format. @@ -42,11 +64,19 @@ more appropriate when exporting to XLS or XLSB or other formats.
NodeJS-specific methods (click to show) -**`XLSX.writeFileAsync(filename, wb, cb)`** +**Export a workbook and attempt to write a local file using `fs.writeFile`** -**`XLSX.writeFileAsync(filename, wb, options, cb)`** +```js +// callback equivalent of `XLSX.writeFile` +XLSX.writeFileAsync(filename, wb, cb); -attempt to write `wb` to `filename` and invoke the callback `cb` on completion. +// callback equivalent with options argument +XLSX.writeFileAsync(filename, wb, options, cb); +``` + + +`writeFileAsync` attempts to write `wb` to `filename` and invoke the callback +`cb` on completion. When an `options` object is specified, it is expected to be the third argument. @@ -275,6 +305,12 @@ The `type` option specifies the JS form of the output: | `"array"` | ArrayBuffer, fallback array of 8-bit unsigned int | | `"file"` | string: path of file that will be created (nodejs only) | -- For compatibility with Excel, `csv` output will always include the UTF-8 byte - order mark. +:::note pass +For compatibility with Excel, `csv` output will always include the UTF-8 byte +order mark ("BOM"). + +The raw [`sheet_to_csv` method](/docs/api/utilities/csv#csv-output) will return +JavaScript strings without the UTF-8 BOM. + +:::