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

title	pagination_prev	pagination_next
Excel JavaScript API	demos/cloud/index	demos/bigdata/index

import current from '/version.js'; import CodeBlock from '@theme/CodeBlock';

:::info pass

This demo focuses on the JavaScript API included with Excel. For reading and writing Excel files, other demos cover a wide variety of use cases

:::

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.

This demo creates a new custom function SHEETJS.EXTERN() which tries to fetch an external spreadsheet and insert the data into the worksheet.

This demo focuses on the basic mechanics. Advanced topics like Excel Custom Function parameters are covered in the official Office JavaScript API docs.

:::note

This demo was last tested on 2023 September 03 against Excel 365 (version 2308)

:::

:::caution Excel Bugs

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.

:::

Integration Details

The NodeJS module can be imported in an Excel Custom Functions project.

The sheet_to_json helper function can generate arrays of arrays of values based on the worksheet data. Excel custom functions transparently treat these as Dynamic Arrays.

This example fetches a file, parses the data, and extracts the first worksheet:

var XLSX = require("xlsx");

/**
 * Download file and write data
 * @customfunction
 * @param {string} url URL to fetch and parse
 * @returns {any[][]} Worksheet data
 */
async function extern(url) {
  try {
    /* Fetch Data */
    const res = await fetch(url);

    /* Get Data */
    const ab = await res.arrayBuffer();

    /* 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
}

Complete Demo

0. Clear the functions cache. For the tested version of Excel:

• Open File Explorer
• Select the address bar and enter %LOCALAPPDATA%\Microsoft\Office\16.0\Wef
• Delete the CustomFunctions folder (if it exists) and empty Recycle Bin.

:::caution pass

This will delete all custom functions associated with the user account!

To preserve the custom functions on the user account, rename the existing folder to CustomFunctionsBackup before testing and rename back to CustomFunctions after testing is finished.

:::

1. Install NodeJS LTS.

2. Install dependencies in a new PowerShell window:

npm i -g yo bower generator-office

Creating a new Add-in

3. Run yo office from the command line. It will ask a few questions:

• "Choose a project type": "Excel Custom Functions using a Shared Runtime"

• "Choose a script type": "JavaScript",

• "What do you want to name your add-in?": "SheetJSImport"

4. Start the dev process:

cd SheetJSImport
npm run build
npm start

Running npm start will open up a terminal window and a new Excel window with the loaded add-in. Keep the terminal window open.

5. In manifest.xml , search for Functions.NameSpace . There will be an XML element with name bt:String. Change the DefaultValue attribute to SHEETJS:

      <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!" />

6. Close the Excel window and the terminal window, then run npm start again.

Integrating the SheetJS Library

7. Install the SheetJS library in the project

{\ npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz}

8. Replace src\functions\functions.js with the following:

var XLSX = require("xlsx");

/**
 * Print SheetJS Library Version
 * @customfunction
 * @returns {string[][]} The SheetJS Library Version.
 */
function version() {
  return [[XLSX.version]];
}

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.

10. In the new Excel window, enter the formula =SHEETJS.VERSION() in cell D1. You should see something similar to the following screenshot:

This indicates that the SheetJS library has been loaded.

Fetching Files from the Internet

11. Add the following code snippet to src\functions\functions.js:

/**
 * Download file and write data
 * @customfunction
 * @param {string} url URL to fetch and parse
 * @returns {any[][]} Worksheet data
 */
async function extern(url) {
  try {
    /* Fetch Data */
    const res = await fetch(url);

    /* Get Data */
    const ab = await res.arrayBuffer();

    /* 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 }); // get data as array of arrays
    return aoa;
  } catch(e) { return [[e.message || e]]; } // pass error back to Excel
}

12. 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.

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.

:::tip pass

SheetJS Pro offers additional features that can be used in Excel Custom Functions and Add-ins

:::