[]
DEMOS DOC DESIGNER API
DOWNLOAD
(Showing Draft Content)

Events

SpreadJS provides a comprehensive event system that allows developers to respond to user interactions, data modifications, structural changes, and advanced workbook operations.

All events are defined in the GC.Spread.Sheets.Events class and can be bound to either a Workbook or a Worksheet, depending on the scope of the operation.

This page introduces the event model, binding mechanism, lifecycle patterns, and usage principles used throughout SpreadJS.

Event Scope

Events in SpreadJS are scoped according to the object that raises them.

Workbook-Level Events

Workbook events are triggered by operations that affect the workbook as a whole, such as:

  • Active sheet changes

  • Clipboard operations

  • Table structural updates

  • Collaboration workflows

  • Calculation progress

  • Permission changes

These events must be bound to the Workbook instance.

Worksheet-Level Events

Worksheet events are triggered by interactions within a specific sheet, including:

  • Cell interaction and selection

  • Editing lifecycle

  • Value and range changes

  • Row and column operations

  • Filtering and sorting

  • Shape, picture, floating object, and form control updates

  • PivotTable and advanced feature operations

These events must be bound to a Worksheet instance.

Binding events at the correct scope ensures predictable behavior and avoids unnecessary handlers.

Binding and Unbinding Events

Use the bind method to register an event handler and unbind (or unbindAll) to remove it.

const spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"));
const sheet = spread.getActiveSheet();
sheet.bind(GC.Spread.Sheets.Events.CellClick, function (sender, args) {
    console.log("Row:", args.row, "Column:", args.col);
});

Each handler receives:

  • sender – The object that raised the event (Workbook or Worksheet)

  • args – An event-specific argument object containing contextual information

To remove a handler:

sheet.unbind(GC.Spread.Sheets.Events.CellClick, handler);
sheet.unbindAll(GC.Spread.Sheets.Events.CellClick);

Event Argument Model

While argument properties vary by event type, many follow consistent patterns:

  • Location context — row, col, sheet, sheetName

  • Range context — cellRange, changedCells

  • State indicators — action, isUndo

  • Control flag — cancel

Always refer to the API Reference for event-specific argument details.

Event Lifecycle Patterns

Many SpreadJS events follow consistent lifecycle naming patterns. Understanding these patterns helps you determine when to intercept or respond to an operation.

1. Changing → Changed

Used for structural or state changes.

  • Changing — Triggered before the operation is applied. Often cancelable.

  • Changed — Triggered after the operation completes.

Example pattern:

  • SheetChanging → SheetChanged

  • ColumnWidthChanging → ColumnWidthChanged

Typical scenarios include:

  • Sheet insertion, removal, renaming, or movement

  • Row or column property updates

  • Filtering and sorting operations

  • Table and range modifications

Use Changing events for validation and prevention.

Use Changed events for post-operation processing or synchronization.

2. Starting → Ending → Ended

Used for interaction and editing workflows.

  • Starting — Before the process begins

  • Ending — Just before completion (often cancelable)

  • Ended — After completion

Example pattern:

  • EditStarting

  • EditEnding

  • EditEnded

Use:

  • Starting to initialize state

  • Ending to validate or cancel

  • Ended to process committed results

Cancelable Events

Some events allow you to prevent the default behavior by setting:

args.cancel = true;

Cancelable events typically occur in the Changing or Ending stage.

For example:

  • Prevent leaving edit mode

  • Prevent sheet switching

  • Prevent paste operations

  • Prevent column resizing

Cancellation must occur during the appropriate pre-action stage (such as Changing or Ending).

Post-action events (such as Changed or Ended) cannot be canceled.

Cancelable events are typically used to:

  • Prevent sheet switching

  • Block invalid edits

  • Restrict resizing operations

  • Intercept paste actions

  • Enforce business rules

Event Categories

The SpreadJS event system spans multiple functional areas, including:

  • Cell interaction and selection

  • Editing lifecycle

  • Data and structural changes

  • Filtering, sorting, grouping, and tables

  • Sheet and workbook lifecycle

  • Clipboard integration

  • Shapes, pictures, floating objects, and form controls

  • PivotTable, ReportSheet, and TableSheet operations

  • Calculation and collaboration workflows

  • Permission and view-related operations

This structure allows developers to integrate SpreadJS into complex application logic while maintaining fine-grained control over user actions and system behavior.

Detailed event definitions and parameter specifications are available in the API Reference under: GC.Spread.Sheets.Events.

Usage Guidelines

When implementing event logic:

  • Bind events at the correct scope (Workbook vs Worksheet).

  • Use pre-action events for validation and cancellation.

  • Use post-action events for logging and synchronization.

  • Avoid heavy processing inside frequently triggered events (such as selection or scrolling).

  • Remove handlers when disposing or recreating sheets to prevent unintended behavior.

The following sections organize events by functional category and provide focused guidance and examples for common development scenarios.