docs.sheetjs.com/docz/docs/index.md

374 lines
9.5 KiB
Markdown
Raw Normal View History

2022-05-16 03:26:04 +00:00
---
sidebar_position: 1
hide_table_of_contents: true
2022-08-13 22:01:26 +00:00
title: Overview
2022-05-16 03:26:04 +00:00
---
2023-04-27 09:12:19 +00:00
import current from '/version.js';
2023-10-06 20:47:17 +00:00
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
2023-05-07 13:58:36 +00:00
import CodeBlock from '@theme/CodeBlock';
2023-04-27 09:12:19 +00:00
2022-05-16 03:26:04 +00:00
# SheetJS CE
SheetJS Community Edition offers battle-tested open-source solutions for
extracting useful data from almost any complex spreadsheet and generating new
spreadsheets that will work with legacy and modern software alike.
[SheetJS Pro](https://sheetjs.com/pro) offers solutions beyond data processing:
Edit complex templates with ease; let out your inner Picasso with styling; make
custom sheets with images/graphs/PivotTables; evaluate formula expressions and
port calculations to web apps; automate common spreadsheet tasks, and much more!
## Simple Examples
2022-08-24 00:51:18 +00:00
The code editors are live -- feel free to edit! They use ReactJS components and
run entirely in the web browser.
2022-05-16 03:26:04 +00:00
### Export an HTML Table to Excel XLSX
<details>
<summary><b>How to add to your site</b> (click to show)</summary>
2022-05-16 03:26:04 +00:00
2023-10-06 20:47:17 +00:00
<Tabs groupId="deployment">
<TabItem value="vanilla" label="HTML">
2022-05-16 03:26:04 +00:00
1) Make sure your table has an ID:
```html
<table id="TableToExport">
```
2023-04-27 09:12:19 +00:00
2) Include a reference to the SheetJS library in your page:
2022-05-16 03:26:04 +00:00
2023-05-07 13:58:36 +00:00
<CodeBlock language="html">{`\
2023-04-27 09:12:19 +00:00
<script src="https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js"></script>`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2022-05-16 03:26:04 +00:00
3) Add a button that users will click to generate an export
```html
<button id="sheetjsexport"><b>Export as XLSX</b></button>
```
2023-10-06 20:47:17 +00:00
4) Add an event handler for the `click` event to export table data to XLSX:
2022-05-16 03:26:04 +00:00
2022-08-24 00:51:18 +00:00
```html
<script>
2022-05-16 03:30:34 +00:00
document.getElementById("sheetjsexport").addEventListener('click', function() {
2022-05-16 03:26:04 +00:00
/* Create worksheet from HTML DOM TABLE */
var wb = XLSX.utils.table_to_book(document.getElementById("TableToExport"));
/* Export to file (start a download) */
XLSX.writeFile(wb, "SheetJSTable.xlsx");
});
2022-08-24 00:51:18 +00:00
</script>
2022-05-16 03:26:04 +00:00
```
2023-10-06 20:47:17 +00:00
</TabItem>
<TabItem value="react" label="React">
:::note pass
This example assumes you have an existing project with an HTML TABLE element:
```jsx title="Sample Component"
function App() {
return ( <>
2024-05-10 05:37:20 +00:00
<h3>SheetJS Table</h3>
<table>
<tr><td colSpan="3">SheetJS Table Export</td></tr>
<tr><td>Author</td><td>ID</td><td>你好!</td></tr>
<tr><td>SheetJS</td><td>7262</td><td>வணக்கம்!</td></tr>
<tr><td colSpan="3">
<a href="//sheetjs.com">Powered by SheetJS</a>
</td></tr>
</table>
2023-10-06 20:47:17 +00:00
</> )
}
export default App;
```
If you are starting from scratch, create a new ViteJS + ReactJS project:
```bash
npm create vite@latest -- sheetjs-react --template react --default
cd sheetjs-react
npm install
npm run dev
```
Replace `src/App.jsx` with the sample component.
:::
1) Install the SheetJS library using a package manager:
<Tabs groupId="pm">
<TabItem value="npm" label="npm">
<CodeBlock language="bash">{`\
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</CodeBlock>
</TabItem>
<TabItem value="pnpm" label="pnpm">
<CodeBlock language="bash">{`\
2024-03-20 07:05:29 +00:00
pnpm install --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
2023-10-06 20:47:17 +00:00
</CodeBlock>
</TabItem>
<TabItem value="yarn" label="Yarn" default>
<CodeBlock language="bash">{`\
yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</CodeBlock>
</TabItem>
</Tabs>
2) Ensure that your component script imports `useRef` from the `react` library:
```js
import { useRef } from "react";
```
3) Add the following line at the top of your component script:
```js
import { utils, writeFileXLSX } from "xlsx";
```
4) Create a ref in the body of your function component:
```jsx
function App() {
// highlight-next-line
const tbl = useRef(null);
// ...
```
5) Attach the ref to the table element:
```jsx
function App() {
// ...
return (
{/*...*/}
// highlight-next-line
<table ref={tbl}>
{/*...*/}
```
6) Add a button with a click handler that will export table data to XLSX:
```jsx
function App() {
// ...
return (
{/*...*/}
// highlight-start
<button onClick={() => {
// generate workbook from table element
const wb = utils.table_to_book(tbl.current);
// write to XLSX
writeFileXLSX(wb, "SheetJSReactExport.xlsx");
}}>Export XLSX</button>
// highlight-end
{/*...*/}
```
</TabItem>
</Tabs>
2022-05-16 03:26:04 +00:00
</details>
<details>
<summary><b>How to automate with NodeJS</b> (click to show)</summary>
2022-08-24 00:51:18 +00:00
2023-03-26 00:55:35 +00:00
[The "Headless Automation" demo](/docs/demos/net/headless) includes complete examples
2022-08-24 06:02:38 +00:00
using the `puppeteer` and `playwright` browser automation frameworks.
2022-08-24 00:51:18 +00:00
</details>
<details open>
<summary><b>Live Example</b> (click to hide)</summary>
2022-05-16 03:26:04 +00:00
2024-01-31 08:14:07 +00:00
This example uses a ReactJS `ref` to reference the HTML TABLE element. ReactJS
details are covered in the [ReactJS demo](/docs/demos/frontend/react#html)
2022-05-16 03:26:04 +00:00
```jsx live
/* The live editor requires this function wrapper */
function Table2XLSX(props) {
2024-01-31 08:14:07 +00:00
/* reference to the table element */
const tbl = React.useRef();
2022-05-16 03:26:04 +00:00
/* Callback invoked when the button is clicked */
2023-10-06 20:47:17 +00:00
const xport = React.useCallback(() => {
2022-08-26 19:21:53 +00:00
/* Create worksheet from HTML DOM TABLE */
2024-01-31 08:14:07 +00:00
const wb = XLSX.utils.table_to_book(tbl.current);
2022-05-16 03:26:04 +00:00
2022-08-26 19:21:53 +00:00
/* Export to file (start a download) */
XLSX.writeFile(wb, "SheetJSTable.xlsx");
2022-05-16 03:26:04 +00:00
});
2023-02-28 11:40:44 +00:00
return ( <>
2024-01-31 08:14:07 +00:00
<table ref={tbl}><tbody>
2022-05-16 03:26:04 +00:00
<tr><td colSpan="3">SheetJS Table Export</td></tr>
2022-08-04 03:00:20 +00:00
<tr><td>Author</td><td>ID</td><td>你好!</td></tr>
<tr><td>SheetJS</td><td>7262</td><td>வணக்கம்!</td></tr>
2022-05-16 03:26:04 +00:00
<tr><td colSpan="3">
<a href="//sheetjs.com">Powered by SheetJS</a>
</td></tr>
</tbody></table>
<button onClick={xport}><b>Export XLSX!</b></button>
2023-02-28 11:40:44 +00:00
</> );
2022-05-16 03:26:04 +00:00
}
```
<a href="https://sheetjs.com/pro">SheetJS Pro Basic</a> extends this export with
support for CSS styling and rich text.
</details>
2023-06-25 09:36:58 +00:00
### Download and Preview Apple Numbers Workbooks
2022-05-16 03:26:04 +00:00
<details>
<summary><b>How to add to your site</b> (click to show)</summary>
2022-05-16 03:26:04 +00:00
1) Create a container DIV for the table:
```html
<div id="TableContainer"></div>
```
2023-04-27 09:12:19 +00:00
2) Include a reference to the SheetJS library in your page:
2022-05-16 03:26:04 +00:00
2023-05-07 13:58:36 +00:00
<CodeBlock language="html">{`\
2023-04-27 09:12:19 +00:00
<script src="https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js"></script>`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2022-05-16 03:26:04 +00:00
3) Add a script block to download and update the page:
```html
<script>
(async() => {
2022-11-08 23:16:40 +00:00
/* replace with the URL of the file */
2024-04-26 04:16:13 +00:00
const URL_TO_DOWNLOAD = "https://docs.sheetjs.com/pres.numbers";
2022-11-08 23:16:40 +00:00
const ab = await (await fetch(URL_TO_DOWNLOAD)).arrayBuffer();
2022-05-16 03:26:04 +00:00
/* Parse file and get first worksheet */
const wb = XLSX.read(ab);
2022-11-08 23:16:40 +00:00
const wsname = wb.SheetNames[0];
const ws = wb.Sheets[wsname];
2022-05-16 03:26:04 +00:00
/* Generate HTML */
var output = document.getElementById("TableContainer");
output.innerHTML = XLSX.utils.sheet_to_html(ws);
})();
</script>
```
</details>
<details open>
<summary><b>Live Example</b> (click to hide)</summary>
2023-06-25 09:36:58 +00:00
2024-04-26 04:16:13 +00:00
This demo processes https://docs.sheetjs.com/pres.numbers
2022-05-16 03:26:04 +00:00
```jsx live
/* The live editor requires this function wrapper */
function Numbers2HTML(props) {
2022-10-21 00:10:10 +00:00
const [__html, setHTML] = React.useState("");
2022-05-16 03:26:04 +00:00
/* Fetch and update HTML */
2024-01-31 08:14:07 +00:00
React.useEffect(() => { (async() => {
2022-05-16 03:26:04 +00:00
/* Fetch file */
2024-04-26 04:16:13 +00:00
const f = await fetch("https://docs.sheetjs.com/pres.numbers");
2022-05-16 03:26:04 +00:00
const ab = await f.arrayBuffer();
/* Parse file */
const wb = XLSX.read(ab);
const ws = wb.Sheets[wb.SheetNames[0]];
/* Generate HTML */
setHTML(XLSX.utils.sheet_to_html(ws));
2024-01-31 08:14:07 +00:00
})(); }, []);
2022-05-16 03:26:04 +00:00
2023-02-28 11:40:44 +00:00
return ( <div dangerouslySetInnerHTML={{ __html }}/> );
2022-05-16 03:26:04 +00:00
}
```
<a href="https://sheetjs.com/pro">SheetJS Pro Basic</a> extends this import with
support for CSS styling and rich text.
</details>
2022-08-24 00:51:18 +00:00
### Preview a workbook on your device
2022-05-16 03:26:04 +00:00
<details open>
<summary><b>Live Example</b> (click to hide)</summary>
2022-08-24 00:51:18 +00:00
This example starts from a CSV string. Use the File Input element to select
a workbook to load. Use the "Export XLSX" button to write the table to XLSX.
2022-05-16 03:26:04 +00:00
```jsx live
/* The live editor requires this function wrapper */
function Tabeller(props) {
2022-08-24 00:51:18 +00:00
const [__html, setHTML] = React.useState("");
2022-05-16 03:26:04 +00:00
2022-08-24 00:51:18 +00:00
/* Load sample data once */
React.useEffect(() => {
/* Starting CSV data -- change data here */
const csv = `\
2022-05-16 03:26:04 +00:00
This,is,a,Test
வணக்கம்,สวัสดี,你好,가지마
1,2,3,4`;
2022-08-24 00:51:18 +00:00
/* Parse CSV into a workbook object */
const wb = XLSX.read(csv, {type: "string"});
2022-05-16 03:26:04 +00:00
2022-08-24 00:51:18 +00:00
/* Get the worksheet (default name "Sheet1") */
const ws = wb.Sheets.Sheet1;
2022-05-16 03:26:04 +00:00
2022-08-24 00:51:18 +00:00
/* Create HTML table */
setHTML(XLSX.utils.sheet_to_html(ws, { id: "tabeller" }));
}, []);
2022-05-16 03:26:04 +00:00
2023-02-28 11:40:44 +00:00
return ( <>
2022-08-24 00:51:18 +00:00
{/* Import Button */}
<input type="file" onChange={async(e) => {
/* get data as an ArrayBuffer */
const file = e.target.files[0];
const data = await file.arrayBuffer();
/* parse and load first worksheet */
const wb = XLSX.read(data);
const ws = wb.Sheets[wb.SheetNames[0]];
setHTML(XLSX.utils.sheet_to_html(ws, { id: "tabeller" }));
}}/>
2022-05-16 03:26:04 +00:00
{/* Export Button */}
<button onClick={() => {
/* Create worksheet from HTML DOM TABLE */
2022-08-24 00:51:18 +00:00
const table = document.getElementById("tabeller");
2022-05-16 03:26:04 +00:00
const wb = XLSX.utils.table_to_book(table);
/* Export to file (start a download) */
XLSX.writeFile(wb, "SheetJSIntro.xlsx");
2022-08-24 00:51:18 +00:00
}}><b>Export XLSX!</b></button>
2022-05-16 03:26:04 +00:00
2022-08-24 00:51:18 +00:00
{/* Show HTML preview */}
2022-10-21 00:10:10 +00:00
<div dangerouslySetInnerHTML={{ __html }}/>
2023-02-28 11:40:44 +00:00
</> );
2022-05-16 03:26:04 +00:00
}
```
</details>
### Browser Testing
[![Build Status](https://saucelabs.com/browser-matrix/sheetjs.svg)](https://saucelabs.com/u/sheetjs)
### Supported File Formats
2022-10-30 05:45:37 +00:00
![graph of format support](pathname:///formats.png)
2022-05-16 03:26:04 +00:00
2022-10-30 05:45:37 +00:00
![graph legend](pathname:///legend.png)