Excel JavaScript preview APIs
New Excel 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:
- You must use the preview version of the Office JavaScript API library from the Office.js content delivery network (CDN). The type definition file for TypeScript compilation and IntelliSense is found at the CDN and DefinitelyTyped. You can install these types with
npm install --save-dev @types/office-js-preview(be sure to remove the types for@types/office-jsif you've previously installed them). - You may need to join the Microsoft 365 Insider program for access to more recent Office builds.
The following table provides a concise summary of the APIs, while the subsequent API list table gives a detailed list.
| Feature area | Description | Relevant objects |
|---|---|---|
| Document tasks | Turn comments into tasks assigned to users. | DocumentTask, DocumentTaskChange, DocumentTaskChangeCollection, DocumentTaskCollection |
| Linked data types | Adds support for data types connected to Excel from external sources. | LinkedDataType, LinkedDataTypeAddedEventArgs, LinkedDataTypeCollection |
| Table styles | Provides control for font, border, fill color, and other aspects of table styles. | Table, PivotTable, Slicer |
API list
The following table lists the Excel JavaScript APIs currently in preview. For a complete list of all Excel JavaScript APIs (including preview APIs and previously released APIs), see all Excel JavaScript APIs.
| Class | Fields | Description |
|---|---|---|
| Application | formatStaleValues | Specifies whether the Format Stale Values option within Calculation Options is enabled or disabled. |
| Base64EncodedImage | data | The Base64-encoded string. |
| type | The file type of the Base64-encoded image. | |
| BlockedErrorCellValue | errorSubType | Represents the type of BlockedErrorCellValue. |
| BusyErrorCellValue | errorSubType | Represents the type of BusyErrorCellValue. |
| CalcErrorCellValue | errorSubType | Represents the type of CalcErrorCellValue. |
| Chart | getDataRange() | Gets the data source of the whole chart. |
| getDataRangeOrNullObject() | Gets the data source of the whole chart. | |
| CheckboxCellControl | type | Represents an interactable control inside of a cell. |
| Comment | assignTask(assignee: Excel.EmailIdentity) | Assigns the task attached to the comment to the given user as an assignee. |
| getTask() | Gets the task associated with this comment. | |
| getTaskOrNullObject() | Gets the task associated with this comment. | |
| CommentReply | assignTask(assignee: Excel.EmailIdentity) | Assigns the task attached to the comment to the given user as the sole assignee. |
| getTask() | Gets the task associated with this comment reply's thread. | |
| getTaskOrNullObject() | Gets the task associated with this comment reply's thread. | |
| ConnectErrorCellValue | errorSubType | Represents the type of ConnectErrorCellValue. |
| DatetimeFormatInfo | shortDateTimePattern | Gets the format string for a short date and time value. |
| DocumentTask | assign(assignee: Excel.EmailIdentity) | Adds the given user to the list of assignees attached to the task. |
| assignees | Returns a collection of assignees of the task. | |
| changes | Gets the change records of the task. | |
| comment | Gets the comment associated with the task. | |
| completedBy | Gets the most recent user to have completed the task. | |
| completedDateTime | Gets the date and time that the task was completed. | |
| createdBy | Gets the user who created the task. | |
| createdDateTime | Gets the date and time that the task was created. | |
| id | Gets the ID of the task. | |
| percentComplete | Specifies the completion percentage of the task. | |
| priority | Specifies the priority of the task. | |
| startAndDueDateTime | Gets or sets the date and time the task should start and is due. | |
| title | Specifies title of the task. | |
| unassign(assignee: Excel.EmailIdentity) | Removes the given user from the list of assignees attached to the task. | |
| unassignAll() | Removes all users from the list of assignees attached to the task. | |
| DocumentTaskChange | assignee | Represents the user assigned to the task for an assign change action, or the user unassigned from the task for an unassign change action. |
| changedBy | Represents the identity of the user who made the task change. | |
| commentId | Represents the ID of the comment or comment reply to which the task change is anchored. | |
| createdDateTime | Represents the creation date and time of the task change record. | |
| dueDateTime | Represents the task's due date and time. | |
| id | The unique GUID of the task change. | |
| percentComplete | Represents the task's completion percentage. | |
| priority | Represents the task's priority. | |
| startDateTime | Represents the task's start date and time. | |
| title | Represents the task's title. | |
| type | Represents the action type of the task change record. | |
| undoChangeId | Represents the DocumentTaskChange.id property that was undone for the undo change action. |
|
| DocumentTaskChangeCollection | getCount() | Gets the number of change records in the collection for the task. |
| getItemAt(index: number) | Gets a task change record by using its index in the collection. | |
| items | Gets the loaded child items in this collection. | |
| DocumentTaskCollection | getCount() | Gets the number of tasks in the collection. |
| getItem(key: string) | Gets a task using its ID. | |
| getItemAt(index: number) | Gets a task by its index in the collection. | |
| getItemOrNullObject(key: string) | Gets a task using its ID. | |
| items | Gets the loaded child items in this collection. | |
| DocumentTaskSchedule | dueDateTime | Gets the date and time that the task is due. |
| startDateTime | Gets the date and time that the task should start. | |
| EmailIdentity | displayName | Represents the user's display name. |
| Represents the user's email. | ||
| id | Represents the user's unique ID. | |
| EmptyCellControl | type | |
| EntityArrayCardLayout | arrayProperty | Represents name of the property that contains the array shown in the card. |
| columnsToReport | Represents the count of columns which the card claims are in the array. | |
| displayName | Represents name of the property that contains the array shown in the card. | |
| firstRowIsHeader | Represents whether the first row of the array is treated as a header. | |
| layout | Represents the type of this layout. | |
| rowsToReport | Represents the count of rows which the card claims are in the array. | |
| EntityCardLayout | layout | Represents the type of this layout. |
| ExternalCodeServiceObjectCellValue | Python_str | Represents the output of str() function when used on this object. |
| Python_type | Represents the full type name of this object. | |
| Python_typeName | Represents the short type name of this object. | |
| basicType | Represents the value that would be returned by Range.valueTypes for a cell with this value. |
|
| basicValue | Represents the value that would be returned by Range.values for a cell with this value. |
|
| language | Represents the runtime language of this external code service. | |
| preview | Represents the preview value shown in the cell. | |
| provider | Represents information about the service that provided the data in this ExternalCodeServiceObjectCellValue. |
|
| type | Represents the type of this cell value. | |
| Identity | displayName | Represents the user's display name. |
| id | Represents the user's unique ID. | |
| LinkedDataType | dataProvider | The name of the data provider for the linked data type. |
| lastRefreshed | The local time-zone date and time since the workbook was opened when the linked data type was last refreshed. | |
| name | The name of the linked data type. | |
| periodicRefreshInterval | The frequency, in seconds, at which the linked data type is refreshed if refreshMode is set to "Periodic". |
|
| refreshMode | The mechanism by which the data for the linked data type is retrieved. | |
| requestRefresh() | Makes a request to refresh the linked data type. | |
| requestSetRefreshMode(refreshMode: Excel.LinkedDataTypeRefreshMode) | Makes a request to change the refresh mode for this linked data type. | |
| serviceId | The unique ID of the linked data type. | |
| supportedRefreshModes | Returns an array with all the refresh modes supported by the linked data type. | |
| LinkedDataTypeAddedEventArgs | serviceId | The unique ID of the new linked data type. |
| source | Gets the source of the event. | |
| type | Gets the type of the event. | |
| LinkedDataTypeCollection | getCount() | Gets the number of linked data types in the collection. |
| getItem(key: number) | Gets a linked data type by service ID. | |
| getItemAt(index: number) | Gets a linked data type by its index in the collection. | |
| getItemOrNullObject(key: number) | Gets a linked data type by ID. | |
| items | Gets the loaded child items in this collection. | |
| requestRefreshAll() | Makes a request to refresh all the linked data types in the collection. | |
| LocalImage | getBase64EncodedImageData(cacheUid: string) | Gets the Base64-encoded image data stored in the shared image cache with the cache unique identifier (UID). |
| LocalImageCellValue | altText | Represents the alternate text used in accessibility scenarios to describe what the image represents. |
| attribution | Represents attribution information to describe the source and license requirements for this image. | |
| basicType | Represents the value that would be returned by Range.valueTypes for a cell with this value. |
|
| basicValue | Represents the value that would be returned by Range.values for a cell with this value. |
|
| image | Represents the image itself, either cached or encoded. | |
| provider | Represents information that describes the entity or individual who provided the image. | |
| type | Represents the type of this cell value. | |
| LocalImageCellValueCacheId | cachedUid | Represents the image's UID as it appears in the cache. |
| MixedCellControl | type | |
| NameErrorCellValue | errorSubType | Represents the type of NameErrorCellValue. |
| NamedSheetViewCollection | getItemOrNullObject(key: string) | Gets a sheet view using its name. |
| NotAvailableErrorCellValue | errorSubType | Represents the type of NotAvailableErrorCellValue. |
| PivotLayout | getCell(dataHierarchy: DataPivotHierarchy | string, rowItems: Array<PivotItem | string>, columnItems: Array<PivotItem | string>) | Gets a unique cell in the PivotTable based on a data hierarchy and the row and column items of their respective hierarchies. |
| pivotStyle | The style applied to the PivotTable. | |
| setStyle(style: string | PivotTableStyle | BuiltInPivotTableStyle) | Sets the style applied to the PivotTable. | |
| PythonErrorCellValue | basicType | Represents the value that would be returned by Range.valueTypes for a cell with this value. |
| basicValue | Represents the value that would be returned by Range.values for a cell with this value. |
|
| errorType | Represents the type of ErrorCellValue. |
|
| type | Represents the type of this cell value. | |
| Query | delete() | Deletes the query and associated connection. |
| refresh() | Refreshes the query. | |
| QueryCollection | refreshAll() | Refresh all queries. |
| Range | clearOrResetContents() | Clears the values of the cells in the range, with special consideration given to cells containing controls. |
| control | Accesses the cell control applied to this range. | |
| RangeAreas | clearOrResetContents() | Clears the values of the cells in the ranges, with special consideration given to cells containing controls. |
| RangeTextRun | font | |
| text | ||
| RefErrorCellValue | errorSubType | Represents the type of RefErrorCellValue. |
| RefreshModeChangedEventArgs | refreshMode | The linked data type refresh mode. |
| serviceId | The unique ID of the object whose refresh mode was changed. | |
| source | Gets the source of the event. | |
| type | Gets the type of the event. | |
| RefreshRequestCompletedEventArgs | refreshed | Indicates if the request to refresh was successful. |
| serviceId | The unique ID of the object whose refresh request was completed. | |
| source | Gets the source of the event. | |
| type | Gets the type of the event. | |
| warnings | An array that contains any warnings generated from the refresh request. | |
| SettableCellProperties | textRuns | Represents the textRuns property. |
| ShapeCollection | addLocalImageReference(address: string) | Creates a reference for the local image stored in the cell address and displays it as a floating shape over cells. |
| addSvg(xml: string) | Creates a scalable vector graphic (SVG) from an XML string and adds it to the worksheet. | |
| Slicer | nameInFormula | Represents the slicer name used in the formula. |
| setStyle(style: string | SlicerStyle | BuiltInSlicerStyle) | Sets the style applied to the slicer. | |
| slicerStyle | The style applied to the slicer. | |
| Table | clearStyle() | Changes the table to use the default table style. |
| onFiltered | Occurs when a filter is applied on a specific table. | |
| setStyle(style: string | TableStyle | BuiltInTableStyle) | Sets the style applied to the table. | |
| tableStyle | The style applied to the table. | |
| TableCollection | onFiltered | Occurs when a filter is applied on any table in a workbook, or a worksheet. |
| TableFilteredEventArgs | tableId | Gets the ID of the table in which the filter is applied. |
| type | Gets the type of the event. | |
| worksheetId | Gets the ID of the worksheet which contains the table. | |
| TimeoutErrorCellValue | basicType | Represents the value that would be returned by Range.valueTypes for a cell with this value. |
| basicValue | Represents the value that would be returned by Range.values for a cell with this value. |
|
| errorSubType | Represents the type of TimeoutErrorCellValue. |
|
| errorType | Represents the type of ErrorCellValue. |
|
| type | Represents the type of this cell value. | |
| UnknownCellControl | type | |
| ValueErrorCellValue | errorSubType | Represents the type of ValueErrorCellValue. |
| Workbook | externalCodeServiceTimeout | Specifies the maximum length of time, in seconds, allotted for a formula that depends on an external code service to complete. |
| linkedDataTypes | Returns a collection of linked data types that are part of the workbook. | |
| localImage | Returns the LocalImage object associated with the workbook. |
|
| showPivotFieldList | Specifies whether the PivotTable's field list pane is shown at the workbook level. | |
| tasks | Returns a collection of tasks that are present in the workbook. | |
| use1904DateSystem | True if the workbook uses the 1904 date system. | |
| Worksheet | onFiltered | Occurs when a filter is applied on a specific worksheet. |
| tasks | Returns a collection of tasks that are present in the worksheet. | |
| WorksheetCollection | addFromBase64(base64File: string, sheetNamesToInsert?: string[], positionType?: Excel.WorksheetPositionType, relativeTo?: Worksheet | string) | Inserts the specified worksheets of a workbook into the current workbook. |
| onFiltered | Occurs when any worksheet's filter is applied in the workbook. | |
| WorksheetFilteredEventArgs | type | Gets the type of the event. |
| worksheetId | Gets the ID of the worksheet in which the filter is applied. |
See also
Collaborate with us on GitHub
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Office Add-ins