Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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 |
| 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. | |
| Chart | getDataRange() | Gets the data source of the whole chart. |
| getDataRangeOrNullObject() | Gets the data source of the whole chart. | |
| 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. | |
| 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 | Specifies 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. | |
| 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. | |
| ExternalCodeServiceObjectCellValue | Python_str | Represents the output of the 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. | |
| 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. |
| 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. | |
| PivotTable | autoRefresh | Specifies whether the PivotTable auto refreshes when the source data changes. |
| 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 | togglePythonMarshalMode(marshalMode?: Excel.PythonMarshalMode) | Sets the marshaling mode of the Python in Excel formula =PY. |
| RequestContext | setInvocation(invocation: { invocationId: number isInCFSyncScenario: boolean }) | |
| 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. | |
| ShapeFont | strikethrough | Specifies the strikethrough status of font. |
| subscript | Specifies the subscript status of font. | |
| superscript | Specifies the superscript status of font. | |
| tintAndShade | Specifies a double that lightens or darkens a color for the range font. | |
| Slicer | nameInFormula | Specifies 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 | altTextDescription | Specifies the alternative text for accessibility. |
| altTextTitle | Specifies a summary for the table, such as one used by screen readers. | |
| clearStyle() | Changes the table to use the default table style. | |
| comment | Specifies a comment associated with the table. | |
| isActive | Retrieves whether the table is currently active. | |
| onFiltered | Occurs when a filter is applied on a specific table. | |
| setStyle(style: string | TableStyle | BuiltInTableStyle) | Sets the style applied to the table. | |
| source | Retrieves the data source type from which the table originates. | |
| 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. | |
| Window | rangeSelection | Gets the range selection in the window. |
| Workbook | externalCodeServiceTimeout | Specifies the maximum length of time, in seconds, allotted for a formula that depends on an external code service to complete. |
| 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