forked from sheetjs/docs.sheetjs.com
307 lines
7.9 KiB
Markdown
307 lines
7.9 KiB
Markdown
---
|
|
title: Synthetic DOM
|
|
---
|
|
|
|
import current from '/version.js';
|
|
import CodeBlock from '@theme/CodeBlock';
|
|
|
|
SheetJS offers three methods to directly process HTML DOM TABLE elements[^1]:
|
|
|
|
- `table_to_sheet` generates a SheetJS worksheet[^2] from a TABLE element
|
|
- `table_to_book` generates a SheetJS workbook[^3] from a TABLE element
|
|
- `sheet_add_dom` adds data from a TABLE element to an existing worksheet
|
|
|
|
These methods work in the web browser. NodeJS and other server-side platforms
|
|
traditionally lack a DOM implementation, but third-party modules fill the gap.
|
|
|
|
:::tip pass
|
|
|
|
The most robust approach for server-side processing is to automate a headless
|
|
web browser. ["Browser Automation"](/docs/demos/net/headless) includes demos.
|
|
|
|
:::
|
|
|
|
This demo covers synthetic DOM implementations for non-browser platforms.
|
|
|
|
## Integration Details
|
|
|
|
SheetJS API methods use DOM features that may not be available.
|
|
|
|
### Table rows
|
|
|
|
The `rows` property of TABLE elements is a list of TR row children. This list
|
|
automatically updates when rows are added and deleted.
|
|
|
|
SheetJS does not mutate `rows`. Assuming there are no nested tables, the `rows`
|
|
property can be created using `getElementsByTagName`:
|
|
|
|
```js
|
|
tbl.rows = Array.from(tbl.getElementsByTagName("tr"));
|
|
```
|
|
|
|
### Row cells
|
|
|
|
The `cells` property of TR elements is a list of TD cell children. This list
|
|
automatically updates when cells are added and deleted.
|
|
|
|
SheetJS does not mutate `cells`. Assuming there are no nested tables, the
|
|
`cells` property can be created using `getElementsByTagName`:
|
|
|
|
```js
|
|
tbl.rows.forEach(row => row.cells = Array.from(row.getElementsByTagName("td")));
|
|
```
|
|
|
|
## NodeJS
|
|
|
|
### JSDOM
|
|
|
|
JSDOM is a DOM implementation for NodeJS. The synthetic DOM elements are
|
|
compatible with SheetJS methods.
|
|
|
|
The following example scrapes the first table from the file `SheetJSTable.html`
|
|
and generates a XLSX workbook:
|
|
|
|
```js title="SheetJSDOM.js"
|
|
const XLSX = require("xlsx");
|
|
const { readFileSync } = require("fs");
|
|
const { JSDOM } = require("jsdom");
|
|
|
|
/* obtain HTML string. This example reads from SheetJSTable.html */
|
|
const html_str = readFileSync("SheetJSTable.html", "utf8");
|
|
|
|
// highlight-start
|
|
/* get first TABLE element */
|
|
const doc = new JSDOM(html_str).window.document.querySelector("table");
|
|
|
|
/* generate workbook */
|
|
const workbook = XLSX.utils.table_to_book(doc);
|
|
// highlight-end
|
|
|
|
XLSX.writeFile(workbook, "SheetJSDOM.xlsx");
|
|
```
|
|
|
|
<details><summary><b>Complete Demo</b> (click to show)</summary>
|
|
|
|
:::note
|
|
|
|
This demo was last tested on 2023 September 10 against JSDOM `22.1.0`
|
|
|
|
:::
|
|
|
|
1) Install SheetJS and JSDOM libraries:
|
|
|
|
<CodeBlock language="bash">{`\
|
|
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz jsdom@22.0.0`}
|
|
</CodeBlock>
|
|
|
|
2) Save the previous codeblock to `SheetJSDOM.js`.
|
|
|
|
3) Download [the sample `SheetJSTable.html`](pathname:///dom/SheetJSTable.html):
|
|
|
|
```bash
|
|
curl -LO https://docs.sheetjs.com/dom/SheetJSTable.html
|
|
```
|
|
|
|
4) Run the script:
|
|
|
|
```bash
|
|
node SheetJSDOM.js
|
|
```
|
|
|
|
The script will create a file `SheetJSDOM.xlsx` that can be opened.
|
|
|
|
</details>
|
|
|
|
### HappyDOM
|
|
|
|
HappyDOM provides a DOM framework for NodeJS. For the tested version (`11.0.2`),
|
|
the following patches were needed:
|
|
|
|
- TABLE `rows` property (explained above)
|
|
- TR `cells` property (explained above)
|
|
|
|
<details><summary><b>Complete Demo</b> (click to show)</summary>
|
|
|
|
:::note
|
|
|
|
This demo was last tested on 2023 September 10 against HappyDOM `11.0.2`
|
|
|
|
:::
|
|
|
|
1) Install SheetJS and HappyDOM libraries:
|
|
|
|
<CodeBlock language="bash">{`\
|
|
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz happy-dom@11.0.2`}
|
|
</CodeBlock>
|
|
|
|
2) Download [the sample script `SheetJSHappyDOM.js`](pathname:///dom/SheetJSHappyDOM.js):
|
|
|
|
```bash
|
|
curl -LO https://docs.sheetjs.com/dom/SheetJSHappyDOM.js
|
|
```
|
|
|
|
3) Run the script:
|
|
|
|
```bash
|
|
node SheetJSHappyDOM.js
|
|
```
|
|
|
|
The script will create a file `SheetJSHappyDOM.xlsx` that can be opened.
|
|
|
|
</details>
|
|
|
|
### XMLDOM
|
|
|
|
XMLDOM provides a DOM framework for NodeJS. For the tested version (`0.8.10`),
|
|
the following patches were needed:
|
|
|
|
- TABLE `rows` property (explained above)
|
|
- TR `cells` property (explained above)
|
|
- Element `innerHTML` property:
|
|
|
|
```js
|
|
Object.defineProperty(tbl.__proto__, "innerHTML", { get: function() {
|
|
var outerHTML = new XMLSerializer().serializeToString(this);
|
|
if(outerHTML.match(/</g).length == 1) return "";
|
|
return outerHTML.slice(0, outerHTML.lastIndexOf("</")).replace(/<[^"'>]*(("[^"]*"|'[^']*')[^"'>]*)*>/, "");
|
|
}});
|
|
```
|
|
|
|
<details><summary><b>Complete Demo</b> (click to show)</summary>
|
|
|
|
:::note
|
|
|
|
This demo was last tested on 2023 September 10 against XMLDOM `0.8.10`
|
|
|
|
:::
|
|
|
|
1) Install SheetJS and XMLDOM libraries:
|
|
|
|
<CodeBlock language="bash">{`\
|
|
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz @xmldom/xmldom@0.8.10`}
|
|
</CodeBlock>
|
|
|
|
2) Download [the sample script `SheetJSXMLDOM.js`](pathname:///dom/SheetJSXMLDOM.js):
|
|
|
|
```bash
|
|
curl -LO https://docs.sheetjs.com/dom/SheetJSXMLDOM.js
|
|
```
|
|
|
|
3) Run the script:
|
|
|
|
```bash
|
|
node SheetJSXMLDOM.js
|
|
```
|
|
|
|
The script will create a file `SheetJSXMLDOM.xlsx` that can be opened.
|
|
|
|
</details>
|
|
|
|
### CheerioJS
|
|
|
|
:::caution pass
|
|
|
|
Cheerio does not support a number of fundamental properties out of the box. They
|
|
can be shimmed, but it is strongly recommended to use a more compliant library.
|
|
|
|
:::
|
|
|
|
CheerioJS provides a DOM-like framework for NodeJS. Many features were missing.
|
|
[`SheetJSCheerio.js`](pathname:///dom/SheetJSCheerio.js) implements the missing
|
|
features to ensure that SheetJS DOM methods can process TABLE elements.
|
|
|
|
<details><summary><b>Complete Demo</b> (click to show)</summary>
|
|
|
|
:::note
|
|
|
|
This demo was last tested on 2023 September 10 against Cheerio `1.0.0-rc.12`
|
|
|
|
:::
|
|
|
|
1) Install SheetJS and CheerioJS libraries:
|
|
|
|
<CodeBlock language="bash">{`\
|
|
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz cheerio@1.0.0-rc.12`}
|
|
</CodeBlock>
|
|
|
|
2) Download [the sample script `SheetJSCheerio.js`](pathname:///dom/SheetJSCheerio.js):
|
|
|
|
```bash
|
|
curl -LO https://docs.sheetjs.com/dom/SheetJSCheerio.js
|
|
```
|
|
|
|
3) Download [the sample `SheetJSTable.html`](pathname:///dom/SheetJSTable.html):
|
|
|
|
```bash
|
|
curl -LO https://docs.sheetjs.com/dom/SheetJSTable.html
|
|
```
|
|
|
|
4) Run the script:
|
|
|
|
```bash
|
|
node SheetJSCheerio.js
|
|
```
|
|
|
|
The script will create a file `SheetJSCheerio.xlsx` that can be opened.
|
|
|
|
</details>
|
|
|
|
## Other Platforms
|
|
|
|
### DenoDOM
|
|
|
|
DenoDOM provides a DOM framework for Deno. For the tested version (`0.1.38`),
|
|
the following patches were needed:
|
|
|
|
- TABLE `rows` property (explained above)
|
|
- TR `cells` property (explained above)
|
|
|
|
This example fetches [a sample table](pathname:///dom/SheetJSTable.html):
|
|
|
|
<CodeBlock language="ts" title="SheetJSDenoDOM.ts">{`\
|
|
// @deno-types="https://cdn.sheetjs.com/xlsx-${current}/package/types/index.d.ts"
|
|
import * as XLSX from 'https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs';
|
|
\n\
|
|
import { DOMParser } from 'https://deno.land/x/deno_dom@v0.1.38/deno-dom-wasm.ts';
|
|
\n\
|
|
const doc = new DOMParser().parseFromString(
|
|
await (await fetch('https://docs.sheetjs.com/dom/SheetJSTable.html')).text(),
|
|
"text/html",
|
|
)!;
|
|
// highlight-start
|
|
const tbl = doc.querySelector("table");
|
|
\n\
|
|
/* patch DenoDOM element */
|
|
tbl.rows = tbl.querySelectorAll("tr");
|
|
tbl.rows.forEach(row => row.cells = row.querySelectorAll("td, th"))
|
|
\n\
|
|
/* generate workbook */
|
|
const workbook = XLSX.utils.table_to_book(tbl);
|
|
// highlight-end
|
|
XLSX.writeFile(workbook, "SheetJSDenoDOM.xlsx");`}
|
|
</CodeBlock>
|
|
|
|
<details><summary><b>Complete Demo</b> (click to show)</summary>
|
|
|
|
:::note
|
|
|
|
This demo was last tested on 2023 September 10 against DenoDOM `0.1.38`
|
|
|
|
:::
|
|
|
|
1) Save the previous codeblock to `SheetJSDenoDOM.ts`.
|
|
|
|
2) Run the script with `--allow-net` and `--allow-write` entitlements:
|
|
|
|
```bash
|
|
deno run --allow-net --allow-write SheetJSDenoDOM.ts
|
|
```
|
|
|
|
The script will create a file `SheetJSDenoDOM.xlsx` that can be opened.
|
|
|
|
</details>
|
|
|
|
[^1]: See ["HTML Table Input" in "Utilities"](/docs/api/utilities/html#html-table-input)
|
|
[^2]: See ["Worksheet Object" in "SheetJS Data Model"](/docs/csf/book) for more details.
|
|
[^3]: See ["Workbook Object" in "SheetJS Data Model"](/docs/csf/book) for more details.
|