Excel JavaScript API online-only requirement set
The ExcelApiOnline requirement set is a special requirement set that includes features that are only available for Excel on the web. APIs in this requirement set are considered to be production APIs (not subject to undocumented behavioral or structural changes) for the Excel on the web application. ExcelApiOnline APIs are considered to be "preview" APIs for other platforms (Windows, Mac, iOS) and may not be supported by any of those platforms.
When APIs in the ExcelApiOnline requirement set are supported across all platforms, they will be added to the next released requirement set (ExcelApi 1.[NEXT]). Once that new requirement set is public, those APIs will be removed from ExcelApiOnline. Think of this as a similar promotion process to an API moving from preview to release.
Important
ExcelApiOnline is a superset of the latest numbered requirement set.
Important
ExcelApiOnline 1.1 is the only version of the online-only APIs. This is because Excel on the web will always have a single version available to users that is the latest version.
The following table provides a concise summary of the APIs, while the subsequent API list table gives a detailed list of the current ExcelApiOnline APIs.
| Feature area | Description | Relevant objects |
|---|---|---|
| Linked workbooks | Manage links between workbooks, including support for refreshing and breaking workbook links. | LinkedWorkbook, LinkedWorkbookCollection |
| Named sheet views | Gives programmatic control of per-user worksheet views. | NamedSheetView, NamedSheetViewCollection |
| Worksheet move events | Detect when worksheets are moved within a collection, the position of the worksheet, and the source of the change. | WorksheetCollection, WorksheetMovedEventArgs |
| Worksheet protection | Prevent unauthorized users from making changes to specified ranges within a worksheet. | WorksheetProtection, AllowEditRange, AllowEditRangeCollection, AllowEditRangeOptions |
Recommended usage
Because ExcelApiOnline APIs are only supported by Excel on the web, your add-in should check if the requirement set is supported before calling these APIs. This avoids calling an online-only API on a different platform.
if (Office.context.requirements.isSetSupported("ExcelApiOnline", "1.1")) {
// Any API exclusive to the ExcelApiOnline requirement set.
}
Once the API is in a cross-platform requirement set, you should remove or edit the isSetSupported check. This will enable your add-in's feature on other platforms. Be sure to test the feature on those platforms when making this change.
Important
Your manifest cannot specify ExcelApiOnline 1.1 as an activation requirement. It is not a valid value to use in the Set element.
API list
The following table lists the Excel JavaScript APIs currently included in the ExcelApiOnline requirement set. For a complete list of all Excel JavaScript APIs (including ExcelApiOnline APIs and previously released APIs), see all Excel JavaScript APIs.
| Class | Fields | Description |
|---|---|---|
| AllowEditRange | address | Specifies the range associated with the object. |
| delete() | Deletes the object from the AllowEditRangeCollection. |
|
| isPasswordProtected | Specifies if the object is password protected. | |
| pauseProtection(password?: string) | Pauses worksheet protection for the object for the user in the current session. | |
| setPassword(password?: string) | Changes the password associated with the object. | |
| title | Specifies the title of the object. | |
| AllowEditRangeCollection | add(title: string, rangeAddress: string, options?: Excel.AllowEditRangeOptions) | Adds an AllowEditRange object to the worksheet. |
| getCount() | Returns the number of AllowEditRange objects in the collection. |
|
| getItem(key: string) | Gets the AllowEditRange object by its title. |
|
| getItemAt(index: number) | Returns an AllowEditRange object by its index in the collection. |
|
| getItemOrNullObject(key: string) | Gets the AllowEditRange object by its title. |
|
| items | Gets the loaded child items in this collection. | |
| pauseProtection(password: string) | Pauses worksheet protection for all AllowEditRange objects found in this worksheet that have the given password for the user in the current session. |
|
| AllowEditRangeOptions | password | The password associated with the AllowEditRange. |
| LinkedWorkbook | breakLinks() | Makes a request to break the links pointing to the linked workbook. |
| id | The original URL pointing to the linked workbook. | |
| refresh() | Makes a request to refresh the data retrieved from the linked workbook. | |
| LinkedWorkbookCollection | breakAllLinks() | Breaks all the links to the linked workbooks. |
| getItem(key: string) | Gets information about a linked workbook by its URL. | |
| getItemOrNullObject(key: string) | Gets information about a linked workbook by its URL. | |
| items | Gets the loaded child items in this collection. | |
| refreshAll() | Makes a request to refresh all the workbook links. | |
| workbookLinksRefreshMode | Represents the update mode of the workbook links. | |
| NamedSheetView | activate() | Activates this sheet view. |
| delete() | Removes the sheet view from the worksheet. | |
| duplicate(name?: string) | Creates a copy of this sheet view. | |
| name | Gets or sets the name of the sheet view. | |
| NamedSheetViewCollection | add(name: string) | Creates a new sheet view with the given name. |
| enterTemporary() | Creates and activates a new temporary sheet view. | |
| exit() | Exits the currently active sheet view. | |
| getActive() | Gets the worksheet's currently active sheet view. | |
| getCount() | Gets the number of sheet views in this worksheet. | |
| getItem(key: string) | Gets a sheet view using its name. | |
| getItemAt(index: number) | Gets a sheet view by its index in the collection. | |
| items | Gets the loaded child items in this collection. | |
| TableRowCollection | deleteRows(rows: number[] | TableRow[]) | Delete multiple rows from a table. |
| deleteRowsAt(index: number, count?: number) | Delete a specified number of rows from a table, starting at a given index. | |
| Workbook | linkedWorkbooks | Returns a collection of linked workbooks. |
| Worksheet | namedSheetViews | Returns a collection of sheet views that are present in the worksheet. |
| WorksheetProtection | allowEditRanges | Specifies the AllowEditRangeCollection object found in this worksheet. |
| canPauseProtection | Specifies if protection can be paused for this worksheet. | |
| checkPassword(password?: string) | Specifies if the password can be used to unlock worksheet protection. | |
| isPasswordProtected | Specifies if the sheet is password protected. | |
| isPaused | Specifies if worksheet protection is paused. | |
| pauseProtection(password?: string) | Pauses worksheet protection for the given worksheet object for the user in the current session. | |
| resumeProtection() | Resumes worksheet protection for the given worksheet object for the user in a given session. | |
| savedOptions | Specifies the protection options saved in the worksheet. | |
| setPassword(password?: string) | Changes the password associated with the WorksheetProtection object. |
|
| updateOptions(options: Excel.WorksheetProtectionOptions) | Change the worksheet protection options associated with the WorksheetProtection object. |
|
| WorksheetProtectionChangedEventArgs | allowEditRangesChanged | Specifies if any of the AllowEditRange objects have changed. |
| protectionOptionsChanged | Specifies if the WorksheetProtectionOptions have changed. |
|
| sheetPasswordChanged | Specifies if the worksheet password has changed. |
See also
Office Add-ins