You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/excel/custom-functions-synchronous.md
+18-17Lines changed: 18 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,48 +7,49 @@ ms.localizationpriority: medium
7
7
8
8
# Synchronous custom functions
9
9
10
-
Synchronous custom functions allow evaluate and conditional format processes to run in Excel simultaneously with the custom function. Enable synchronous support when your custom function needs to run in tandem with any the Excel processes listed in this article. If a custom function doesn't support synchronous operations, it returns an error such as `#CALC!` or `#VALUE!` when it runs at the same time as these Excel processes.
10
+
Synchronous custom functions allow evaluate and conditional format processes to run in Excel simultaneously with the custom function. Enable synchronous support when your custom function needs to run in tandem with any the Excel processes listed in this article. Custom functions that don't support synchronous operations return an error such as `#CALC!` or `#VALUE!` when they run at the same time as these Excel processes.
11
11
12
12
> [!WARNING]
13
-
> Synchronous custom functions don't support write operations with Office JavaScript APIs, such as using `Range.values` to set a cell value. Calling a write operation in a synchronous custom function may cause Excel to freeze.
13
+
> Synchronous custom functions don't support write operations with Office JavaScript APIs, such as using `Range.values` to set a cell value. Calling a write operation in a synchronous custom function may cause Excel to freeze. Do not use write operations in synchronous custom functions.
14
14
15
15
## Excel processes supported by synchronous custom functions
16
16
17
-
The following Excel actions and processes work with synchronous custom functions.
17
+
The following actions and processes work with synchronous custom functions.
18
18
19
-
### Evaluate actions
19
+
### Supported evaluate actions
20
20
21
-
-UI action: Formulas > Evaluate Formula.
22
-
-UI action: Formulas > Insert Function.
23
-
-UI action: In cell edit mode, selecting part of a formula and using F9 to see partial calculation results.
24
-
-VBA API: Application.Calculate.
21
+
-Selecting Formulas and then Evaluate Formula in Excel.
22
+
-Selecting Formulas and then Insert Function in Excel.
23
+
- In cell edit mode, selecting part of a formula and using F9 to see partial calculation results.
24
+
-The `Application.Calculate` method in VBA.
25
25
26
-
### Conditional format actions
26
+
### Supported conditional format actions
27
27
28
-
The following list applies to conditional format actions triggered by both the Excel UI and Office JavaScript APIs.
28
+
The following list applies to conditional formatting actions triggered by both the Excel UI and Office JavaScript APIs.
29
29
30
-
- Create new rule.
30
+
- Create a new rule.
31
31
- Edit rules.
32
32
- Delete rules.
33
33
- Reorder rules.
34
-
- Change “Applies to” range.
35
-
- Toggle “Stop if True”.
34
+
- Change the “Applies to” range.
35
+
- Toggle “Stop if true” on or off.
36
36
- Clear all rules.
37
-
- Copy/Cut and Paste cells containing conditional formatting.
37
+
- Cut and paste cells that contain conditional formatting.
38
+
- Copy and paste cells that contain conditional formatting.
38
39
39
40
> [!NOTE]
40
-
> When a synchronous custom function takes a significant amount of time to complete, Excel might temporarily block the user interface while waiting for the result. To avoid prolonged interruptions, users can cancel the execution at any time by using <kbd>Esc</kbd> or by selecting anywhere outside the cell or dialog.
41
+
> When a synchronous custom function takes a significant amount of time to complete, Excel might temporarily block the user interface while waiting for the result. To avoid prolonged interruptions, users can cancel the function execution at any time by using the <kbd>Esc</kbd> key or selecting anywhere outside the cell or dialog.
41
42
42
43
## Enable synchronous support in your add-in
43
44
44
-
To support synchronous scenarios in your add-in:
45
+
To support synchronous scenarios in your add-in, take the following steps.
45
46
46
47
- If you [autogenerate JSON metadata](custom-functions-json-autogeneration.md), use the `@supportSync` JSDoc tag.
47
48
- If you [manually create JSON metadata](custom-functions-json.md), use the `"supportSync": true` setting in the `"options"` object of your **functions.json** file.
48
49
- If the function uses `Excel.RequestContext`, call the `setInvocation` method of `Excel.RequestContext` and pass in the `CustomFunctions.Invocation` object. For an example, see the [code sample](#code-sample).
49
50
50
51
> [!IMPORTANT]
51
-
> Synchronous custom functions can't be **streaming** or **volatile** functions. If you use the `@supportSync` tag with `@volatile` or `@streaming` tags, Excel ignores the synchronous support. Volatile or streaming support takes precedence, and the custom function can't run at the same time as evaluate or conditional format processes.
52
+
> Synchronous custom functions can't be **streaming** or **volatile** functions. If you use the `@supportSync` tag with `@volatile` or `@streaming` tags, Excel ignores the synchronous support. Volatile or streaming support takes precedence.
0 commit comments