Skip to content

Commit bad87f7

Browse files
DinakarSF4212DinakarSF4212
committed
1013906: Add an "Events" section documenting feature-specific Spreadsheet events.
1 parent d193d99 commit bad87f7

7 files changed

Lines changed: 344 additions & 171 deletions

File tree

‎Document-Processing/Excel/Spreadsheet/React/events.md‎

Lines changed: 84 additions & 171 deletions
Original file line numberDiff line numberDiff line change
@@ -11,87 +11,97 @@ documentation: ug
1111

1212
The Spreadsheet component triggers events for creation, data binding, selection, editing, clipboard actions, sorting, filtering, formatting, row and column insertion or deletion, context menu and ribbon interactions, and import/export operations—enabling integration of custom logic into application workflows.
1313

14-
## actionBegin
14+
## Action Events
15+
16+
The `actionBegin` and `actionComplete` events are the primary action events in the Spreadsheet.
17+
18+
The `actionBegin` event triggers when any action begins in the Spreadsheet and fires for all user-initiated actions, enabling you to identify the action type, prevent specific actions from executing, and apply custom logic at the initiation of an action.
19+
20+
The `actionComplete` event triggers when any action completes in the Spreadsheet and fires for all user-initiated actions, enabling you to identify the action type and apply custom logic after an action has successfully completed.
21+
22+
You can identify the type of action being triggered by using the `args.action` property during both the action events.
23+
24+
The following table represents the action names for which the `actionBegin` and `actionComplete` events are triggered in the Spreadsheet:
25+
26+
| **Action** | **ActionBegin** | **ActionComplete** |
27+
|--------|-------------|----------------|
28+
| Add Data Validation | validation | validation |
29+
| Add Defined Name | - | addDefinedName |
30+
| Autofill | autofill | autofill |
31+
| Autofit | resizeToFit | resizeToFit |
32+
| Cell Delete | cellDelete | cellDelete |
33+
| Cell Save (Edit) | cellSave | cellSave |
34+
| Chart Design | chartDesign | chartDesign |
35+
| Chart Deletion | deleteChart | deleteChart |
36+
| Chart Insertion | beforeInsertChart | insertChart |
37+
| Chart (Resize/Drag and Drop) | - | chartRefresh |
38+
| Clear | beforeClear | clear |
39+
| Clear Conditional Formatting | - | clearCF |
40+
| Clear Validation | removeValidation | removeValidation |
41+
| Clear Highlight | removeHighlight | removeHighlight |
42+
| Clipboard (Copy) | copy | - |
43+
| Clipboard (Cut) | cut | - |
44+
| Clipboard (Paste) | clipboard | clipboard |
45+
| Comment | addComment | addComment |
46+
| Conditional Formatting | conditionalFormat | conditionalFormat |
47+
| Delete | delete | delete |
48+
| Delete Comment | deleteComment | deleteComment |
49+
| Delete (Rows/Columns) | delete | delete |
50+
| Filter | filter | filter |
51+
| Formatting (Cell/Number) | format | format |
52+
| Freeze Panes | freezePanes | freezePanes |
53+
| Gridlines | gridlines | gridlines |
54+
| Headers | headers | headers |
55+
| Hide (Row/Column) | hideShow | hideShow |
56+
| Highlight Invalid Data | addHighlight | addHighlight |
57+
| Hyperlink | hyperlink | hyperlink |
58+
| Image Deletion | deleteImage | deleteImage |
59+
| Image Insertion | beforeInsertImage | insertImage |
60+
| Image (Resize/Drag and Drop) | - | imageRefresh |
61+
| Insert (Row/Column/Sheet) | insert | insert |
62+
| Merge | merge | merge |
63+
| Open | beforeOpen | import |
64+
| Protect Sheet | protectSheet | protectSheet |
65+
| Read-Only | readonly | readonly |
66+
| Remove Defined Name | - | removeDefinedName |
67+
| Replace | beforeReplace | replace |
68+
| Replace All | beforeReplaceAll | replaceAll |
69+
| Resize (Row/Column) | - | resize |
70+
| Save | beforeSave | - |
71+
| Sort | beforeSort | sorting |
72+
| Sheet Duplicate | duplicateSheet | duplicateSheet |
73+
| Sheet Hide | hideSheet | hideSheet |
74+
| Sheet Move | moveSheet | moveSheet |
75+
| Sheet Rename | renameSheet | renameSheet |
76+
| Wrap | beforeWrap | wrap |
77+
78+
79+
The following code example demonstrates how to bind the `actionBegin` and `actionComplete` events in the Spreadsheet.
1580

