Excel.WorksheetChangedEventArgs interface

Provides information about the worksheet that raised the changed event.

Remarks

[ API set: ExcelApi 1.7 ]

Properties

address

Gets the range address that represents the changed area of a specific worksheet.

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.

changeType

Gets the change type that represents how the changed event is triggered. See Excel.DataChangeType for details.

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 Excel.EventSource for details.

triggerSource

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 Excel.EventType for details.

worksheetId

Gets the ID of the worksheet in which the data changed.

Methods

getRange(ctx)

Gets the range that represents the changed area of a specific worksheet.

[ API set: ExcelApi 1.8 ]

getRangeOrNullObject(ctx)

Gets the range that represents the changed area of a specific worksheet. It might return null object.

[ API set: ExcelApi 1.8 ]

Property Details

address

Gets the range address that represents the changed area of a specific worksheet.

address: string;

Property Value

string

Remarks

[ API set: ExcelApi 1.7 ]

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

[ API set: ExcelApi 1.14 ]

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

[ API set: ExcelApi 1.7 ]

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

[ API set: ExcelApi 1.9 ]

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

[ API set: ExcelApi 1.7 ]

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

[ API set: ExcelApi 1.14 ]

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

[ API set: ExcelApi 1.7 ]

worksheetId

Gets the ID of the worksheet in which the data changed.

worksheetId: string;

Property Value

string

Remarks

[ API set: ExcelApi 1.7 ]

Method Details

getRange(ctx)

Gets the range that represents the changed area of a specific worksheet.

[ API set: ExcelApi 1.8 ]

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.

[ API set: ExcelApi 1.8 ]

getRangeOrNullObject(ctx: Excel.RequestContext): Excel.Range;

Parameters

Returns