Skip to content

Commit 7c1a566

Browse files
alison-mkalison-mk
authored
Merge pull request #5184 from OfficeDev/main
[Admin] Publish
2 parents 21db8df + 6321522 commit 7c1a566

File tree

3 files changed

+148
-1
lines changed

3 files changed

+148
-1
lines changed

‎docs/excel/excel-add-ins-undo-capabilities.md

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
title: Undo capabilities with the Excel JavaScript API
3+
description: Learn how to preserve the undo stack in your Excel add-ins.
4+
ms.date: 05/15/2025
5+
ms.localizationpriority: medium
6+
---
7+
8+
# Undo support with the Excel JavaScript API (preview)
9+
10+
Excel add-ins support undo behavior. This preserves both actions performed by Excel JavaScript APIs and actions performed by the user in Excel. These actions are saved in the *undo stack* for an individual user, allowing the user to step back through their actions when desired.
11+
12+
> [!NOTE]
13+
> The features described in this article are currently available only in public preview. [!INCLUDE [Information about using preview APIs](../includes/using-excel-preview-apis.md)]
14+
15+
## Undo grouping
16+
17+
The Excel JavaScript API also supports undo grouping. This allows you to group multiple API calls into a single undoable action for your add-in user. For example, if your add-in needs to make several different updates across multiple worksheets in response to a single user command, you can wrap all those updates in a single group. This is done with the `mergeUndoGroup` property provided to the `Excel.run` function.
18+
19+
If an API within the group doesn't offer undo support, the `UndoNotSupported` error is thrown to let you know that the operation can’t be grouped. Your add-in should gracefully handle this error and present a reasonable message to the user.
20+
21+
The following code sample shows how to merge multiple actions with `mergeUndoGroup` set to `true`.
22+
23+
> [!IMPORTANT]
24+
> Ensure that all grouped API calls support undo to avoid errors. See [Unsupported APIs](#unsupported-apis) for more information.
25+
26+
```js
27+
await Excel.run({ mergeUndoGroup: true }, async (context) => {
28+
const sheet = context.workbook.worksheets.getActiveWorksheet();
29+
let range = sheet.getRange("A1");
30+
range.values = [["123"]];
31+
32+
await context.sync();
33+
34+
range = sheet.getRange("B2");
35+
range.values = [["456"]];
36+
37+
await context.sync();
38+
});
39+
```
40+
41+
## Unsupported APIs
42+
43+
Most Excel JavaScript APIs do support undo actions. However, see the following table for a list of APIs that do not support undo behavior.
44+
45+
> [!TIP]
46+
> If you call an unsupported API in your add-in, the user’s undo stack is cleared starting from that API call, and a user cannot undo actions past that point.
47+
48+
| API | Supported in Excel on the web | Supported in Excel on Windows and Excel on Mac | Notes |
49+
|:--------------|:------|:--------|:----------|
50+
| `AllowEditRange.address` | No | No | *None* |
51+
| `AllowEditRange.delete` | No | No | *None* |
52+
| `AllowEditRange.pauseProtection` | No | No | *None* |
53+
| `AllowEditRange.setPassword` | No | No | *None* |
54+
| `AllowEditRange.title` | No | No | *None* |
55+
| `AllowEditRangeCollection.add` | No | No | *None* |
56+
| `AllowEditRangeCollection.pauseProtection` | No | No | *None* |
57+
| `Chart.categoryLabelLevel` | No | No | *None* |
58+
| `Chart.seriesNameLevel` | No | No | *None* |
59+
| `ChartPivotOptions.showAxisFieldButtons` | No | Yes | *None* |
60+
| `ChartPivotOptions.showLegendFieldButtons` | No | Yes | *None* |
61+
| `ChartPivotOptions.showReportFilterFieldButtons` | No | Yes | *None* |
62+
| `ChartPivotOptions.showValueFieldButtons` | No | Yes | *None* |
63+
| `ChartTrendlineLabel.formula` | No | Yes | *None* |
64+
| `DataConnectionCollection.refreshAll` | No | No | *None* |
65+
| `DocumentProperties.author​` | No | Yes | *None* |
66+
| `DocumentProperties.category` | No | Yes | *None* |
67+
| `DocumentProperties.comments` | No | Yes | *None* |
68+
| `DocumentProperties.company` | No | Yes | *None* |
69+
| `DocumentProperties.keywords` | No | Yes | *None* |
70+
| `DocumentProperties.manager` | No | Yes | *None* |
71+
| `DocumentProperties.revisionNumber` | No | Yes | *None* |
72+
| `DocumentProperties.subject` | No | Yes | *None* |
73+
| `DocumentProperties.title` | No | Yes | *None* |
74+
| `LinkedWorkbook.refresh` | No | No | *None* |
75+
| `LinkedWorkbookCollection.refreshAll` | No | No | *None* |
76+
| `NamedItem.comment` | No | Yes | *None* |
77+
| `PivotTableStyle.delete` | No | Yes | API does **not** support co-authoring undo in Excel on Windows and Mac. |
78+
| `PivotTableStyle.duplicate` | No | Yes | *None* |
79+
| `PivotTableStyle.name` | No | Yes | *None* |
80+
| `PivotTableStyleCollection.add` | No | Yes | API does **not** support co-authoring undo in Excel on Windows and Mac. |
81+
| `PivotTableStyleCollection.setDefault` | No | Yes | API does **not** support co-authoring undo in Excel on Windows and Mac. |
82+
| `Query.delete` | No | Yes | API supports undo in Excel on Windows and Mac but doesn't support redo. |
83+
| `Query.refresh` | No | Yes | API supports undo Excel on Windows and Mac but doesn't support redo. |
84+
| `QueryCollection.refreshAll` | No | Yes | API supports undo Excel on Windows and Mac but doesn't support redo. |
85+
| `Slicer.name` | No | Yes | *None* |
86+
| `Slicer.nameInFormula` | No | Yes | *None* |
87+
| `SlicerStyle.delete` | No | Yes | API does **not** support co-authoring undo in Excel on Windows and Mac. |
88+
| `SlicerStyle.duplicate` | No | Yes | *None* |
89+
| `SlicerStyle.name` | No | Yes | *None* |
90+
| `SlicerStyleCollection.add` | No | Yes | API does **not** support co-authoring undo in Excel on Windows and Mac. |
91+
| `SlicerStyleCollection.setDefault` | No | Yes | API does **not** support co-authoring undo in Excel on Windows and Mac. |
92+
| `Style.addIndent` | No | Yes | *None* |
93+
| `Style.autoIndent` | No | Yes | *None* |
94+
| `Style.formulaHidden` | No | Yes | *None* |
95+
| `Style.horizontalAlignment` | No | Yes | *None* |
96+
| `Style.includeAlignment` | No | Yes | *None* |
97+
| `Style.includeBorder` | No | Yes | *None* |
98+
| `Style.includeFont` | No | Yes | *None* |
99+
| `Style.includeNumber` | No | Yes | *None* |
100+
| `Style.includePatterns` | No | Yes | *None* |
101+
| `Style.includeProtection` | No | Yes | *None* |
102+
| `Style.indentLevel` | No | Yes | *None* |
103+
| `Style.locked` | No | Yes | *None* |
104+
| `Style.numberFormat` | No | Yes | *None* |
105+
| `Style.numberFormatLocal` | No | Yes | *None* |
106+
| `Style.orientation` | No | Yes | *None* |
107+
| `Style.readingOrder` | No | Yes | *None* |
108+
| `Style.shrinkToFit` | No | Yes | *None* |
109+
| `Style.textOrientation` | No | Yes | *None* |
110+
| `Style.verticalAlignment` | No | Yes | *None* |
111+
| `Style.wrapText` | No | Yes | *None* |
112+
| `TableStyle.delete` | No | Yes | API does **not** support co-authoring undo in Excel on Windows and Mac. |
113+
| `TableStyle.duplicate` | No | Yes | *None* |
114+
| `TableStyle.name` | No | Yes | *None* |
115+
| `TableStyleCollection.add` | No | Yes | API does **not** support co-authoring undo in Excel on Windows and Mac. |
116+
| `TableStyleCollection.setDefault` | No | Yes | API does **not** support co-authoring undo in Excel on Windows and Mac. |
117+
| `TimelineStyle.delete` | No | Yes | API does **not** support co-authoring undo in Excel on Windows and Mac. |
118+
| `TimelineStyle.duplicate` | No | Yes | *None* |
119+
| `TimelineStyle.name` | No | Yes | *None* |
120+
| `TimelineStyleCollection.add` | No | Yes | API does **not** support co-authoring undo in Excel on Windows and Mac. |
121+
| `TimelineStyleCollection.setDefault` | No | Yes | API does **not** support co-authoring undo in Excel on Windows and Mac. |
122+
| `Workbook.close` | No | No | *None* |
123+
| `Workbook.insertWorksheetsFromBase64` | No | No | *None* |
124+
| `Workbook.save` | No | No | *None* |
125+
| `WorkbookProtection.protect` | No | No | *None* |
126+
| `WorkbookProtection.unprotect` | No | No | *None* |
127+
| `Worksheet.copy` | No | No | *None* |
128+
| `Worksheet.delete` | No | No | *None* |
129+
| `Worksheet.name` | Yes | No | *None* |
130+
| `Worksheet.standardWidth` | No | Yes | *None* |
131+
| `Worksheet.position` | Yes | No | *None* |
132+
| `Worksheet.visibility​` | Yes | No | *None* |
133+
| `WorksheetCollection.addFromBase64` | No | No | *None* |
134+
| `WorksheetProtection.pauseProtection` | No | No | *None* |
135+
| `WorksheetProtection.protect` | No | No | *None* |
136+
| `WorksheetProtection.resumeProtection` | No | No | *None* |
137+
| `WorksheetProtection.setPassword` | No | No | *None* |
138+
| `WorksheetProtection.unprotect` | No | No | *None* |
139+
| `WorksheetProtection.updateOptions` | No | No | *None* |
140+
141+
## See also
142+
143+
- [Excel JavaScript object model in Office Add-ins](excel-add-ins-core-concepts.md)

‎docs/testing/application-specific-api-error-handling.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Error handling with the application-specific JavaScript APIs
33
description: Learn about Excel, Word, PowerPoint, and other application-specific JavaScript API error handling logic to account for runtime errors.
44
ms.topic: error-reference
5-
ms.date: 03/01/2024
5+
ms.date: 05/15/2025
66
ms.localizationpriority: medium
77
---
88

@@ -107,6 +107,7 @@ The following tables list the errors that application-specific APIs may return.
107107
|`PivotTableRangeConflict`|The attempted operation causes a conflict with a PivotTable range.|*None* |
108108
|`RangeExceedsLimit`|The cell count in the range has exceeded the maximum supported number. See the [Resource limits and performance optimization for Office Add-ins](../concepts/resource-limits-and-performance-optimization.md#excel-add-ins) article for more information.|*None* |
109109
|`RefreshWorkbookLinksBlocked`|The operation failed because the user hasn't granted permission to refresh external workbook links.|*None* |
110+
|`UndoNotSupported`|The JavaScript API request failed due to lack of support for the undo operation.|*None* |
110111
|`UnsupportedSheet`|This sheet type does not support this operation, since it is a Macro or Chart sheet.|*None* |
111112

112113
### Word-specific error codes and messages

‎docs/toc.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -601,6 +601,9 @@ items:
601601
- name: Tables
602602
href: excel/excel-add-ins-tables.md
603603
displayName: Excel
604+
- name: Undo support
605+
href: excel/excel-add-ins-undo-capabilities.md
606+
displayName: Excel
604607
- name: Workbooks
605608
href: excel/excel-add-ins-workbooks.md
606609
displayName: Excel

0 commit comments

Comments
 (0)