docs.sheetjs.com/docz/docs/02-getting-started/01-installation/01-standalone.mdx

222 lines
7.4 KiB
Plaintext
Raw Normal View History

2022-05-16 03:26:04 +00:00
---
title: Standalone Browser Scripts
2022-08-24 23:48:22 +00:00
pagination_prev: getting-started/index
2023-07-26 20:18:07 +00:00
pagination_next: getting-started/examples/index
2022-05-16 03:26:04 +00:00
sidebar_position: 1
sidebar_custom_props:
summary: Classic pages with simple <script> tags
---
import current from '/version.js';
2023-05-07 13:58:36 +00:00
import CodeBlock from '@theme/CodeBlock';
2022-05-16 03:26:04 +00:00
Each standalone release script is available at https://cdn.sheetjs.com/.
2022-05-16 03:26:04 +00:00
2023-05-07 13:58:36 +00:00
<p>The current version is {current} and can be referenced as follows:</p>
2022-05-16 03:26:04 +00:00
2023-05-07 13:58:36 +00:00
<CodeBlock language="html">{`\
2022-05-16 03:26:04 +00:00
<!-- use version ${current} -->
<script lang="javascript" 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
2023-06-25 09:36:58 +00:00
:::tip pass
2022-05-16 03:26:04 +00:00
2023-04-27 09:12:19 +00:00
[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!
:::
2022-05-16 03:26:04 +00:00
2023-08-23 08:05:30 +00:00
:::warning pass
2022-07-25 23:18:00 +00:00
2022-08-25 08:22:28 +00:00
A number of services host older versions of the SheetJS libraries. Due to
syncing issues, they are generally out of date.
2022-07-25 23:18:00 +00:00
**The SheetJS CDN** https://cdn.sheetjs.com/ **is the authoritative source**
2023-08-23 08:05:30 +00:00
**for SheetJS scripts**
2022-07-25 23:18:00 +00:00
:::
2022-05-16 03:26:04 +00:00
2022-06-05 22:43:44 +00:00
## Browser Scripts
2022-05-16 03:26:04 +00:00
`xlsx.full.min.js` is the complete standalone script. It includes support for
2022-06-05 22:43:44 +00:00
reading and writing many spreadsheet formats.
2022-05-16 03:26:04 +00:00
2023-05-07 13:58:36 +00:00
<CodeBlock language="html">{`\
2022-06-05 22:43:44 +00:00
<!-- use xlsx.full.min.js from version ${current} -->
<script lang="javascript" 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
`xlsx.mini.min.js` is a slimmer build that omits the following features:
2022-05-16 03:26:04 +00:00
- CSV and SYLK encodings (directly affecting users outside of the United States)
- XLSB / XLS / Lotus 1-2-3 / SpreadsheetML 2003 / Numbers file formats
- Stream utility functions
2022-05-16 03:26:04 +00:00
<details>
<summary><b>How to integrate the mini build</b> (click to show)</summary>
2022-06-05 22:43:44 +00:00
Replace references to `xlsx.full.min.js` with `xlsx.mini.min.js`. Starting from
scratch, a single script tag should be added at the top of the HTML page:
2022-05-16 03:26:04 +00:00
2023-05-07 13:58:36 +00:00
<CodeBlock language="html">{`\
2022-05-16 03:26:04 +00:00
<!-- use xlsx.mini.min.js from version ${current} -->
<script lang="javascript" src="https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.mini.min.js"></script>`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2022-05-16 03:26:04 +00:00
</details>
2023-08-23 08:05:30 +00:00
### Vendoring
For general stability, making a local copy of SheetJS scripts ("vendoring") is
strongly recommended. Vendoring decouples websites from SheetJS infrastructure.
2023-08-23 08:05:30 +00:00
<ol start="1"><li><p>Download the script (<code parentName="pre">xlsx.full.min.js</code>) for
the desired version. The current version is available at <a href={"https://cdn.sheetjs.com/xlsx-" + current + "/package/dist/xlsx.full.min.js"}>{"https://cdn.sheetjs.com/xlsx-" + current + "/package/dist/xlsx.full.min.js"}</a></p></li></ol>
2023-08-23 08:05:30 +00:00
2) Move the script to a `public` folder with other scripts.
3) Reference the local script from HTML pages:
```html
<script src="/public/xlsx.full.min.js"></script>
```
This script assigns to `window.XLSX`. The global can be used in other scripts.
2022-06-05 22:43:44 +00:00
### Internet Explorer and Older Browsers
2022-05-16 03:26:04 +00:00
For broad compatibility with JavaScript engines, the library is written using
2022-06-05 22:43:44 +00:00
ECMAScript 3 language dialect. A "shim" script provides implementations of
functions for older browsers and environments.
2023-05-07 13:58:36 +00:00
Due to SSL compatibility issues, older versions of IE will not be able to
2022-06-05 22:43:44 +00:00
use the CDN scripts directly. They should be downloaded and saved to a public
directory in the site:
2023-05-07 13:58:36 +00:00
2022-06-05 22:43:44 +00:00
<ul>
<li>Standalone: <a href={"https://cdn.sheetjs.com/xlsx-" + current + "/package/dist/xlsx.mini.min.js"}>{"https://cdn.sheetjs.com/xlsx-" + current + "/package/dist/xlsx.mini.min.js"}</a></li>
<li>Shim: <a href={"https://cdn.sheetjs.com/xlsx-" + current + "/package/dist/shim.min.js"}>{"https://cdn.sheetjs.com/xlsx-" + current + "/package/dist/shim.min.js"}</a></li>
2022-06-05 22:43:44 +00:00
</ul>
2022-05-16 03:26:04 +00:00
A `script` reference to the shim must be added before the standalone script:
2022-05-16 03:26:04 +00:00
```html
<!-- add the shim first -->
<script type="text/javascript" src="shim.min.js"></script>
<!-- after the shim is referenced, add the library -->
<script type="text/javascript" src="xlsx.full.min.js"></script>
```
2022-06-05 22:43:44 +00:00
### Web Workers
2022-05-16 03:26:04 +00:00
2022-06-05 22:43:44 +00:00
The standalone scripts can be loaded using `importScripts` at the top of the
worker scripts:
2023-05-07 13:58:36 +00:00
<CodeBlock language="js">{`\
2022-06-05 22:43:44 +00:00
importScripts("https://cdn.sheetjs.com/xlsx-${current}/package/dist/shim.min.js");
importScripts("https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js");`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2022-05-16 03:26:04 +00:00
2022-10-21 00:10:10 +00:00
## ECMAScript Module Imports
2022-06-05 22:43:44 +00:00
2023-08-23 08:05:30 +00:00
:::caution pass
2022-06-05 22:43:44 +00:00
This section refers to imports in HTML pages using `script type="module"`.
The ["Frameworks and Bundlers"](/docs/getting-started/installation/frameworks)
section covers imports in projects using bundlers (ViteJS) or frameworks
(Kaioken / ReactJS / Angular / VueJS / Svelte)
2022-06-05 22:43:44 +00:00
:::
2022-05-16 03:26:04 +00:00
The ECMAScript Module build is saved to `xlsx.mjs` and can be directly added to
a page with a `script` tag using `type="module"`:
2023-05-07 13:58:36 +00:00
<CodeBlock language="html">{`\
2022-05-16 03:26:04 +00:00
<script type="module">
import { read, writeFileXLSX } from "https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs";
</script>`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2022-05-16 03:26:04 +00:00
2022-08-26 19:21:53 +00:00
If Encoding support is required, `cpexcel.full.mjs` must be manually imported:
2022-05-16 03:26:04 +00:00
2023-05-07 13:58:36 +00:00
<CodeBlock language="html">{`\
2022-05-16 03:26:04 +00:00
<script type="module">
/* load the codepage support library for extended support with older formats */
import { set_cptable } from "https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs";
import * as cptable from 'https://cdn.sheetjs.com/xlsx-${current}/package/dist/cpexcel.full.mjs';
set_cptable(cptable);
</script>`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2022-05-16 03:26:04 +00:00
2023-08-23 08:05:30 +00:00
Web Worker support is noted in [the "Web Workers" demo](/docs/demos/bigdata/worker#installation)
### Dynamic Imports
Dynamic imports with `import()` will only download the SheetJS scripts when they
are used. This example will download the library when data is exported:
2022-06-05 22:43:44 +00:00
2023-05-07 13:58:36 +00:00
<CodeBlock language="html">{`\
2022-06-05 22:43:44 +00:00
<button id="xport">Export</button>
<script type="module">
xport.addEventListener("click", async() => {
2023-05-07 13:58:36 +00:00
\n\
2023-08-23 08:05:30 +00:00
/* dynamically import the script in the event listener */
2022-06-05 22:43:44 +00:00
// highlight-next-line
const XLSX = await import("https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs");
2023-05-07 13:58:36 +00:00
\n\
2022-06-05 22:43:44 +00:00
const wb = XLSX.utils.book_new();
const ws = XLSX.utils.aoa_to_sheet([["a","b","c"],[1,2,3]]);
XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "SheetJSESMTest.xlsx");
});
</script>`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2022-06-05 22:43:44 +00:00
2023-08-23 08:05:30 +00:00
:::caution pass
The callback functions must be marked as `async` and the script block must have
the attribute `type="module"`
:::
If Encoding support is required, `cpexcel.full.mjs` must be manually imported:
<CodeBlock language="html">{`\
<button id="xport">Export</button>
<script type="module">
xport.addEventListener("click", async() => {
\n\
/* dynamically import the scripts in the event listener */
// highlight-start
const XLSX = await import("https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs");
const cptable = await import("https://cdn.sheetjs.com/xlsx-${current}/package/dist/cpexcel.full.mjs");
XLSX.set_cptable(cptable);
// highlight-end
\n\
const wb = XLSX.utils.book_new();
const ws = XLSX.utils.aoa_to_sheet([["a","b","c"],[1,2,3]]);
XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "SheetJSESMTest.xlsx");
});
</script>`}
</CodeBlock>
2022-06-05 22:43:44 +00:00
## Bower
2023-08-23 08:05:30 +00:00
:::warning pass
2022-06-05 22:43:44 +00:00
Bower is deprecated and the maintainers recommend using other tools.
:::
The Bower package manager supports tarballs from the SheetJS CDN:
2022-06-05 22:43:44 +00:00
2023-05-07 13:58:36 +00:00
<CodeBlock language="bash">{`\
2022-08-07 07:48:40 +00:00
npx bower install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2022-06-05 22:43:44 +00:00
Bower will place the standalone scripts in `bower_components/js-xlsx/dist/`