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

html-out

Browse Source
This commit is contained in:
SheetJS 2023-05-27 19:07:45 -04:00
parent ae138cc327
commit 727a67b152
12 changed files with 261 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docz/docs/02-getting-started/01-installation/index.md Normal file
View File

@ -0,0 +1,29 @@
---
pagination_prev: getting-started/index
pagination_next: getting-started/example
hide_table_of_contents: true
title: Installation
------
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
<https://cdn.sheetjs.com> is the primary software distribution site. Please
read the installation instructions for your use case:
<ul>{useCurrentSidebarCategory().items.map((item, index) => {
const listyle = (item.customProps?.icon) ? {
listStyleImage: `url("${item.customProps.icon}")`
} : {};
return (<li style={listyle} {...(item.customProps?.class ? {className: item.customProps.class}: {})}>
<a href={item.href}>{item.label}</a>{item.customProps?.summary && (" - " + item.customProps.summary)}
</li>);
})}</ul>
:::info
[Watch the repo](https://git.sheetjs.com/SheetJS/sheetjs) or subscribe to the
[RSS feed](https://git.sheetjs.com/sheetjs/sheetjs/tags.rss) to be notified when
new versions are released!
:::

2
docz/docs/02-getting-started/02-example.mdx
View File

@ -1,5 +1,5 @@
---
pagination_prev: getting-started/index
pagination_prev: getting-started/installation/index
sidebar_position: 2
---

11
docz/docs/02-getting-started/index.md
View File

@ -1,17 +1,20 @@
---
hide_table_of_contents: true
pagination_next: getting-started/example
pagination_next: getting-started/installation/index
---
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
# Getting Started
["Tutorial"](/docs/getting-started/example) is a live example that covers
general data munging and data export to spreadsheets.
## Installation
["Demos"](/docs/demos) include discussions and tested examples for common
deployments and use cases.
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
## Installation
<https://cdn.sheetjs.com> is the primary software distribution site. Please
read the installation instructions for your use case:

4
docz/docs/03-demos/07-data/09-alasql.md
View File

@ -181,14 +181,12 @@ By default the workbook is parsed and `sheet_to_json` is used to pull data:
The `XLSX` "into" target calls `XLSX.writeFile` under the hood:
```js
const { promise: alasql } = require("alasql");
(async() => {
const data = [
{ Name: "Bill Clinton", Index: 42 },
{ Name: "Someone Else", Index: 47 }
];
await alasql(`SELECT * INTO XLSX("PresMod5.xlsx") FROM ?`, [data]);
await alasql.promise(`SELECT * INTO XLSX("PresMod5.xlsx") FROM ?`, [data]);
/* PresMod5.xlsx will be created */
})();
```

8
docz/docs/06-solutions/05-output.md
View File

@ -805,8 +805,8 @@ var csv = XLSX.utils.sheet_to_csv(worksheet, opts);
```
This snapshot is designed to replicate the "CSV UTF-8 (`.csv`)" output type.
["Delimiter-Separated Output"](/docs/api/utilities#delimiter-separated-output) describes the
function and the optional `opts` argument in more detail.
["CSV and Text"](/docs/api/utilities/csv) describes the function and the
optional `opts` argument in more detail.
_Generate "Text" from a single worksheet_
@ -815,8 +815,8 @@ var txt = XLSX.utils.sheet_to_txt(worksheet, opts);
```
This snapshot is designed to replicate the "UTF-16 Text (`.txt`)" output type.
["Delimiter-Separated Output"](/docs/api/utilities#delimiter-separated-output) describes the
function and the optional `opts` argument in more detail.
["CSV and Text"](/docs/api/utilities/csv) describes the function and the
optional `opts` argument in more detail.
_Generate a list of formulae from a single worksheet_

54
docz/docs/08-api/07-utilities/07-html.md → docz/docs/08-api/07-utilities/05-html.md
View File

@ -1,5 +1,5 @@
---
sidebar_position: 7
sidebar_position: 5
title: HTML
---
@ -17,6 +17,58 @@ HTML format and HTML table utilities.
:::
## HTML Table Output
```js
var html = XLSX.utils.sheet_to_html(ws, opts);
```
As an alternative to the `writeFile` HTML type, `XLSX.utils.sheet_to_html` also
produces HTML output. The function takes an options argument:
| Option Name | Default | Description |
|:------------|:--------:|:----------------------------------------------------|
| `id` | | Specify the `id` attribute for the `TABLE` element |
| `editable` | false | If true, set `contenteditable="true"` for every TD |
| `header` | | Override header |
| `footer` | | Override footer |
Starting from [the sample file `pres.numbers`](https://sheetjs.com/pres.numbers):
```jsx live
function SheetJSHTML() {
const url = "https://sheetjs.com/pres.numbers";
const [__html, setHTML] = React.useState("");
React.useEffect(() => { (async() => {
/* download file and parse */
const wb = XLSX.read(await (await fetch(url)).arrayBuffer());
/* get the first worksheet */
const ws = wb.Sheets[wb.SheetNames[0]];
/* generate HTML */
const html = XLSX.utils.sheet_to_html(ws);
setHTML(html);
})(); }, []);
return ( <>
<b>XLSX.utils.sheet_to_html(ws)</b>
<div dangerouslySetInnerHTML={{__html}}/>
</> );
}
```
### Implementation Details
The generated table will include special data attributes on each `TD` element:
| Attribute | Description |
|:----------|:-------------------------------------------------------------|
| `data-t` | Override [Cell Type](/docs/csf/cell#data-types) |
| `data-v` | Override Cell Value |
| `data-z` | Override [Number Format](/docs/csf/features/nf) |
External cell links will be written as `A` tags wrapping the cell contents.
## HTML Table Input
### Create New Sheet

125
docz/docs/08-api/07-utilities/07-csv.md Normal file
View File

@ -0,0 +1,125 @@
---
sidebar_position: 7
title: CSV and Text
---
CSV is a common format for data interchange. Spreadsheet applications such as
Excel also support other delimiter-separated formats including "Text" (using a
tab character as the field separator).
The general write functions (`XLSX.write` and `XLSX.writeFile`) support `csv`
and `txt` (for CSV and tab-separated values respectively), but the specific
utility functions generate raw JS strings for further processing.
## Live Demo
After choosing a file, the demo will print the data from each worksheet:
```jsx live
function SheetJSPreCSView() {
const [__html, setHTML] = React.useState("Select a file");
const process = (ab) => {
const wb = XLSX.read(ab);
var res = "";
wb.SheetNames.forEach((n, idx) => {
const ws = wb.Sheets[n];
res += `<b>Sheet #${idx+1} (${n})</b>\n`;
res += XLSX.utils.sheet_to_csv(ws) + "\n\n";
});
setHTML(res);
};
React.useEffect(() => { (async() => {
const url = "https://sheetjs.com/pres.numbers";
process(await (await fetch(url)).arrayBuffer());
})(); }, []);
return ( <>
<input type="file" onChange={async(e) => {
process(await e.target.files[0].arrayBuffer());
}}/>
<pre dangerouslySetInnerHTML={{ __html }}/>
</> );
}
```
## Delimiter-Separated Output
**Export worksheet data in CSV, TSV, or other delimiter-separated format**
```js
var csv = XLSX.utils.sheet_to_csv(ws, opts);
```
As an alternative to the `writeFile` CSV type, `XLSX.utils.sheet_to_csv` also
produces CSV output. The function takes an options argument:
| Option Name | Default | Description |
| :----------- | :------: | :------------------------------------------------- |
|`FS` | `","` | "Field Separator" delimiter between fields |
|`RS` | `"\n"` | "Record Separator" delimiter between rows |
|`dateNF` | FMT 14 | Use specified date format in string output |
|`strip` | false | Remove trailing field separators in each record ** |
|`blankrows` | true | Include blank lines in the CSV output |
|`skipHidden` | false | Skips hidden rows/columns in the CSV output |
|`forceQuotes` | false | Force quotes around fields |
- `strip` will remove trailing commas from each line under default `FS/RS`
- `blankrows` must be set to `false` to skip blank lines.
- Fields containing the record or field separator will automatically be wrapped
in double quotes; `forceQuotes` forces all cells to be wrapped in quotes.
The following example shows `FS` and `RS` options:
```jsx live
function SheetJSCSVTest() {
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]
]);
return ( <pre>
<b>Worksheet (as HTML)</b>
<div dangerouslySetInnerHTML={{__html: XLSX.utils.sheet_to_html(ws)}}/>
<b>XLSX.utils.sheet_to_csv(ws)</b><br/>
{XLSX.utils.sheet_to_csv(ws)}<br/><br/>
<b>XLSX.utils.sheet_to_csv(ws, {'{'} FS: "\t" {'}'})</b><br/>
{XLSX.utils.sheet_to_csv(ws, { FS: "\t" })}<br/><br/>
<b>XLSX.utils.sheet_to_csv(ws, {'{'} FS: ":", RS: "|" {'}'})</b><br/>
{XLSX.utils.sheet_to_csv(ws, { FS: ":", RS: "|" })}<br/>
</pre> );
}
```
### CSV Output
**Export worksheet data in "Comma-Separated Values" (CSV)**
```js
var csv = XLSX.utils.sheet_to_csv(ws, opts);
```
`sheet_to_csv` uses the comma character as the field separator by default. This
utility function mirrors the `csv` book type in `XLSX.write` or `XLSX.writeFile`.
`sheet_to_csv` always returns a JS string and always omits byte-order marks.
### UTF-16 Text Output
**Export worksheet data in "UTF-16 Text" or Tab-Separated Values (TSV)**
```js
var txt = XLSX.utils.sheet_to_txt(ws, opts);
```
`sheet_to_txt` uses the tab character as the field separator. This utility
function matches the `txt` book type in `XLSX.write` or `XLSX.writeFile`.
If encoding support is available, the output will be encoded in `CP1200` and the
UTF-16 BOM will be added. If encoding support is not available, the output will
be encoded as a standard `string`.
`XLSX.utils.sheet_to_txt` takes the same arguments as `sheet_to_csv`.

2
docz/docs/08-api/07-utilities/09-formulae.md
View File

@ -4,6 +4,8 @@ title: Array of Formulae
pagination_next: miscellany/formats
---
**Extract all formulae from a worksheet**
```js
var fmla_arr = XLSX.utils.sheet_to_formulae(ws);
```

95
docz/docs/08-api/07-utilities/index.md
View File

@ -284,102 +284,11 @@ function SheetJSHeaderOrder() {
## Delimiter-Separated Output
```js
var csv = XLSX.utils.sheet_to_csv(ws, opts);
```
As an alternative to the `writeFile` CSV type, `XLSX.utils.sheet_to_csv` also
produces CSV output. The function takes an options argument:
| Option Name | Default | Description |
| :----------- | :------: | :------------------------------------------------- |
|`FS` | `","` | "Field Separator" delimiter between fields |
|`RS` | `"\n"` | "Record Separator" delimiter between rows |
|`dateNF` | FMT 14 | Use specified date format in string output |
|`strip` | false | Remove trailing field separators in each record ** |
|`blankrows` | true | Include blank lines in the CSV output |
|`skipHidden` | false | Skips hidden rows/columns in the CSV output |
|`forceQuotes` | false | Force quotes around fields |
- `strip` will remove trailing commas from each line under default `FS/RS`
- `blankrows` must be set to `false` to skip blank lines.
- Fields containing the record or field separator will automatically be wrapped
in double quotes; `forceQuotes` forces all cells to be wrapped in quotes.
- `XLSX.write` with `csv` type will always prepend the UTF-8 byte-order mark for
Excel compatibility. `sheet_to_csv` returns a JS string and omits the mark.
Using `XLSX.write` with type `string` will also skip the mark.
Starting from the example worksheet:
```jsx live
function SheetJSCSVTest() {
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]
]);
return ( <pre>
<b>Worksheet (as HTML)</b>
<div dangerouslySetInnerHTML={{__html: XLSX.utils.sheet_to_html(ws)}}/>
<b>XLSX.utils.sheet_to_csv(ws)</b><br/>
{XLSX.utils.sheet_to_csv(ws)}<br/><br/>
<b>XLSX.utils.sheet_to_csv(ws, {'{'} FS: "\t" {'}'})</b><br/>
{XLSX.utils.sheet_to_csv(ws, { FS: "\t" })}<br/><br/>
<b>XLSX.utils.sheet_to_csv(ws, {'{'} FS: ":", RS: "|" {'}'})</b><br/>
{XLSX.utils.sheet_to_csv(ws, { FS: ":", RS: "|" })}<br/>
</pre> );
}
```
**UTF-16 Text Output**
```js
var txt = XLSX.utils.sheet_to_txt(ws, opts);
```
The `txt` output type uses the tab character as the field separator. If the
`codepage` library is available (included in full distribution but not core),
the output will be encoded in `CP1200` and the UTF-16 BOM will be added.
`XLSX.utils.sheet_to_txt` takes the same arguments as `sheet_to_csv`.
[**This has been moved to a separate page**](/docs/api/utilities/csv)
## HTML Output
```js
var html = XLSX.utils.sheet_to_html(ws, opts);
```
As an alternative to the `writeFile` HTML type, `XLSX.utils.sheet_to_html` also
produces HTML output. The function takes an options argument:
| Option Name | Default | Description |
| :---------- | :------: | :-------------------------------------------------- |
|`id` | | Specify the `id` attribute for the `TABLE` element |
|`editable` | false | If true, set `contenteditable="true"` for every TD |
|`header` | | Override header (default `html body`) |
|`footer` | | Override footer (default `/body /html`) |
Starting from the example worksheet:
```jsx live
function SheetJSHTML() {
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]
]);
return ( <pre>
<b>XLSX.utils.sheet_to_html(ws)</b>
<div dangerouslySetInnerHTML={{__html: XLSX.utils.sheet_to_html(ws)}}/>
</pre> );
}
```
[**This has been moved to a separate page**](/docs/api/utilities/html#html-table-output)
## Array Output

41
docz/docs/08-api/index.md
View File

@ -42,46 +42,61 @@ Write options are described in the [Writing Options](/docs/api/write-options) se
Utilities are available in the `XLSX.utils` object.
The following are described in [`A1` Utilities](/docs/csf/general#utilities)
The methods are covered in dedicated pages:
**Cell and cell address manipulation:**
**[`A1` Utilities](/docs/csf/general#utilities)**
_Cell and cell address manipulation:_
- `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.
The following are described in ["HTML" section of "Utility Functions"](/docs/api/utilities/html):
**["HTML" section of "Utility Functions"](/docs/api/utilities/html)**
**Reading from HTML:**
_Reading from HTML:_
- `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.
The following are described in the [Utility Functions](/docs/api/utilities):
_Writing HTML:_
**Constructing:**
- `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)**
_Exporting Formulae:_
- `sheet_to_formulae` generates a list of formulae or cell value assignments.
**[Utility Functions](/docs/api/utilities)**
_Workbook Operations:_
- `book_new` creates an empty workbook
- `book_append_sheet` adds a worksheet to a workbook
**Importing:**
_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:**
_Exporting Data:_
- `sheet_to_json` converts a worksheet object to an array of JSON objects.
- `sheet_to_csv` generates delimiter-separated-values output.
- `sheet_to_txt` generates UTF-16 formatted text.
- `sheet_to_html` generates HTML output.
- `sheet_to_formulae` generates a list of formulae or cell value assignments.
**Miscellaneous**
_Miscellaneous_
- `format_cell` generates the text value for a cell (using number formats).
- `sheet_set_array_formula` adds an array formula to a worksheet

