docs.sheetjs.com/docz/docs/02-getting-started/01-installation/01-standalone.mdx
2023-06-25 14:44:00 -04:00

173 lines
5.6 KiB
Plaintext

---
pagination_prev: getting-started/index
pagination_next: getting-started/example
sidebar_position: 1
sidebar_custom_props:
summary: Classic pages with simple <script> tags
---
import current from '/version.js';
import CodeBlock from '@theme/CodeBlock';
# Standalone Browser Scripts
Each standalone release script is available at <https://cdn.sheetjs.com/>.
<p>The current version is {current} and can be referenced as follows:</p>
<CodeBlock language="html">{`\
<!-- use version ${current} -->
<script lang="javascript" src="https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js"></script>`}
</CodeBlock>
:::tip pass
[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!
:::
:::warning
A number of services host older versions of the SheetJS libraries. Due to
syncing issues, they are generally out of date.
They are known CDN bugs.
<https://cdn.sheetjs.com/> is the authoritative source for SheetJS modules.
:::
## Browser Scripts
`xlsx.full.min.js` is the complete standalone script. It includes support for
reading and writing many spreadsheet formats.
<CodeBlock language="html">{`\
<!-- 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>`}
</CodeBlock>
A slimmer build is generated at `dist/xlsx.mini.min.js`. Compared to full build:
- codepage library skipped (no support for XLS encodings)
- no support for XLSB / XLS / Lotus 1-2-3 / SpreadsheetML 2003 / Numbers
- node stream utils removed
<details><summary><b>How to integrate the mini build</b> (click to show)</summary>
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:
<CodeBlock language="html">{`\
<!-- 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>`}
</CodeBlock>
</details>
### Internet Explorer and Older Browsers
For broad compatibility with JavaScript engines, the library is written using
ECMAScript 3 language dialect. A "shim" script provides implementations of
functions for older browsers and environments.
Due to SSL compatibility issues, older versions of IE will not be able to
use the CDN scripts directly. They should be downloaded and saved to a public
directory in the site:
<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>
</ul>
Add a `script` reference to the shim before the standalone script:
```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>
```
### Web Workers
The standalone scripts can be loaded using `importScripts` at the top of the
worker scripts:
<CodeBlock language="js">{`\
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");`}
</CodeBlock>
## ECMAScript Module Imports
:::caution
This section refers to imports using `script type="module"`. For imports in
modern projects using Webpack or React or Angular or VueJS, the installation is
described [in the next section](/docs/getting-started/installation/frameworks).
:::
The ECMAScript Module build is saved to `xlsx.mjs` and can be directly added to
a page with a `script` tag using `type="module"`:
<CodeBlock language="html">{`\
<script type="module">
import { read, writeFileXLSX } from "https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs";
</script>`}
</CodeBlock>
If Encoding support is required, `cpexcel.full.mjs` must be manually imported:
<CodeBlock language="html">{`\
<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>`}
</CodeBlock>
Dynamic imports with `import()` can be used in data export scenarios. This
example will download the library only when the export button is pressed:
<CodeBlock language="html">{`\
<button id="xport">Export</button>
<script type="module">
xport.addEventListener("click", async() => {
\n\
/* dynamically import the library in the event listener */
// highlight-next-line
const XLSX = await import("https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs");
\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>
Web Worker support is noted in [the demo](/docs/demos/bigdata/worker#installation)
## Bower
:::caution
Bower is deprecated and the maintainers recommend using other tools.
:::
The Bower package manager plays nice with the CDN tarballs:
<CodeBlock language="bash">{`\
npx bower install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</CodeBlock>
Bower will place the standalone scripts in `bower_components/js-xlsx/dist/`