16-
The `actionBegin` event triggers when any action begins in the spreadsheet. This event fires for all user-initiated actions, enabling you to identify the action type, prevent specific actions from executing, and apply custom logic at the initiation of an action.
17-
18-
**Event Arguments:** [`ActionBeginEventArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actionbegin)
19-
20-
You can identify the type of action being triggered using the `args.action` property.
21-
22-
The following code example demonstrates how to bind the `actionBegin` event in the spreadsheet.
2381
{% tabs %}
24-
{% highlight ts tabtitle="app.tsx" %}
25-
import * as React from 'react';
26-
import { createRoot } from 'react-dom/client';
27-
import { SpreadsheetComponent } from '@syncfusion/ej2-react-spreadsheet';
28-
function App() {
29-
const spreadsheetRef = React.useRef<SpreadsheetComponent>(null);
30-
31-
const actionBegin = (args: any) => {
32-
console.log(`actionBegin triggered ${args.action}`);
33-
console.log(args);
34-
}
35-
36-
return (
37-
<SpreadsheetComponent ref={spreadsheetRef} actionBegin={actionBegin}>
38-
</SpreadsheetComponent>
39-
);
40-
};
41-
export default App;
42-
43-
const root = createRoot(document.getElementById('root')!);
44-
root.render(<App />);
82+
{% highlight js tabtitle="app.jsx" %}
83+
{% include code-snippet/spreadsheet/react/events/app/app.jsx %}
4584
{% endhighlight %}
46-
{% endtabs %}
47-
48-
## actionComplete
49-
50-
The `actionComplete` event triggers when any action completes in the spreadsheet. This event fires for all user-initiated actions, enabling you to identify the action type and apply custom logic after an action has successfully completed.
51-
52-
**Event Arguments:** [`ActionCompleteEventArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actioncomplete)
53-
54-
You can identify the type of action that completed using the `args.action` property.
55-
56-
The following code example demonstrates how to bind the `actionComplete` event in the spreadsheet.
57-
{% tabs %}
5885
{% highlight ts tabtitle="app.tsx" %}
59-
import * as React from 'react';
60-
import { createRoot } from 'react-dom/client';
61-
import { SpreadsheetComponent } from '@syncfusion/ej2-react-spreadsheet';
62-
function App() {
63-
const spreadsheetRef = React.useRef<SpreadsheetComponent>(null);
64-
65-
const actionComplete = (args: any) => {
66-
console.log(`actionComplete triggered ${args.action}`);
67-
console.log(args);
68-
}
69-
70-
return (
71-
<SpreadsheetComponent ref={spreadsheetRef} actionComplete={actionComplete}>
72-
</SpreadsheetComponent>
73-
);
74-
};
75-
export default App;
76-
77-
const root = createRoot(document.getElementById('root')!);
78-
root.render(<App />);
86+
{% include code-snippet/spreadsheet/react/events/app/app.tsx %}
7987
{% endhighlight %}
8088
{% endtabs %}
8189

90+
{% previewsample "/document-processing/code-snippet/spreadsheet/react/events" %}
91+
8292
## Clipboard
8393

84-
When performing clipboard operations such as **Cut**, **Copy**, or **Paste**, the spreadsheet triggers specific events that allow users to monitor and manage these actions effectively. The following sections outline the event sequence and their roles.
94+
When performing clipboard operations such as **Cut**, **Copy**, or **Paste**, the Spreadsheet triggers specific events that allow you to monitor and manage these actions effectively. The following sections outline the event sequence and their roles.
8595

86-
**Cut / Copy**
96+
### Cut / Copy
8797

88-
For **Cut** or **Copy** actions, only the [`actionBegin`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actionbegin) event is triggered. You can identify the type of action and access the copied range using the following properties:
98+
For **Cut** or **Copy** actions, only the [`actionBegin`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actionbegin) event is triggered. You can identify the action type and access the copied range by using the following properties:
8999

90100
* `args.action === 'cut'` → Indicates a Cut action
91101
* `args.action === 'copy'` → Indicates a Copy action
92-
* `args.args.copiedRange` → Provides the copied range
102+
* `args.args.copiedRange` → Provides the range of copied cells
93103

94-
**Paste**
104+
### Paste
95105

96106
During a **Paste** operation, events are triggered in the following sequence:
97107

