Skip to content

Commit ac8d8f6

Browse files
sridhar-alagirisamysridhar-alagirisamy
authored
Merge pull request #2364 from syncfusion-content/EJ2-1013906-dev
1013906: Add an "Events" section documenting feature-specific Spreadsheet events.
2 parents 9a35ec1 + ce095b5 commit ac8d8f6

8 files changed

Lines changed: 415 additions & 0 deletions

File tree

‎Document-Processing-toc.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5461,6 +5461,7 @@
54615461
<li><a href="/document-processing/excel/spreadsheet/react/mobile-responsiveness">Mobile Responsiveness</a></li>
54625462
<li><a href="/document-processing/excel/spreadsheet/react/feature-list">Features Availability</a>
54635463
</li>
5464+
<li><a href="/document-processing/excel/spreadsheet/react/events">Events</a></li>
54645465
<li><a href="https://ej2.syncfusion.com/react/documentation/api/spreadsheet/">API Reference</a></li>
54655466
</ul>
54665467
</li>

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

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
layout: post
3+
title: Events in React Spreadsheet component | Syncfusion
4+
description: Learn here all about the events in Syncfusion React Spreadsheet component of Syncfusion Essential JS 2 and more.
5+
control: Events
6+
platform: document-processing
7+
documentation: ug
8+
---
9+
10+
# Events in React Spreadsheet Component
11+
12+
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.
13+
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.
80+
81+
{% tabs %}
82+
{% highlight js tabtitle="app.jsx" %}
83+
{% include code-snippet/spreadsheet/react/events/app/app.jsx %}
84+
{% endhighlight %}
85+
{% highlight ts tabtitle="app.tsx" %}
86+
{% include code-snippet/spreadsheet/react/events/app/app.tsx %}
87+
{% endhighlight %}
88+
{% endtabs %}
89+
90+
{% previewsample "/document-processing/code-snippet/spreadsheet/react/events" %}
91+
92+
## Clipboard
93+
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.
95+
96+
### Cut / Copy
97+
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:
99+
100+
* `args.action === 'cut'` → Indicates a Cut action
101+
* `args.action === 'copy'` → Indicates a Copy action
102+
* `args.args.copiedRange` → Provides the range of copied cells
103+
104+
### Paste
105+
106+
During a **Paste** operation, events are triggered in the following sequence:
107+
108+
> actionBegin → beforeCellUpdate → cellSave → actionComplete
109+
110+
The table below describes each event and its role in the paste process:
111+
112+
| **Event** | **Description** | **Event Arguments** |
113+
|-----------|------------------|----------------------|
114+
| [`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) |
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) |
116+
| [`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) |
117+
| [`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) |
118+
119+
### Accessing copied and pasted ranges
120+
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:
122+
123+
* `args.action === 'clipboard'` → Indicates a paste action
124+
125+
Once verified, you can access the following properties:
126+
127+
* `args.eventArgs.copiedRange` → The range of cells that were copied
128+
* `args.eventArgs.pastedRange` → The range of cells where content was pasted
129+
130+
## Editing
131+
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.
133+
134+
The sequence of events during manual cell editing is:
135+
136+
> cellEdit → cellEditing → actionBegin → beforeCellUpdate → beforeCellSave → cellSave → cellEdited → actionComplete
137+
138+
The table below describes each event and its role in the editing process:
139+
140+
| **Event** | **Description** | **Event Arguments** |
141+
|-----------|------------------|----------------------|
142+
| [`cellEdit`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#celledit) | Triggers before the cell enters edit mode. | [`CellEditEventArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/cellediteventargs) |
143+
| [`cellEditing`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#cellediting) | Triggers while editing is in progress; fires for each change made to the cell content. | [`CellEditingEventArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/cellediteventargs) |
144+
| [`actionBegin`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actionbegin) | Triggers when the edit action starts. | [`ActionBeginEventArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#actionbegin) |
145+
| [`beforeCellUpdate`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#beforecellupdate) | Triggers before any cell property (style, value, formula, etc.) is modified. | [`BeforeCellUpdateArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/beforecellupdateargs) |
146+
| [`beforeCellSave`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#beforecellsave) | Triggers before the cell value is saved. | [`BeforeCellSaveEventArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/cellediteventargs) |
147+
| [`cellSave`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/index-default#cellsave) | Triggers when the modified cell value is saved. | [`CellSaveEventArgs`](https://ej2.syncfusion.com/react/documentation/api/spreadsheet/cellsaveeventargs) |
148+
| [`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) |
149+
| [`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) |
150+
151+
## See Also
152+
153+
* [Editing](./editing.md)
154+
* [Clipboard](./clipboard.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 />);

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

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

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
export let data = [
2+
{ 'Item Name': 'Casual Shoes', Date: '02/14/2014', Time: '11:34:32 AM', Quantity: 10, Price: 20, Amount: 200, Discount: 1, Profit: 10 },
3+
{ 'Item Name': 'Sports Shoes', Date: '06/11/2014', Time: '05:56:32 AM', Quantity: 20, Price: 30, Amount: 600, Discount: 5, Profit: 50 },
4+
{ 'Item Name': 'Formal Shoes', Date: '07/27/2014', Time: '03:32:44 AM', Quantity: 20, Price: 15, Amount: 300, Discount: 7, Profit: 27 },
5+
{ 'Item Name': 'Sandals & Floaters', Date: '11/21/2014', Time: '06:23:54 AM', Quantity: 15, Price: 20, Amount: 300, Discount: 11, Profit: 67 },
6+
{ 'Item Name': 'Flip- Flops & Slippers', Date: '06/23/2014', Time: '12:43:59 AM', Quantity: 30, Price: 10, Amount: 300, Discount: 10, Profit: 70 },
7+
{ 'Item Name': 'Sneakers', Date: '07/22/2014', Time: '10:55:53 AM', Quantity: 40, Price: 20, Amount: 800, Discount: 13, Profit: 66 },
8+
{ 'Item Name': 'Running Shoes', Date: '02/04/2014', Time: '03:44:34 AM', Quantity: 20, Price: 10, Amount: 200, Discount: 3, Profit: 14 },
9+
{ 'Item Name': 'Loafers', Date: '11/30/2014', Time: '03:12:52 AM', Quantity: 31, Price: 10, Amount: 310, Discount: 6, Profit: 29 },
10+
{ 'Item Name': 'Cricket Shoes', Date: '07/09/2014', Time: '11:32:14 AM', Quantity: 41, Price: 30, Amount: 1210, Discount: 12, Profit: 166 },
11+
{ 'Item Name': 'T-Shirts', Date: '10/31/2014', Time: '12:01:44 AM', Quantity: 50, Price: 10, Amount: 500, Discount: 9, Profit: 55 },
12+
];

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
export let data: Object[] = [
2+
{ 'Item Name': 'Casual Shoes', Date: '02/14/2014', Time: '11:34:32 AM', Quantity: 10, Price: 20, Amount: 200, Discount: 1, Profit: 10 },
3+
{ 'Item Name': 'Sports Shoes', Date: '06/11/2014', Time: '05:56:32 AM', Quantity: 20, Price: 30, Amount: 600, Discount: 5, Profit: 50 },
4+
{ 'Item Name': 'Formal Shoes', Date: '07/27/2014', Time: '03:32:44 AM', Quantity: 20, Price: 15, Amount: 300, Discount: 7, Profit: 27 },
5+
{ 'Item Name': 'Sandals & Floaters', Date: '11/21/2014', Time: '06:23:54 AM', Quantity: 15, Price: 20, Amount: 300, Discount: 11, Profit: 67 },
6+
{ 'Item Name': 'Flip- Flops & Slippers', Date: '06/23/2014', Time: '12:43:59 AM', Quantity: 30, Price: 10, Amount: 300, Discount: 10, Profit: 70 },
7+
{ 'Item Name': 'Sneakers', Date: '07/22/2014', Time: '10:55:53 AM', Quantity: 40, Price: 20, Amount: 800, Discount: 13, Profit: 66 },
8+
{ 'Item Name': 'Running Shoes', Date: '02/04/2014', Time: '03:44:34 AM', Quantity: 20, Price: 10, Amount: 200, Discount: 3, Profit: 14 },
9+
{ 'Item Name': 'Loafers', Date: '11/30/2014', Time: '03:12:52 AM', Quantity: 31, Price: 10, Amount: 310, Discount: 6, Profit: 29 },
10+
{ 'Item Name': 'Cricket Shoes', Date: '07/09/2014', Time: '11:32:14 AM', Quantity: 41, Price: 30, Amount: 1210, Discount: 12, Profit: 166 },
11+
{ 'Item Name': 'T-Shirts', Date: '10/31/2014', Time: '12:01:44 AM', Quantity: 50, Price: 10, Amount: 500, Discount: 9, Profit: 55 },
12+
];

0 commit comments

Comments
 (0)