Edit

Share via

Referencing the Office JavaScript API library

  • Article

The Office JavaScript API library provides the APIs that your add-in can use to interact with the Office application. The simplest way to reference the library is to use the content delivery network (CDN) by adding the following <script> tag within the <head> section of your HTML page.

<head>
    ...
    <script src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js" type="text/javascript"></script>
</head>

This will download and cache the Office JavaScript API files the first time your add-in loads to make sure that it is using the most up-to-date implementation of Office.js and its associated files for the specified version.

Important

You must reference the Office JavaScript API from inside the <head> section of the page to ensure that the API is fully initialized prior to any body elements.

API versioning and backward compatibility

In the previous HTML snippet, the /1.1/ in front of office.js in the CDN URL specifies the latest incremental release within version 1 of Office.js. Because the Office JavaScript API maintains backward compatibility, the latest release will continue to support API members that were introduced earlier in version 1.

If you plan to publish your Office Add-in from AppSource, you must use this CDN reference. Local references are only appropriate for internal, development, and debugging scenarios.

Note

To use preview APIs, reference the preview version of the Office JavaScript API library on the CDN: https://appsforoffice.microsoft.com/lib/beta/hosted/office.js.

Enabling IntelliSense for a TypeScript project

In addition to referencing the Office JavaScript API as described previously, you can also enable IntelliSense for TypeScript add-in project by using the type definitions from DefinitelyTyped. To do so, run the following command in a Node-enabled system prompt (or git bash window) from the root of your project folder. You must have Node.js installed (which includes npm).

npm install --save-dev @types/office-js

Preview APIs

New JavaScript APIs are first introduced in "preview" and later become part of a specific numbered requirement set after sufficient testing occurs and user feedback is acquired.

Note

Preview APIs are subject to change and are not intended for use in a production environment. We recommend that you try them out in test and development environments only. Do not use preview APIs in a production environment or within business-critical documents.

To use preview APIs:

CDN references for other Microsoft 365 environments

21Vianet operates and manages an Office 365 service powered by licensed Microsoft technologies to provide Office 365 services for China compliant with local laws and regulations. Add-ins developed for use within this cloud environment should use corresponding CDN. Use https://appsforoffice.cdn.partner.office365.cn/appsforoffice/lib/1/hosted/office.js instead of the standard CDN reference. This ensures continued compliance and provides better add-in performance.

See also