Performance and Calculation

Large SJS.TABLE formulas may significantly increase recalculation time because multiple simulations are evaluated for each input combination.

SpreadJS provides calculation modes and progress events to help manage performance.

Calculation Modes

By default, SpreadJS recalculates all formulas automatically when dependent data changes.

For workbooks containing large data tables, you can adjust calculation behavior using CalculationMode.

spread.options.calculationMode = GC.Spread.Sheets.CalculationMode.partial;

To trigger recalculation manually:

spread.calculate();

Monitoring Calculation Progress

SpreadJS raises the CalculationProgress event to report recalculation progress.

Enabling Incremental Calculation (General Formulas)

For general formula recalculation, progress reporting is available when incremental calculation is enabled:

spread.options.incrementalCalculation = true;

When enabled, the CalculationProgress event reports:

• totalCells

• pendingCells

• iterate (for iterative calculation)

Progress Reporting for SJS.TABLE

SJS.TABLE has specialized progress reporting behavior.

Event Triggering

During SJS.TABLE evaluation, the CalculationProgress event is raised:

• Even if incrementalCalculation is not enabled

• Independently of general formula recalculation progress

When a workbook contains SJS.TABLE, the event is triggered as follows:

1. When SJS.TABLE is detected for evaluation, the event is raised with dataTableProgress: 0

2. During evaluation, the event continues to fire with dataTableProgress

representing the progress of the data table calculation.

Event Payload Behavior

While SJS.TABLE is being evaluated:

• The event payload includes dataTableProgress.

• Other progress fields such as totalCells, pendingCells, and iterate are not included.

dataTableProgress represents the completion ratio of the data table calculation.

Example

spread.bind(
  GC.Spread.Sheets.Events.CalculationProgress,
  function (e, info) {
    if (info.dataTableProgress !== undefined) {
      console.log(
        "Data Table: " +
        (info.dataTableProgress * 100).toFixed(0) + "%"
      );
      return;
    }

    if (info.pendingCells === 0) {
      console.log("Calculation finished");
    }
  }
);

This separation ensures that large SJS.TABLE simulations do not generate excessive general calculation completion notifications, while still providing clear progress feedback for data table evaluation.

Status Bar Indicator

During SJS.TABLE calculation, the built-in SpreadJS status bar automatically displays:

Data Table: x%

No configuration is required. This provides visual feedback that a data table calculation is in progress.