Excel.WorksheetChangedEventArgs interface
Provides information about the worksheet that raised the changed event.
Remarks
Properties
| address | Gets the range address that represents the changed area of a specific worksheet. |
| change |
Represents a change to the direction that the cells in a worksheet will shift when a cell or cells are deleted or inserted. This includes the following two scenarios. 1. The direction (such as down or to the right) that existing cells will shift when a new cell or cells are inserted into a worksheet. 2. The direction (such as up or to the left) that the remaining cells will shift when a cell or cells are deleted from a worksheet. |
| change |
Gets the change type that represents how the changed event is triggered. See |
| details | Represents the information about the change detail. This property can be retrieved when the changed event is triggered on a single cell. If the changed event is triggered on multiple cells, this property cannot be retrieved. |
| source | Gets the source of the event. See |
| trigger |
Represents the trigger source of the event. For example, identifies whether this local add-in triggers the event. |
| type | Gets the type of the event. See |
| worksheet |
Gets the ID of the worksheet in which the data changed. |
Methods
| get |
Gets the range that represents the changed area of a specific worksheet. |
| get |
Gets the range that represents the changed area of a specific worksheet. It might return null object. |
Property Details
address
Gets the range address that represents the changed area of a specific worksheet.
address: string;Property Value
string
Remarks
changeDirectionState
Represents a change to the direction that the cells in a worksheet will shift when a cell or cells are deleted or inserted. This includes the following two scenarios. 1. The direction (such as down or to the right) that existing cells will shift when a new cell or cells are inserted into a worksheet. 2. The direction (such as up or to the left) that the remaining cells will shift when a cell or cells are deleted from a worksheet.
changeDirectionState: Excel.ChangeDirectionState;Property Value
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-worksheet.yaml
async function onChange(event: Excel.WorksheetChangedEventArgs) {
// This function is an event handler that returns the address, trigger source,
// and insert or delete shift directions of the change.
await Excel.run(async (context) => {
// Return the address where change occurred.
console.log(`Handler for worksheet onChanged event has been triggered.`);
console.log(` Data changed address: ` + event.address);
// Return the source of the event that triggered the change.
console.log(` Data change trigger source: ` + event.triggerSource);
// Note：insertShiftDirection and deleteShiftDirection are exclusive and both enums can't have a value at the same time.
// If one has a value, then the other will return undefined.
// If the insert shift direction is defined, return it.
if (event.changeDirectionState.insertShiftDirection) {
console.log(` Cells inserted shift direction: ` + event.changeDirectionState.insertShiftDirection);
}
// If the delete shift direction is defined, return it.
if (event.changeDirectionState.deleteShiftDirection) {
console.log(` Cells deleted shift direction: ` + event.changeDirectionState.deleteShiftDirection);
}
});
}
...
// This function deletes data from a range and sets the delete shift direction to "up".
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getItem("Sample");
const range = sheet.getRange("A5:F5");
range.delete(Excel.DeleteShiftDirection.up);
});
changeType
Gets the change type that represents how the changed event is triggered. See Excel.DataChangeType for details.
changeType: Excel.DataChangeType | "Unknown" | "RangeEdited" | "RowInserted" | "RowDeleted" | "ColumnInserted" | "ColumnDeleted" | "CellInserted" | "CellDeleted";Property Value
Excel.DataChangeType | "Unknown" | "RangeEdited" | "RowInserted" | "RowDeleted" | "ColumnInserted" | "ColumnDeleted" | "CellInserted" | "CellDeleted"
Remarks
details
Represents the information about the change detail. This property can be retrieved when the changed event is triggered on a single cell. If the changed event is triggered on multiple cells, this property cannot be retrieved.
details: Excel.ChangedEventDetail;Property Value
Remarks
Examples
// This function would be used as an event handler for the Worksheet.onChanged event.
async function onWorksheetChanged(eventArgs) {
await Excel.run(async (context) => {
const details = eventArgs.details;
const address = eventArgs.address;
// Print the before and after types and values to the console.
console.log(`Change at ${address}: was ${details.valueBefore}(${details.valueTypeBefore}),`
+ ` now is ${details.valueAfter}(${details.valueTypeAfter})`);
await context.sync();
});
}
source
Gets the source of the event. See Excel.EventSource for details.
source: Excel.EventSource | "Local" | "Remote";Property Value
Excel.EventSource | "Local" | "Remote"
Remarks
triggerSource
Represents the trigger source of the event. For example, identifies whether this local add-in triggers the event.
triggerSource: Excel.EventTriggerSource | "Unknown" | "ThisLocalAddin";Property Value
Excel.EventTriggerSource | "Unknown" | "ThisLocalAddin"
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-worksheet.yaml
async function onChange(event: Excel.WorksheetChangedEventArgs) {
// This function is an event handler that returns the address, trigger source,
// and insert or delete shift directions of the change.
await Excel.run(async (context) => {
// Return the address where change occurred.
console.log(`Handler for worksheet onChanged event has been triggered.`);
console.log(` Data changed address: ` + event.address);
// Return the source of the event that triggered the change.
console.log(` Data change trigger source: ` + event.triggerSource);
// Note：insertShiftDirection and deleteShiftDirection are exclusive and both enums can't have a value at the same time.
// If one has a value, then the other will return undefined.
// If the insert shift direction is defined, return it.
if (event.changeDirectionState.insertShiftDirection) {
console.log(` Cells inserted shift direction: ` + event.changeDirectionState.insertShiftDirection);
}
// If the delete shift direction is defined, return it.
if (event.changeDirectionState.deleteShiftDirection) {
console.log(` Cells deleted shift direction: ` + event.changeDirectionState.deleteShiftDirection);
}
});
}
type
Gets the type of the event. See Excel.EventType for details.
type: "WorksheetChanged";Property Value
"WorksheetChanged"
Remarks
worksheetId
Gets the ID of the worksheet in which the data changed.
worksheetId: string;Property Value
string
Remarks
Method Details
getRange(ctx)
Gets the range that represents the changed area of a specific worksheet.
getRange(ctx: Excel.RequestContext): Excel.Range;Parameters
Returns
getRangeOrNullObject(ctx)
Gets the range that represents the changed area of a specific worksheet. It might return null object.
getRangeOrNullObject(ctx: Excel.RequestContext): Excel.Range;Parameters
Returns
Office Add-ins
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for