docs.sheetjs.com/docz/docs/08-api/index.md

171 lines
5.2 KiB
Markdown
Raw Normal View History

2022-05-16 03:26:04 +00:00
---
2022-08-24 23:48:22 +00:00
pagination_prev: csf/index
2022-05-16 03:26:04 +00:00
sidebar_position: 5
2022-08-13 22:01:26 +00:00
title: API Reference
2022-05-16 03:26:04 +00:00
---
2023-06-20 01:21:34 +00:00
import current from '/version.js';
2022-05-16 03:26:04 +00:00
2023-06-20 01:21:34 +00:00
This section lists the functions defined in the library.
2022-05-16 03:26:04 +00:00
2023-10-30 23:28:40 +00:00
:::info pass
**The ["SheetJS Data Model"](/docs/csf) section covers spreadsheet features.**
The API functions primarily focus on conversions between data representations.
:::
## Library access
2023-06-20 01:21:34 +00:00
Using the ["Standalone" scripts](/docs/getting-started/installation/standalone),
`XLSX` is added to the `window` or other `global` object.
2022-05-16 03:26:04 +00:00
2023-06-20 01:21:34 +00:00
Using the ["NodeJS" module](/docs/getting-started/installation/nodejs), the
`XLSX` variable refers to the CommonJS export:
2022-05-16 03:26:04 +00:00
2023-06-20 01:21:34 +00:00
```js
var XLSX = require("xlsx");
```
Using [a framework](/docs/getting-started/installation/frameworks), the `XLSX`
variable refers to the glob import:
```js
import * as XLSX from "xlsx";
```
2022-06-22 19:25:24 +00:00
2022-05-16 03:26:04 +00:00
## Parsing functions
`XLSX.read(data, read_opts)` attempts to parse `data`.
`XLSX.readFile(filename, read_opts)` attempts to read `filename` and parse.
2022-10-30 05:45:37 +00:00
Parse options are described in the [Parsing Options](/docs/api/parse-options) section.
2022-05-16 03:26:04 +00:00
## Writing functions
2022-06-22 19:25:24 +00:00
`XLSX.write(wb, write_opts)` attempts to write the workbook `wb`.
`XLSX.writeXLSX(wb, write_opts)` attempts to write the workbook in XLSX format.
2022-05-16 03:26:04 +00:00
`XLSX.writeFile(wb, filename, write_opts)` attempts to write `wb` to `filename`.
In browser-based environments, it will attempt to force a client-side download.
2022-06-22 19:25:24 +00:00
`XLSX.writeFileXLSX(wb, filename, write_opts)` attempts to write an XLSX file.
2022-05-16 03:26:04 +00:00
`XLSX.writeFileAsync(filename, wb, o, cb)` attempts to write `wb` to `filename`.
If `o` is omitted, the writer will use the third argument as the callback.
2022-10-30 05:45:37 +00:00
Write options are described in the [Writing Options](/docs/api/write-options) section.
2022-05-16 03:26:04 +00:00
## Utilities
2022-06-01 22:59:29 +00:00
Utilities are available in the `XLSX.utils` object.
2023-05-27 23:07:45 +00:00
The methods are covered in dedicated pages:
2022-06-01 22:59:29 +00:00
2023-05-27 23:07:45 +00:00
**[`A1` Utilities](/docs/csf/general#utilities)**
_Cell and cell address manipulation:_
2022-06-01 22:59:29 +00:00
- `encode_row / decode_row` converts between 0-indexed rows and 1-indexed rows.
- `encode_col / decode_col` converts between 0-indexed columns and column names.
- `encode_cell / decode_cell` converts cell addresses.
- `encode_range / decode_range` converts cell ranges.
2023-06-13 17:49:52 +00:00
**["Arrays of Data" section of "Utility Functions"](/docs/api/utilities/array)**
_Importing Data:_
- `aoa_to_sheet` converts an array of arrays of JS data to a worksheet.
- `json_to_sheet` converts an array of JS objects to a worksheet.
- `sheet_add_aoa` adds an array of arrays of JS data to an existing worksheet.
- `sheet_add_json` adds an array of JS objects to an existing worksheet.
_Exporting Data:_
- `sheet_to_json` converts a worksheet object to an array of JSON objects.
2023-05-27 23:07:45 +00:00
**["HTML" section of "Utility Functions"](/docs/api/utilities/html)**
2023-05-18 22:41:23 +00:00
2023-05-27 23:07:45 +00:00
_Reading from HTML:_
2023-05-18 22:41:23 +00:00
- `table_to_sheet` converts a DOM TABLE element to a worksheet.
- `table_to_book` converts a DOM TABLE element to a worksheet.
- `sheet_add_dom` adds data from a DOM TABLE element to an existing worksheet.
2023-05-27 23:07:45 +00:00
_Writing HTML:_
- `sheet_to_html` generates HTML output.
**["CSV and Text" section of "Utility Functions"](/docs/api/utilities/csv)**
_Writing CSV and Text:_
- `sheet_to_csv` generates delimiter-separated-values output.
- `sheet_to_txt` generates UTF-16 formatted text.
**["Array of Formulae" section of "Utility Functions"](/docs/api/utilities/formulae)**
2022-05-16 03:26:04 +00:00
2023-05-27 23:07:45 +00:00
_Exporting Formulae:_
- `sheet_to_formulae` generates a list of formulae or cell value assignments.
2023-06-25 09:36:58 +00:00
**["Workbook Helpers" section of "Utility Functions"](/docs/api/utilities/wb)**
2023-05-27 23:07:45 +00:00
_Workbook Operations:_
2022-05-16 03:26:04 +00:00
2024-01-03 06:47:00 +00:00
- `book_new` creates a workbook object
2022-05-16 03:26:04 +00:00
- `book_append_sheet` adds a worksheet to a workbook
2023-06-25 09:36:58 +00:00
**[Utility Functions](/docs/api/utilities)**
2023-05-27 23:07:45 +00:00
_Miscellaneous_
2022-05-16 03:26:04 +00:00
- `format_cell` generates the text value for a cell (using number formats).
2022-06-22 19:25:24 +00:00
- `sheet_set_array_formula` adds an array formula to a worksheet
## Platform-Specific Functions
### NodeJS Streaming Write functions
`XLSX.stream` contains a set of streaming write functions for NodeJS streams:
- `to_csv(sheet, opts)` streams CSV rows
- `to_html(sheet, opts)` streams an HTML table incrementally
- `to_json(sheet, opts)` streams JS objects (object-mode stream)
2024-07-18 22:19:02 +00:00
- `to_xlml(book, opts)` streams a SpreadsheetML2003 workbook incrementally
2022-06-22 19:25:24 +00:00
2024-07-18 22:19:02 +00:00
Stream methods are described in the ["Stream Export"](/docs/api/stream) section.
2023-05-30 06:41:09 +00:00
2022-06-22 19:25:24 +00:00
### ESM Helpers
Due to broad inconsistencies in ESM implementations, the `mjs` build does not
import any dependencies. Instead, they must be manually passed to the library:
`XLSX.set_cptable` sets the internal `codepage` instance. This provides support
2022-08-25 08:22:28 +00:00
for different languages in XLS or text parsing.
2022-06-22 19:25:24 +00:00
`XLSX.set_fs` set `fs` instance (using `readFileSync` and `writeFileSync`). This
provides NodeJS ESM support for `XLSX.readFile` and `XLSX.writeFile`.
`XLSX.utils.set_readable` supplies a NodeJS `stream.Readable` constructor. This
2023-06-20 01:21:34 +00:00
provides NodeJS ESM support for the streaming operations.
ESM helper functions are described in the ["NodeJS" Installation section](/docs/getting-started/installation/nodejs)
## Miscellaneous
`XLSX.version` is the version of the library.
:::note pass
<p>The current version is <code>{current}</code></p>
:::
2023-10-24 06:20:57 +00:00
`XLSX.SSF` is an embedded version of the [format library](/docs/constellation/ssf).
2023-06-20 01:21:34 +00:00
`XLSX.CFB` is an embedded version of the [container library](https://git.sheetjs.com/sheetjs/js-cfb).