@@ -102,70 +112,30 @@ The table below describes each event and its role in the paste process:
102112
| **Event** | **Description** | **Event Arguments** |
103113
|-----------|------------------|----------------------|
104114
| [`actionBegin`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actionbegin) | Triggers when the paste action starts. | [`ActionBeginEventArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actionbegin) |
105-
| [`beforeCellUpdate`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#beforecellupdate) | Triggers for each cell in the pasted range before it is updated, allowing modification and cancelling `paste` action. | [`BeforeCellUpdateArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/beforecellupdateargs) |
115+
| [`beforeCellUpdate`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#beforecellupdate) | Triggers for each cell in the pasted range before it is updated, allowing you to modify cell properties or cancel the `paste` action. | [`BeforeCellUpdateArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/beforecellupdateargs) |
106116
| [`cellSave`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#cellsave) | Triggers for each cell in the pasted range after the modified cell is saved. | [`CellSaveEventArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/cellsaveeventargs) |
107117
| [`actionComplete`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actioncomplete) | Triggers after all pasted cells are fully saved. | [`ActionCompleteEventArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actioncomplete) |
108118

109-
**Accessing clipboard properties**
119+
### Accessing copied and pasted ranges
110120

111-
You can access clipboard-related properties such as the copied and pasted ranges during paste operations using the [`actionBegin`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actionbegin) and [`actionComplete`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actioncomplete) events. Verify the action type using:
121+
You can access the copied and pasted ranges during paste operations by using the [`actionBegin`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actionbegin) and [`actionComplete`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actioncomplete) events. Verify the action type using:
112122

113-
* `args.action === 'clipboard'` → Indicates a paste action.
123+
* `args.action === 'clipboard'` → Indicates a paste action
114124

115125
Once verified, you can access the following properties:
116126

117127
* `args.eventArgs.copiedRange` → The range of cells that were copied
118-
* `args.eventArgs.pastedRange` → The range of cells where the content was pasted
119-
120-
The following code example showcases the events triggered during clipboard operations in the spreadsheet.
121-
{% tabs %}
122-
{% highlight ts tabtitle="app.tsx" %}
123-
124-
import * as React from 'react';
125-
import { createRoot } from 'react-dom/client';
126-
import { SpreadsheetComponent } from '@syncfusion/ej2-react-spreadsheet';
127-
128-
function App() {
129-
const spreadsheetRef = React.useRef<SpreadsheetComponent>(null);
130-
131-
const actionBegin = (args: any) => {
132-
console.log(`actionBegin triggered ${args.action}`);
133-
console.log(args);
134-
}
135-
136-
const beforeCellUpdate = (args: any) => {
137-
console.log(args);
138-
}
139-
140-
const cellSave = (args: any) => {
141-
console.log(args);
142-
}
143-
144-
const actionComplete = (args: any) => {
145-
console.log(`actionComplete triggered ${args.action}`);
146-
console.log(args);
147-
}
148-
149-
return (
150-
<SpreadsheetComponent ref={spreadsheetRef} actionBegin={actionBegin} beforeCellUpdate={beforeCellUpdate} cellSave={cellSave} actionComplete={actionComplete} >
151-
</SpreadsheetComponent>
152-
);
153-
};
154-
export default App;
155-
156-
const root = createRoot(document.getElementById('root')!);
157-
root.render(<App />);
158-
{% endhighlight %}
159-
{% endtabs %}
128+
* `args.eventArgs.pastedRange` → The range of cells where content was pasted
160129

161130
## Editing
162131

163-
When a cell is edited manually—such as by **double-clicking the cell**, **pressing the F2 key**, or **modifying it through the formula bar**—the spreadsheet triggers a series of events. These events allow users to monitor and manage the entire editing process, from initiation to completion.
132+
When a cell is edited manually—such as by **double-clicking the cell**, **pressing the F2 key**, or **modifying it through the formula bar**—the Spreadsheet triggers a series of events. These events allow you to monitor and manage the entire editing process, from initiation to completion.
164133

165134
The sequence of events during manual cell editing is:
135+
166136
> cellEdit → cellEditing → actionBegin → beforeCellUpdate → beforeCellSave → cellSave → cellEdited → actionComplete
167137
168-
The table below lists each event and its role in the editing process:
138+
The table below describes each event and its role in the editing process:
169139

170140
| **Event** | **Description** | **Event Arguments** |
171141
|-----------|------------------|----------------------|
@@ -178,63 +148,6 @@ The table below lists each event and its role in the editing process:
178148
| [`cellEdited`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#celledited) | Triggers after the editing process completes. | [`CellEditedEventArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/cellediteventargs) |
179149
| [`actionComplete`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actioncomplete) | Triggers once the entire edit operation is completed. | [`ActionCompleteEventArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actioncomplete) |
180150

181-
The following code example showcases the events triggered during cell editing in the spreadsheet.
182-
183-
{% tabs %}
184-
{% highlight ts tabtitle="app.tsx" %}
185-
import * as React from 'react';
186-
import { createRoot } from 'react-dom/client';
187-
import { SpreadsheetComponent } from '@syncfusion/ej2-react-spreadsheet';
188-
189-
function App() {
190-
const spreadsheetRef = React.useRef<SpreadsheetComponent>(null);
191-
192-
const actionBegin = (args: any) => {
193-
console.log(`actionBegin triggered ${args.action}`);
194-
console.log(args);
195-
}
196-
197-
const beforeCellSave = (args: any) => {
198-
console.log(args);
199-
}
200-
201-
const beforeCellUpdate = (args: any) => {
202-
console.log(args);
203-
}
204-
205-
const cellEdit = (args: any) => {
206-
console.log(args);
207-
}
208-
209-
const cellEditing = (args: any) => {
210-
console.log(args);
211-
}
212-
213-
const cellEdited = (args: any) => {
214-
console.log(args);
215-
}
216-
217-
const cellSave = (args: any) => {
218-
console.log(args);
219-
}
220-
221-
const actionComplete = (args: any) => {
222-
console.log(`actionComplete triggered ${args.action}`);
223-
console.log(args);
224-
}
225-
226-
return (
227-
<SpreadsheetComponent ref={spreadsheetRef} actionBegin={actionBegin} beforeCellSave={beforeCellSave} beforeCellUpdate={beforeCellUpdate} cellSave={cellSave} cellEdit={cellEdit} cellEditing={cellEditing} cellEdited={cellEdited} actionComplete={actionComplete} >
228-
</SpreadsheetComponent>
229-
);
230-
};
231-
export default App;
232-
233-
const root = createRoot(document.getElementById('root')!);
234-
root.render(<App />);
235-
{% endhighlight %}
236-
{% endtabs %}
237-
238151
## See Also
239152

240153
* [Editing](./editing.md)

‎Document-Processing/code-snippet/spreadsheet/react/events/app/app.jsx‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
import React, { useRef } from 'react';
2+
import { createRoot } from 'react-dom/client';
3+
import { SpreadsheetComponent, SheetsDirective, SheetDirective, RangesDirective, RangeDirective, ColumnsDirective, ColumnDirective } from '@syncfusion/ej2-react-spreadsheet';
4+
import { data } from './datasource';
5+
6+
function App() {
7+
const spreadsheetRef = useRef(null);
8+
9+
const actionBegin = (args) => {
10+
appendElement(`actionBegin triggered for <b>&nbsp;${args.action}</b> action<hr>`);
11+
console.log(args);
12+
}
13+
14+
const actionComplete = (args) => {
15+
appendElement(`actionComplete triggered for <b>&nbsp;${args.action}</b> action<hr>`);
16+
console.log(args);
17+
}
18+
19+
const clearBtnClick = () => {
20+
const eventLog = document.getElementById('EventLog');
21+
if (eventLog) {
22+
eventLog.innerHTML = "";
23+
}
24+
};
25+
const appendElement = (html) => {
26+
const span = document.createElement("span");
27+
span.innerHTML = html;
28+
const log = document.getElementById('EventLog');
29+
if (log) {
30+
log.insertBefore(span, log.firstChild);
31+
}
32+
};
33+
34+
return (
35+
<div>
36+
<div>
37+
<SpreadsheetComponent ref={spreadsheetRef} actionBegin={actionBegin} actionComplete={actionComplete}>
38+
<SheetsDirective>
39+
<SheetDirective>
40+
<RangesDirective>
41+
<RangeDirective dataSource={data}></RangeDirective>
42+
</RangesDirective>
43+
<ColumnsDirective>
44+
<ColumnDirective width={180}></ColumnDirective>
45+
<ColumnDirective width={130}></ColumnDirective>
46+
<ColumnDirective width={130}></ColumnDirective>
47+
<ColumnDirective width={180}></ColumnDirective>
48+
<ColumnDirective width={130}></ColumnDirective>
49+
<ColumnDirective width={120}></ColumnDirective>
50+
</ColumnsDirective>
51+
</SheetDirective>
52+
</SheetsDirective>
53+
</SpreadsheetComponent>
54+
</div>
55+
<div>
56+
<h4><b>Event Trace</b></h4>
57+
<div id="evt">
58+
<div>
59+
<span id="EventLog"></span>
60+
</div>
61+
<button id="clearBtn" className='e-btn' onClick={clearBtnClick}>Clear</button>
62+
</div>
63+
</div>
64+
</div>
65+
);
66+
};
67+
export default App;
68+
69+
const root = createRoot(document.getElementById('root'));
70+
root.render(<App />);

0 commit comments

Comments
 (0)