Edit

Share via

Excel JavaScript preview APIs

  • Article

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:

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.
BasicCardLayout layout Represents the type of this layout.
BasicCompactLayout icon Specifies the name of the icon which is used to open the card.
BasicViewLayouts card Represents the layout of this value and its properties in card view.
compact Represents the layout used when there is limited space to represent the value.
BlockedErrorCellValue errorSubType Represents the type of BlockedErrorCellValue.
BooleanCellValue layouts Represents layout information for views of this boolean value.
properties Represents additional properties of this boolean value.
provider Represents information that describes the service that provided the data in this BooleanCellValue.
referencedValues Represents the cell values which are referenced within BooleanCellValue.properties.
type Represents the type of this cell value.
BusyErrorCellValue errorSubType Represents the type of BusyErrorCellValue.
CalcErrorCellValue errorSubType Represents the type of CalcErrorCellValue.
CardLayoutTwoColumnSection layout Represents the type of layout for this section.
Chart getDataRange() Gets the data source of the whole chart.
getDataRangeOrNullObject() Gets the data source of the whole chart.
ChartDataLabel geometricShapeType Gets or sets the geometric shape type of the data label.
getSubstring(start: number, length?: number) Returns a substring of the data label.
getTailAnchor() Returns the tail anchor of the data label which is shown as a sticky callout.
setHeight(height: number) Sets the height of the data label in points.
setWidth(width: number) Sets the width of the data label in points.
showAsStickyCallout Gets a value that indicates whether the data label is shown as a callout with the tail anchor attached to the data point.
ChartDataLabelAnchor left Represents the distance, in points, from the anchor to the left edge of the chart data label.
top Represents the distance, in points, from the anchor to the top edge of the chart data label.
ChartDataLabels geometricShapeType Gets or sets the geometric shape type of the data labels.
leaderLines Gets an object that represents the leader lines of the data labels.
showAsStickyCallout Gets a value that indicates whether the data labels are shown as a callout with the tail anchor attached to the data point.
showLeaderLines Gets or sets a value that indicates whether leader lines are displayed for the data labels.
ChartLeaderLines format Represents the formatting of leader lines of data labels in a series.
ChartLeaderLinesFormat line Gets an object that represents the line formatting of chart leader lines.
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.
DoubleCellValue layouts Represents layout information for views of this double value.
numberFormat Returns the number format string that is used to display this value.
properties Represents additional properties of this double value.
provider Represents information that describes the service that provided the data in this DoubleCellValue.
referencedValues Represents the cell values which are referenced within DoubleCellValue.properties.
type Represents the type of this cell value.
EmailIdentity displayName Represents the user's display name.
email 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.
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.
JavaScriptCustomFunctionReferenceCellValue 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.
functionType Represents the type of FunctionCellValue.
id Represents the ID of the custom function.
namespace Represents the namespace used by the custom function.
type Represents the type of this cell value.
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.
LinkedEntityDataDomain dataProvider Gets the name of the data provider for the linked entity data domain.
delete() Deletes this object from the LinkedEntityDataDomainCollection.
id Gets the ID of the linked entity data domain defined by Office Add-ins.
lastRefreshed Gets the date and time (in the local time zone) since the workbook was opened and the LinkedEntityCellValue objects of this linked entity data domain were last refreshed.
loadFunctionId Gets the ID of the custom function that is called on demand to resolve or refresh the LinkedEntityCellValue objects of the linked entity data domain defined by Office Add-ins.
name Gets the name of the linked entity data domain.
periodicRefreshInterval Gets the frequency, in seconds, at which LinkedEntityCellValue objects of this linked entity data domain are refreshed automatically.
refresh() Refreshes all LinkedEntityCellValue objects of this linked entity data domain.
refreshMode Gets or sets the refresh mode that defines how and when the LinkedEntityCellValue objects of this linked entity data domain are refreshed.
serviceId Gets the service ID of the linked entity data domain.
supportedRefreshModes Gets all the refresh modes supported by the linked entity data domain.
LinkedEntityDataDomainAddedEventArgs id Gets the ID of the linked entity data domain that was just added to the workbook.
serviceId Gets the service ID of the linked entity data domain that was just added to the workbook.
source Gets the source of the event.
type Gets the type of the event.
LinkedEntityDataDomainCollection add(options: Excel.LinkedEntityDataDomainCreateOptions) Adds a linked entity data domain object defined by the Office Add-in to the collection.
getCount() Gets the number of linked entity data domains in the collection.
getItem(id: string) Gets a linked entity data domain by its id.
getItemAt(index: number) Gets a linked entity data domain by its index in the collection.
getItemByName(name: string) Gets a linked entity data domain by its name.
getItemByNameOrNullObject(name: string) Gets a linked entity data domain by its name.
getItemOrNullObject(id: string) Gets a linked entity data domain by its id.
items Gets the loaded child items in this collection.
onLinkedEntityDataDomainAdded Occurs when a new linked entity data domain is added to the workbook.
onRefreshCompleted Occurs when the request to refresh LinkedEntityCellValue objects of a linked entity data domain is completed.
onRefreshModeChanged Occurs when the refreshMode of a linked entity data domain is changed.
refreshAll() Refreshes all LinkedEntityCellValue objects of all linked entity data domains in this collection.
LinkedEntityDataDomainCreateOptions dataProvider Gets or sets the name of the data provider for the linked entity data domain.
id Gets or sets the ID of the linked entity data domain.
loadFunctionId Gets or sets the ID of the custom function that will be called on demand to resolve or refresh the LinkedEntityCellValue objects of this linked entity data domain.
name Gets or sets the name of the linked entity data domain.
periodicRefreshInterval Gets or sets the frequency, in seconds, at which LinkedEntityCellValue objects of this linked entity data domain are refreshed automatically.
supportedRefreshModes Gets or sets all the refresh modes supported by the linked entity data domain.
LinkedEntityDataDomainRefreshCompletedEventArgs errors Gets any errors encountered during the request to refresh LinkedEntityCellValue objects of the linked entity data domain.
id Gets the ID of the linked entity data domain whose LinkedEntityCellValue objects were refreshed.
refreshed Returns true if the LinkedEntityCellValue objects of the linked entity data domain were refreshed successfully, otherwise returns false.
serviceId Gets the service ID of the linked entity data domain whose LinkedEntityCellValue objects were refreshed.
source Gets the source of the event.
type Gets the type of the event.
LinkedEntityDataDomainRefreshModeChangedEventArgs id Gets the ID of the linked entity data domain whose refresh mode was changed.
refreshMode Gets the new refresh mode of the linked entity data domain.
serviceId Gets the service ID of the linked entity data domain whose refresh mode was changed.
source Gets the source of the event.
type Gets the type of the event.
LinkedEntityIdCulture culture Represents the language culture used to create the LinkedEntityCellValue object.
entityId Represents the identifier specific to a service used to create the LinkedEntityCellValue object.
LinkedEntityLoadServiceRequest domainId Represents the domain specific to the service used to create the LinkedEntityCellValue objects.
entities Represents the entity IDs and cultures of the LinkedEntityCellValue objects to load.
LinkedEntityLoadServiceResult entities Represents the loaded LinkedEntityCellValue objects.
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.
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 getDisplayedCellProperties(cellPropertiesLoadOptions: CellPropertiesLoadOptions) Returns a 2D array, encapsulating the display data for each cell's font, fill, borders, alignment, and other properties.
RangeAreas
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.
StringCellValue layouts Represents layout information for views of this string value.
properties Represents additional properties of this string value.
provider Represents information that describes the service that provided the data in this StringCellValue.
referencedValues Represents the cell values which are referenced within StringCellValue.properties.
type Represents the type of this cell value.
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.
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.
getActiveShape() Gets the active shape in the workbook.
getActiveShapeOrNullObject() Gets the active shape in the workbook.
linkedDataTypes Returns a collection of linked data types that are part of the workbook.
linkedEntityDataDomains Returns a collection of linked entity data domains that are available in 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.
showDataTypeIcons Specifies if data type icons are visible on the 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