What's new in Excel JavaScript API 1.12
The ExcelApi 1.12 increased support for formulas in ranges by adding APIs for tracking dynamic arrays and finding a formula's direct precedents. It also added API control of PivotTable filters. Improvements were also made in the comment, culture settings, and custom properties feature areas.
| Feature area | Description | Relevant objects |
|---|---|---|
| Comment events | Adds events for add, change, and delete to the comment collection. | CommentCollection |
| Date and time culture settings | Gives access to additional cultural settings around date and time formatting. | CultureInfo, NumberFormatInfo Application |
| Direct precedents | Returns ranges that are used to evaluate a cell's formula. | Range |
| Pivot Filters | Applies value-driven filters to the fields of a PivotTable. | PivotField, PivotFilters |
| Range spilling | Lets add-ins find ranges associated with dynamic array results. | Range |
| Worksheet-level custom properties | Lets custom properties be scoped to the worksheet-level, in addition to being scoped to the workbook-level. | WorksheetCustomProperty, WorksheetCustomPropertyCollection |
API list
The following table lists the APIs in Excel JavaScript API requirement set 1.12. To view API reference documentation for all APIs supported by Excel JavaScript API requirement set 1.12 or earlier, see Excel APIs in requirement set 1.12 or earlier.
| Class | Fields | Description |
|---|---|---|
| ChartAxisTitle | textOrientation | Specifies the angle to which the text is oriented for the chart axis title. |
| ChartSeries | getDimensionValues(dimension: Excel.ChartSeriesDimension) | Gets the values from a single dimension of the chart series. |
| Comment | contentType | Gets the content type of the comment. |
| CommentAddedEventArgs | commentDetails | Gets the CommentDetail array that contains the comment ID and IDs of its related replies. |
| source | Specifies the source of the event. | |
| type | Gets the type of the event. | |
| worksheetId | Gets the ID of the worksheet in which the event happened. | |
| CommentChangedEventArgs | changeType | Gets the change type that represents how the changed event is triggered. |
| commentDetails | Get the CommentDetail array which contains the comment ID and IDs of its related replies. |
|
| source | Specifies the source of the event. | |
| type | Gets the type of the event. | |
| worksheetId | Gets the ID of the worksheet in which the event happened. | |
| CommentCollection | onAdded | Occurs when the comments are added. |
| onChanged | Occurs when comments or replies in a comment collection are changed, including when replies are deleted. | |
| onDeleted | Occurs when comments are deleted in the comment collection. | |
| CommentDeletedEventArgs | commentDetails | Gets the CommentDetail array that contains the comment ID and IDs of its related replies. |
| source | Specifies the source of the event. | |
| type | Gets the type of the event. | |
| worksheetId | Gets the ID of the worksheet in which the event happened. | |
| CommentDetail | commentId | Represents the ID of the comment. |
| replyIds | Represents the IDs of the related replies that belong to the comment. | |
| CommentReply | contentType | The content type of the reply. |
| CultureInfo | datetimeFormat | Defines the culturally appropriate format of displaying date and time. |
| DatetimeFormatInfo | dateSeparator | Gets the string used as the date separator. |
| longDatePattern | Gets the format string for a long date value. | |
| longTimePattern | Gets the format string for a long time value. | |
| shortDatePattern | Gets the format string for a short date value. | |
| timeSeparator | Gets the string used as the time separator. | |
| PivotDateFilter | comparator | The comparator is the static value to which other values are compared. |
| condition | Specifies the condition for the filter, which defines the necessary filtering criteria. | |
| exclusive | If true, filter excludes items that meet criteria. |
|
| lowerBound | The lower-bound of the range for the between filter condition. |
|
| upperBound | The upper-bound of the range for the between filter condition. |
|
| wholeDays | For equals, before, after, and between filter conditions, indicates if comparisons should be made as whole days. |
|
| PivotField | applyFilter(filter: Excel.PivotFilters) | Sets one or more of the field's current PivotFilters and applies them to the field. |
| clearAllFilters() | Clears all criteria from all of the field's filters. | |
| clearFilter(filterType: Excel.PivotFilterType) | Clears all existing criteria from the field's filter of the given type (if one is currently applied). | |
| getFilters() | Gets all filters currently applied on the field. | |
| isFiltered(filterType?: Excel.PivotFilterType) | Checks if there are any applied filters on the field. | |
| PivotFilters | dateFilter | The PivotField's currently applied date filter. |
| labelFilter | The PivotField's currently applied label filter. | |
| manualFilter | The PivotField's currently applied manual filter. | |
| valueFilter | The PivotField's currently applied value filter. | |
| PivotLabelFilter | comparator | The comparator is the static value to which other values are compared. |
| condition | Specifies the condition for the filter, which defines the necessary filtering criteria. | |
| exclusive | If true, filter excludes items that meet criteria. |
|
| lowerBound | The lower-bound of the range for the between filter condition. |
|
| substring | The substring used for the beginsWith, endsWith, and contains filter conditions. |
|
| upperBound | The upper-bound of the range for the between filter condition. |
|
| PivotManualFilter | selectedItems | A list of selected items to manually filter. |
| PivotTable | allowMultipleFiltersPerField | Specifies if the PivotTable allows the application of multiple PivotFilters on a given PivotField in the table. |
| PivotTableScopedCollection | getCount() | Gets the number of PivotTables in the collection. |
| getFirst() | Gets the first PivotTable in the collection. | |
| getItem(key: string) | Gets a PivotTable by name. | |
| getItemOrNullObject(name: string) | Gets a PivotTable by name. | |
| items | Gets the loaded child items in this collection. | |
| PivotValueFilter | comparator | The comparator is the static value to which other values are compared. |
| condition | Specifies the condition for the filter, which defines the necessary filtering criteria. | |
| exclusive | If true, filter excludes items that meet criteria. |
|
| lowerBound | The lower-bound of the range for the between filter condition. |
|
| selectionType | Specifies if the filter is for the top/bottom N items, top/bottom N percent, or top/bottom N sum. | |
| threshold | The "N" threshold number of items, percent, or sum to be filtered for a top/bottom filter condition. | |
| upperBound | The upper-bound of the range for the between filter condition. |
|
| value | Name of the chosen "value" in the field by which to filter. | |
| Range | getDirectPrecedents() | Returns a WorkbookRangeAreas object that represents the range containing all the direct precedent cells of a specified range in the same worksheet or across multiple worksheets. |
| getPivotTables(fullyContained?: boolean) | Gets a scoped collection of PivotTables that overlap with the range. | |
| getSpillParent() | Gets the range object containing the anchor cell for a cell getting spilled into. | |
| getSpillParentOrNullObject() | Gets the range object containing the anchor cell for the cell getting spilled into. | |
| getSpillingToRange() | Gets the range object containing the spill range when called on an anchor cell. | |
| getSpillingToRangeOrNullObject() | Gets the range object containing the spill range when called on an anchor cell. | |
| hasSpill | Represents if all cells have a spill border. | |
| numberFormatCategories | Represents the category of number format of each cell. | |
| savedAsArray | Represents if all the cells would be saved as an array formula. | |
| RangeAreasCollection | getCount() | Gets the number of RangeAreas objects in this collection. |
| getItemAt(index: number) | Returns the RangeAreas object based on position in the collection. |
|
| items | Gets the loaded child items in this collection. | |
| WorkbookRangeAreas | addresses | Returns an array of addresses in A1-style. |
| areas | Returns the RangeAreasCollection object. |
|
| getRangeAreasBySheet(key: string) | Returns the RangeAreas object based on worksheet ID or name in the collection. |
|
| getRangeAreasOrNullObjectBySheet(key: string) | Returns the RangeAreas object based on worksheet name or ID in the collection. |
|
| ranges | Returns ranges that comprise this object in a RangeCollection object. |
|
| Worksheet | customProperties | Gets a collection of worksheet-level custom properties. |
| WorksheetCustomProperty | delete() | Deletes the custom property. |
| key | Gets the key of the custom property. | |
| value | Gets or sets the value of the custom property. | |
| WorksheetCustomPropertyCollection | add(key: string, value: string) | Adds a new custom property that maps to the provided key. |
| getCount() | Gets the number of custom properties on this worksheet. | |
| getItem(key: string) | Gets a custom property object by its key, which is case-insensitive. | |
| getItemOrNullObject(key: string) | Gets a custom property object by its key, which is case-insensitive. | |
| items | Gets the loaded child items in this collection. |