docs.sheetjs.com/docz/docs/03-demos/10-extensions/03-excelapi.md

210 lines
6.0 KiB
Markdown
Raw Normal View History

2022-05-31 02:53:56 +00:00
---
2022-08-26 05:39:17 +00:00
title: Excel JavaScript API
2023-02-28 11:40:44 +00:00
pagination_prev: demos/cloud/index
pagination_next: demos/bigdata/index
2022-05-31 02:53:56 +00:00
---
2023-04-27 09:12:19 +00:00
import current from '/version.js';
2023-05-07 13:58:36 +00:00
import CodeBlock from '@theme/CodeBlock';
2023-04-27 09:12:19 +00:00
2022-08-30 22:12:52 +00:00
:::info
This demo focuses on the JavaScript API included with Excel. For reading and
2022-09-07 20:32:46 +00:00
writing Excel files, [other demos](/docs/demos/) cover a wide variety of use cases
2022-08-30 22:12:52 +00:00
:::
2022-05-31 02:53:56 +00:00
Office 2016 introduced a JavaScript API for interacting with the application.
It offers solutions for custom functions as well as task panes.
Excel currently does not provide support for working with Apple Numbers files
and some legacy file formats. SheetJS fills the gap.
2023-04-21 00:53:38 +00:00
This demo creates a new custom function `SHEETJS.EXTERN()` which tries to fetch
an external spreadsheet and insert the data into the worksheet.
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
![`SHEETJS.EXTERN` output](pathname:///xlapi/xlfetch.png)
2022-05-31 02:53:56 +00:00
This demo focuses on the basic mechanics. Advanced topics like Excel Custom
Function parameters are covered in the official Office JavaScript API docs.
2023-04-21 00:53:38 +00:00
:::note
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
This demo was last tested on 2023 April 20 against Excel 365 (version 2303)
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
:::
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
:::caution Excel Bugs
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
There was a binary data bug affecting `fetch` and Excel. It was resolved in
version 2303. It is strongly encouraged to upgrade to the latest version of
Excel 365 before running the demo.
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
:::
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
## Integration Details
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
The [NodeJS module](/docs/getting-started/installation/nodejs) can be imported
in an Excel Custom Functions project.
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
The [`sheet_to_json`](/docs/api/utilities#json) helper function can generate
arrays of arrays of values based on the worksheet data. Excel custom functions
transparently treat these as Dynamic Arrays.
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
This example fetches a file, parses the data, and extracts the first worksheet:
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
```js title="src\functions\functions.js"
2022-05-31 02:53:56 +00:00
var XLSX = require("xlsx");
/**
2023-04-21 00:53:38 +00:00
* Download file and write data
2022-05-31 02:53:56 +00:00
* @customfunction
2023-04-21 00:53:38 +00:00
* @param {string} url URL to fetch and parse
* @returns {any[][]} Worksheet data
2022-05-31 02:53:56 +00:00
*/
2023-04-21 00:53:38 +00:00
async function extern(url) {
try {
/* Fetch Data */
const res = await fetch(url);
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
/* Get Data */
const ab = await res.arrayBuffer();
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
/* Parse Data */
var wb = XLSX.read(ab);
/* get and return data */
var ws = wb.Sheets[wb.SheetNames[0]]; // get first worksheet
var aoa = XLSX.utils.sheet_to_json(ws, { header: 1 }); // array of arrays
return aoa;
} catch(e) { return [[e.message || e]]; } // pass error back to Excel
}
2022-05-31 02:53:56 +00:00
```
2023-04-21 00:53:38 +00:00
## Complete Demo
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
0) Clear the functions cache. For the tested version of Excel:
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
- Open File Explorer
- Select the address bar and enter `%LOCALAPPDATA%\Microsoft\Office\16.0\Wef`
- Delete `CustomFunctions` and empty Recycle Bin.
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
1) Install [NodeJS LTS](https://nodejs.org/en/download/).
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
2) Install dependencies in a new PowerShell window:
2022-05-31 02:53:56 +00:00
2023-05-11 21:28:29 +00:00
```bash
2023-05-07 13:58:36 +00:00
npm i -g yo bower generator-office
2023-04-21 00:53:38 +00:00
```
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
### Creating a new Add-in
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
3) Run `yo office` from the command line. It will ask a few questions:
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
- "Choose a project type": "Excel Custom Functions using a Shared Runtime"
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
- "Choose a script type": "JavaScript",
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
- "What do you want to name your add-in?": "SheetJSImport"
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
4) Start the dev process:
2022-05-31 02:53:56 +00:00
2023-05-11 21:28:29 +00:00
```bash
2023-04-21 00:53:38 +00:00
cd SheetJSImport
npm run build
npm start
2022-05-31 02:53:56 +00:00
```
2023-04-21 00:53:38 +00:00
Running `npm start` will open up a terminal window and a new Excel window with
the loaded add-in. Keep the terminal window open.
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
5) In `manifest.xml` , search for `Functions.NameSpace` . There will be an XML
element with name `bt:String`. Change the `DefaultValue` attribute to `SHEETJS`:
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
```xml title="manifest.xml"
<bt:ShortStrings>
// highlight-next-line
<bt:String id="Functions.Namespace" DefaultValue="SHEETJS"/>
<bt:String id="GetStarted.Title" DefaultValue="Get started with your sample add-in!" />
```
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
6) Close the Excel window and the terminal window, then run `npm start` again.
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
### Integrating the SheetJS Library
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
7) Install the SheetJS library in the project
2022-05-31 02:53:56 +00:00
2023-05-07 13:58:36 +00:00
<CodeBlock language="bash">{`\
2023-04-27 09:12:19 +00:00
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
8) Replace `src\functions\functions.js` with the following:
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
```js title="src\functions\functions.js"
var XLSX = require("xlsx");
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
/**
* Print SheetJS Library Version
* @customfunction
* @returns {string[][]} The SheetJS Library Version.
*/
function version() {
return [[XLSX.version]];
}
```
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
9) After making the change, save the files. Close the terminal window and the
Excel window (do not save the Excel file). Re-run `npm start`.
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
10) In the new Excel window, enter the formula `=SHEETJS.VERSION()` in cell
`E1`. You should see something similar to the following screenshot:
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
![`SHEETJS.VERSION` output](pathname:///xlapi/xlvers.png)
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
This indicates that the SheetJS library has been loaded.
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
### Fetching Files from the Internet
2022-05-31 02:53:56 +00:00
2023-04-21 00:53:38 +00:00
11) Add the following code snippet to `src\functions\functions.js`:
2022-05-31 02:53:56 +00:00
```js src\functions\functions.js
/**
* Download file and write data
* @customfunction
2023-04-21 00:53:38 +00:00
* @param {string} url URL to fetch and parse
2022-05-31 02:53:56 +00:00
* @returns {any[][]} Worksheet data
*/
2023-04-21 00:53:38 +00:00
async function extern(url) {
2022-05-31 02:53:56 +00:00
try {
/* Fetch Data */
const res = await fetch(url);
/* Get Data */
2023-04-21 00:53:38 +00:00
const ab = await res.arrayBuffer();
2022-05-31 02:53:56 +00:00
/* Parse Data */
2023-04-21 00:53:38 +00:00
var wb = XLSX.read(ab);
2022-05-31 02:53:56 +00:00
/* get and return data */
var ws = wb.Sheets[wb.SheetNames[0]]; // get first worksheet
var aoa = XLSX.utils.sheet_to_json(ws, { header: 1 }); // get data as array of arrays
2023-01-14 03:13:35 +00:00
return aoa;
} catch(e) { return [[e.message || e]]; } // pass error back to Excel
2022-05-31 02:53:56 +00:00
}
```
2023-04-21 00:53:38 +00:00
12) After making the change, save the files. Close the terminal window and the
2022-05-31 02:53:56 +00:00
Excel window (do not save the Excel file). Re-run `npm start`.
2023-04-21 00:53:38 +00:00
13) Enter the text `https://sheetjs.com/pres.numbers` in cell `D1`. Enter the
formula `=SHEETJS.EXTERN(D1)` in cell `D2` and press Enter. Excel should pull
in the data and generate a dynamic array.
2022-05-31 02:53:56 +00:00
2023-01-14 03:13:35 +00:00
:::note
2022-05-31 02:53:56 +00:00
[SheetJS Pro](https://sheetjs.com/pro) offers additional features that can be
2022-09-07 20:32:46 +00:00
used in Excel Custom Functions and Add-ins
2023-01-14 03:13:35 +00:00
:::