Excel JavaScript API requirement sets

Requirement sets are named groups of API members. Office Add-ins use requirement sets specified in the manifest or use a runtime check to determine whether an Office host supports APIs that an add-in needs. For more information, see Specify Office hosts and API requirements.

Excel add-ins run across multiple versions of Office, including Office 2016 for Windows, Office for iPad, Office for Mac, and Office Online. The following table lists the Excel requirement sets, the Office host applications that support that requirement set, and the build versions or number for those applications.

Note: Any API that is listed as beta is not ready for production usage. They are made available so that developers can try them out in test and development environments. They are not meant to be used against production/business critical documents.

For the requirement sets that are marked as Beta, use the specified (or later) version of the Office software and use the Beta library of the CDN: https://appsforoffice.microsoft.com/lib/beta/hosted/office.js. Entires not listed as Beta are generally available and you can continue to use Production CDN library: https://appsforoffice.microsoft.com/lib/1/hosted/office.js

*Note: The build number for Office 2016 installed via MSI is 16.0.4266.1001. This version only contains the ExcelApi 1.1 requirement set.

To find out more about versions, build numbers, and Office Online Server, see:

• Version and build numbers of update channel releases for Office 365 clients
• What version of Office am I using?
• Where you can find the version and build number for an Office 365 client application
• Office Online Server overview.aspx)

Runtime requirement support check

During the runtime, add-ins can check if a particular host supports an API requirement set by doing the following-check:

if (Office.context.requirements.isSetSupported('ExcelApi', 1.3) === true) {
  /// perform actions
}
else {
  /// provide alternate flow/logic
}

Manifest based requirement support check

Use the Requirements element in the add-in manifest to specify critical requirement sets or API members that your add-in must use. If the Office host or platform doesn't support the requirement sets or API members specified in the Requirements element, the add-in won't run in that host or platform, and won't display in My Add-ins. Instead, we recommend that you make your add-in available on all platforms of an Office host, such as Excel for Windows, Excel Online, and Excel for iPad. To make your add-in available on all Office hosts and platforms, use runtime checks instead of the Requirements element.

The following code example shows an add-in that loads in all Office host applications that support ExcelApi requirement set, version 1.3.

<Requirements>
   <Sets DefaultMinVersion="1.3">
      <Set Name="ExcelApi" MinVersion="1.3"/>
   </Sets>
</Requirements>

Office common API requirement sets

For information about common API requirement sets, see Office common API requirement sets.

Upcoming Excel 1.6 release features

Conditional formatting

Introduces Conditional formating of a range. Allows follwoing types of conditional formatting:

• Color scale
• Data bar
• Icon set
• Custom

In addiiton:

• Returns the range the conditonal format is applied to.
• Removal of conditional formatting.
• Provides priority and stopifTrue capability
• Get collection of all conditional formatting on a given range.
• Clears all conditional formats active on the current specified range.

For API details, please refer to the Excel API open specification.

Upcoming Excel 1.5 release features

Custom XML part

• Addition of custom XML parts collection to workbook object.
• Get custom XML part using ID
• Get a new scoped collection of custom XML parts whose namespaces match the given namespace.
• Get XML string associated with a part.
• Provide id and namespace of a part.
• Adds a new custom XML part to the workbook.
• Set entire XML part.
• Delete a custom XML part.
• Delete an attribute with the given name from the element identified by xpath.
• Query the XML content by xpath.
• Insert, update and delete attribute.

Reference implementation: Please refer here for a reference implementation that shows how custom XML parts can be used in an add-in.

Others

• range.getSurroundingRegion() Returns a Range object that represents the surrounding region for this range. A surrounding region is a range bounded by any combination of blank rows and blank columns relative to this range.
• getNextColumn() and getPreviousColumn(), `getLast() on table column.
• getActiveWorksheet() on the workbook.
• getRange(address: string) off of workbook.
• getBoundingRange(ranges: []) Gets the smallest range object that encompasses the provided ranges. For example, the bounding range between "B2:C5" and "D10:E15" is "B2:E15".
• getCount() on various collections such as named item, worksheet, table, etc. to get number of items in a collection. workbook.worksheets.getCount()
• getFirst() and getLast() and get last on various collection such as tworksheet, able column, chart points, range view collection.
• getNext() and getPrevious() on worksheet, table column collection.
• getRangeR1C1() Gets the range object beginning at a particular row index and column index, and spanning a certain number of rows and columns.

For API details, please refer to the Excel API open specification.

What's new in Excel JavaScript API 1.4

The following are the new additions to the Excel JavaScript APIs in requirement set 1.3.

Named item add and new properties

New properties:

• comment
• scope worksheet or workbook scoped items
• worksheet returns the worksheet on which the named item is scoped to.

New methods:

• add(name: string, reference: Range or string, comment: string)Adds a new name to the collection of the given scope.
• addFormulaLocal(name: string, formula: string, comment: string) Adds a new name to the collection of the given scope using the user's locale for the formula.

Settings API in in Excel namespace

Setting object represents a key-value pair of a setting persisted to the document. Now, we've added settings related APIs under Excel namespace. This doesn't offer net new functionality - however this make easy to remain in the promise based batched API syntax reduce the dependency on common API for Excel related tasks.

APIs include getItem() to get setting entry via the key, add() to add the specified key:value setting pair to the workbook.

Others

• Set table column name (prior version only allows reading).
• Add table column to the end of the table (prior version only allows anywhere but last).
• Add multiple rows to a table at a time (prior version only allows 1 row at a time).
• range.getColumnsAfter(count: number) and range.getColumnsBefore(count: number) to get a certain number of columns to the right/left of the current Range object.
• Get item or null object function: This functionality allows getting object using a key. If the object does not exist, the returned object's isNullObject property will be true. This alows developers to check if an object exists or not without having to handle it thorugh exception handling. Available on worksheet, named-item, binding, chart series, etc.

worksheet.GetItemOrNullObject()

What's new in Excel JavaScript API 1.3

The following are the new additions to the Excel JavaScript APIs in requirement set 1.3.

What's new in Excel JavaScript API 1.2

The following are the new additions to the Excel JavaScript APIs in requirement set 1.2.

Excel JavaScript API 1.1

Excel JavaScript API 1.1 is the first version of the API. For details about the API, see the Excel JavaScript API reference topics.

Additional resources

• Specify Office hosts and API requirements
• Office Add-ins XML manifest