SheetXL - v1.0.2
    Preparing search index...

    Interface ChangeEvent

    What a change event announces: where the change landed and what wrote it.

    sheet.addListeners({
      onDataChange(_sheet, event) {
        if (!event.getCommit()) return; // recalculated, not written
        console.log(`${event.getCommit()!.getDescription()}: ${event.getRanges()?.toString() ?? 'the sheet'}`);
      }
    });
    interface ChangeEvent {
        getCommit(): ICommit | null;
        getKind(): ChangeEventKey;
        getPreviousCommit(): ICommit | null;
        getPreviousRanges(): ICellRanges | null;
        getRanges(): ICellRanges | null;
        getSheet(): IWorksheet;
        getShifts(): readonly IWorksheet.Shift[];
        isUndo(): boolean;
    }
    Index
    getCommit getKind getPreviousCommit getPreviousRanges getRanges getSheet getShifts isUndo

    • The commit that wrote the change, or null when it was not written: a calculation landing, the engine rewriting a formula's text, or a change announced outside a commit (a table's own style, a cache that has to repaint).

      Returns ICommit | null

      An undo or redo announces the commit it moved to. When one delivery covers several commits, this is the latest.

    • The commit the change moved from: for a write its parent, for an undo the commit undone. null for a derived change, or when there is none.

      Returns ICommit | null

    • The same ranges as they were at getPreviousCommit: what the change replaced.

      Returns ICellRanges | null

      Ranges on a detached copy of the sheet, built only when asked for: reading them costs nothing on the write path, and writing to them does not reach the workbook. null when there is no previous commit, when the store no longer keeps it, or when the change moved cells (an insert, a delete, a move): the addresses then name different cells before it. getShifts says how they moved.

      const replaced = event.getPreviousRanges()?.getCounts(); // what the write overwrote

    • The ranges that changed, or null when the extent is not known and the whole sheet should be treated as changed.

      Returns ICellRanges | null

      Addresses are as of the change. Read them in the listener; after a later insert or delete they may no longer name the same cells.

    • The inserts and deletes of cells the change made on this sheet, in the order they ran. Empty when it moved no cells.

      Returns readonly IWorksheet.Shift[]

      A move of cells is the insert and the delete it is made of. An undo reports the inverse of what it undid, last first: the undo of an insert is a delete.

      for (const shift of event.getShifts()) {
        console.log(`${shift.getKind()} ${shift.getAxis()}s: ${shift.getRanges()?.toString()}`);
      }

    • true when the change is an undo. A redo is not an undo: it announces the commit it restored, as the forward commit did.

      Returns boolean

    Settings
    Member Visibility

    On This Page
    Methods