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

142 lines
3.2 KiB
Markdown
Raw Normal View History

2022-05-16 03:26:04 +00:00
---
sidebar_position: 9
2022-12-01 01:13:00 +00:00
title: Utility Functions
2023-05-15 08:38:23 +00:00
pagination_prev: api/write-options
2022-05-16 03:26:04 +00:00
---
2023-06-13 17:49:52 +00:00
The utility functions in this section fall into two categories:
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
**Data Packaging**
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
The "Input" functions create SheetJS data structures (worksheets or workbooks)
from rows of data or other common JS data representations
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
These functions are paired with `write` or `writeFile` to create exports. For
example, the following diagram shows the steps to export an HTML TABLE to XLSX:
2022-07-07 04:05:14 +00:00
2023-06-13 17:49:52 +00:00
```mermaid
flowchart LR
html{{HTML\nTABLE}}
ws(SheetJS\nWorksheet)
wb(SheetJS\nWorkbook)
file[(workbook\nfile)]
html --> |table_to_sheet\n\n| ws
2024-01-03 06:47:00 +00:00
ws --> |book_new\n\n| wb
2023-06-13 17:49:52 +00:00
wb --> |writeFile\n\n| file
```
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
**Data Extraction**
2022-07-07 04:05:14 +00:00
2023-06-13 17:49:52 +00:00
The "Output" functions extract data from worksheets to friendlier structures.
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
These functions are paired with `read` or `readFile` to process data from files.
The following diagram shows the steps to generate an HTML TABLE from a URL:
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
```mermaid
flowchart LR
url[(Remote\nFile)]
ab[(Data\nArrayBuffer)]
wb(SheetJS\nWorkbook)
ws(SheetJS\nWorksheet)
html{{HTML\nTABLE}}
url --> |fetch\n\n| ab
ab --> |read\n\n| wb
wb --> |wb.Sheets\nselect sheet| ws
ws --> |sheet_to_html\nfirst worksheet| html
2022-07-07 04:05:14 +00:00
```
2022-09-22 00:20:14 +00:00
2023-06-13 17:49:52 +00:00
## Array Output
**Generate rows of data from a worksheet**
```js
var arr = XLSX.utils.sheet_to_json(ws, opts);
```
2022-09-22 00:20:14 +00:00
2023-06-25 09:36:58 +00:00
[**This function is described in a dedicated page**](/docs/api/utilities/array#array-of-objects-input)
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
## Array of Arrays Input
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
**Create a worksheet from an array of arrays**
2022-05-16 03:26:04 +00:00
```js
2023-06-13 17:49:52 +00:00
var ws = XLSX.utils.aoa_to_sheet(aoa, opts);
2022-05-16 03:26:04 +00:00
```
2022-07-07 04:05:14 +00:00
**Add data from an array of arrays to an existing worksheet**
```js
XLSX.utils.sheet_add_aoa(ws, aoa, opts);
```
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
[**These functions are described in a dedicated page**](/docs/api/utilities/array#array-of-arrays-input)
2022-05-16 03:26:04 +00:00
2022-10-06 00:05:06 +00:00
## Array of Objects Input
2022-05-16 03:26:04 +00:00
2022-07-07 04:05:14 +00:00
**Create a worksheet from an array of objects**
```js
var ws = XLSX.utils.json_to_sheet(aoo, opts);
```
2023-06-13 17:49:52 +00:00
**Add data from an array of objects to an existing worksheet**
2022-07-07 04:05:14 +00:00
```js
2023-06-13 17:49:52 +00:00
XLSX.utils.sheet_add_json(ws, aoo, opts);
2022-07-07 04:05:14 +00:00
```
2023-06-13 17:49:52 +00:00
[**These functions are described in a dedicated page**](/docs/api/utilities/array#array-of-objects-input)
2022-07-07 04:05:14 +00:00
2023-06-13 17:49:52 +00:00
## HTML Table Input
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
**Create a worksheet or workbook from a TABLE element**
2022-05-16 03:26:04 +00:00
```js
2023-06-13 17:49:52 +00:00
var ws = XLSX.utils.table_to_sheet(elt, opts);
var wb = XLSX.utils.table_to_book(elt, opts);
2022-05-16 03:26:04 +00:00
```
2023-06-13 17:49:52 +00:00
**Add data from a TABLE element to an existing worksheet**
2022-07-07 04:05:14 +00:00
```js
2023-06-13 17:49:52 +00:00
XLSX.utils.sheet_add_dom(ws, elt, opts);
2022-07-07 04:05:14 +00:00
```
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
[**These functions are described in a dedicated page**](/docs/api/utilities/html#html-table-input)
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
## HTML Output
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
**Display worksheet data in a HTML table**
2022-05-16 03:26:04 +00:00
```js
2023-06-13 17:49:52 +00:00
var html = XLSX.utils.sheet_to_html(ws, opts);
2022-07-07 04:05:14 +00:00
```
2023-06-13 17:49:52 +00:00
[**This function are described in a dedicated page**](/docs/api/utilities/html#html-table-output)
2022-10-06 00:05:06 +00:00
## Delimiter-Separated Output
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
**Generate CSV from a Worksheet**
2022-12-01 01:13:00 +00:00
2022-05-16 03:26:04 +00:00
```js
2023-06-13 17:49:52 +00:00
var csv = XLSX.utils.sheet_to_csv(ws, opts);
2022-12-01 01:13:00 +00:00
```
2023-06-13 17:49:52 +00:00
**Export worksheet data in "UTF-16 Text" or Tab-Separated Values (TSV)**
2022-12-01 01:13:00 +00:00
2023-06-13 17:49:52 +00:00
```js
var txt = XLSX.utils.sheet_to_txt(ws, opts);
2022-12-01 01:13:00 +00:00
```
2023-06-13 17:49:52 +00:00
[**These functions are described in a dedicated page**](/docs/api/utilities/csv)
2022-12-01 01:13:00 +00:00
2023-06-13 17:49:52 +00:00
## Formulae Output
2022-12-01 01:13:00 +00:00
2023-06-13 17:49:52 +00:00
**Extract all formulae from a worksheet**
2022-12-01 01:13:00 +00:00
2023-06-13 17:49:52 +00:00
```js
var fmla_arr = XLSX.utils.sheet_to_formulae(ws);
2022-07-07 04:05:14 +00:00
```
2022-05-16 03:26:04 +00:00
2023-06-13 17:49:52 +00:00
[**This function is described in a dedicated page**](/docs/api/utilities/formulae)