4
docz/docs/09-miscellany/02-errors.md
View File

@ -13,7 +13,7 @@ wealth of information and user-contributed examples.
**Many of these errors have been fixed in newer releases!** Ensure that the
latest version of the library is being used. Some legacy endpoints are out of
date. [Review the Installation instructions.](/docs/getting-started#installation)
date. [Review the Installation instructions.](/docs/getting-started/installation)
If issues are not covered in the docs or the issue tracker, or if a solution is
not discussed in the documentation, we would appreciate a bug report.
@ -41,7 +41,7 @@ Uncaught TypeError: Cannot read property 'utils' of undefined
The root cause is an undefined `XLSX` variable. This usually means the library
was not properly loaded.
[Review the Installation instructions.](/docs/getting-started#installation)
[Review the Installation instructions.](/docs/getting-started/installation)
If the error shows up while using the latest version, projects may require
other configuration or loading strategies.

14
docz/package.json
View File

@ -15,12 +15,12 @@
},
"dependencies": {
"@cmfcmf/docusaurus-search-local": "0.11.0",
"@docusaurus/core": "2.3.1",
"@docusaurus/plugin-client-redirects": "2.3.1",
"@docusaurus/preset-classic": "2.3.1",
"@docusaurus/theme-common": "2.3.1",
"@docusaurus/theme-live-codeblock": "2.3.1",
"@docusaurus/theme-mermaid": "2.3.1",
"@docusaurus/core": "2.4.1",
"@docusaurus/plugin-client-redirects": "2.4.1",
"@docusaurus/preset-classic": "2.4.1",
"@docusaurus/theme-common": "2.4.1",
"@docusaurus/theme-live-codeblock": "2.4.1",
"@docusaurus/theme-mermaid": "2.4.1",
"@mdx-js/react": "1.6.22",
"clsx": "1.2.1",
"prism-react-renderer": "1.3.5",
@ -29,7 +29,7 @@
"xlsx": "https://cdn.sheetjs.com/xlsx-0.19.3/xlsx-0.19.3.tgz"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.3.1"
"@docusaurus/module-type-aliases": "2.4.1"
},
"browserslist": {
"production": [