増分計算

SpreadJS は、Workbook クラスの incrementalCalculation プロパティを true に設定することで、実行中に計算全体をセグメントに分割する増分計算をサポートしています。これにより、計算タスクが膨大な場合でも、ユーザーの操作に応答できるようになります。

セルを増分的に計算し、UI イベントに応答することができます。これにより、ブックに多数の数式が含まれている場合に UI がフリーズするのを防ぐことができます。計算が保留中のセルがあるときにセルが更新されると、更新されたセルとその依存セルが計算タスクに追加されます。ただし、行／列またはシートを挿入または削除し、次の計算で調整された数式が使用される場合、保留中の計算は破棄されます。

incrementalCalculation プロパティを true に設定すると、CalculationProgress イベントを使用して進行状況を追跡できます。

次のサンプルコードは、CalculationProgress イベントで進行状況を追跡する方法を示しています。

// この例では、CalculationProgress イベントを使用して計算の進行状況をログに記録します。
spread.options.incrementalCalculation = true;
spread.bind(GC.Spread.Sheets.Events.CalculationProgress, function (e, info) { 
    var msg = "Calculate "; 
    if (info.pendingCells === 0) { 
        msg += "finished"; 
    } else if (info.iterate >= 0) { 
        msg += info.pendingCells + " cells in iterative calculation round " + info.iterate; 
    } else { 
        msg += (info.totalCells - info.pendingCells) + "/" + info.totalCells + "cells"; 
    } 
    console.log(msg); 
}); 

ステータスバー項目の追加

incrementalCalculation プロパティが true に設定されている場合、計算の進行状況を示すために、ステータス バーに増分計算も表示されます。

次のコード サンプルは、SpreadJSをステータス バーに連結して、計算の進行状況を自動的に表示する方法を示しています。

// ステータス バーを初期化し、SpreadJSに連結します。
var statusBar = new GC.Spread.Sheets.StatusBar.StatusBar(document.getElementById('statusBar'));
statusBar.bind(spread);

非循環参照セルの場合: 計算の進行状況は、次の画像に示すようにパーセンテージ形式で表示されます。

循環参照セルの場合: iterativeCalculation を true に設定することで反復計算が実装され、次の GIF画像 に示すように、反復ラウンドで計算の進行状況が表示されます。

次のサンプルコードは、循環参照の iterativeCalculation を設定する方法を示しています。

// 反復計算を有効にします。
spread.options.iterativeCalculation = true;
spread.options.iterativeCalculationMaximumIterations = 24;

WebWorker（calcWorker プラグイン）で増分計算を実行する

calcWorker プラグインは、スプレッドシートの計算処理を WebWorker にオフロードし、負荷の高い再計算中もメインスレッドの応答性を維持します。

このプラグインを有効にすると、大規模データや数式が多いブックを操作する際に、UI が停止する状況を防ぎ、パフォーマンスを向上できます。

使用方法:

方法 1 – スクリプトファイルを使用する

1. プラグインを HTML ファイルに読み込みます。

2. incrementalCalculation オプションを true に設定します。

<script src="gc.spread.sheets.all.xx.x.x.min.js"></script>
<script src="plugins/gc.spread.sheets.calcworker.xx.x.x.min.js"></script>
<script src="resources/ja/gc.spread.sheets.resources.ja.xx.x.x.min.js"></script>
<script>
window.onload = function () {
    window.spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"));
    spread.options.incrementalCalculation = true;
};
</script>

方法 2 – NPM パッケージを使用する

1. プラグインをインストールする:

npm install @mescius/spread-sheets-calc-worker

2. コード内でインポートして有効化する:

import '@mescius/spread-sheets-calc-worker';
spread.options.incrementalCalculation = true;

確認方法

有効化に成功すると、計算タスクがブラウザのバックグラウンドスレッドで非同期に実行されます。

ブラウザの DevTools で calcWorker.js のスレッドを確認すると、Worker が動作していることを確認できます。

機能

• incrementalCalculation を有効にすると、SpreadJS は数式の再計算をメインスレッドではなく Web Worker 内で実行します。

  • これにより、ユーザー操作中もセルのインクリメンタル更新が途切れずに進みます。

  • 計算は非同期で実行され、完了後に結果がメインスレッドへ返されます。

• incrementalCalculation が無効の場合、すべての計算をメインスレッドで実行します。

動作と制限事項

• 計算の優先度

  calcOnDemand は incrementalCalculation よりも優先度が低いです。

  incrementalCalculation を有効にすると、calcOnDemand オプションは自動的に無効になります。

• 計算の一時停止

  すべてのワーカーによる計算処理を一時停止するには spread.suspendCalcService() を使用します。

• 手動計算モード

  計算モードが「manual」の場合、CalcWorker は自動再計算を実行しません。

• データ転送の制限

  ワーカーへ渡す値はシリアル化できる必要があります。関数や複雑なオブジェクト（例: クロージャ）はセル値として使用できません。

sheet.setValue(1,1,{a:1,f:()=>{return 2;}}); // worker モードでは使用できません

• 計算結果に依存する API

  並べ替え、エクスポート、集計など、最新の計算結果に依存する処理を実行する前に、await waitForAllCalculations() を呼び出して、すべての Worker タスクが完了していることを確認してください。

sheet.suspendPaint();
for (let i = 0; i < 100; i++) {
    sheet.setFormula(i, 0, `=${100 - i}`);
}
sheet.resumePaint();
await spread.waitForAllCalculations();
sheet.sortRange(0, 0, 100, 1, true, [{ index: 0, ascending: true }]);

• カスタム関数

  カスタム関数はメインスレッドで実行します。CalcWorker 内の数式でカスタム関数が呼び出される場合、評価処理を UI スレッドに委譲し、その結果を CalcWorker に返します。

• 条件付き書式と可視化要素

  条件付き書式、シェイプ、チャートは常にメインスレッドで処理され、CalcWorker の最新結果を使用して更新します。

例: パフォーマンス比較

次の例では、calcWorker プラグインが負荷の高い再計算処理中の応答性をどのように改善するかを示します。

このブックには 10,000 行 のデータが含まれ、RAND() 関数による乱数生成や、確率、標準偏差などの統計計算を実行します。

再計算（基礎となる数式の編集や乱数入力の変更など）を実行すると、スプレッドシートは多数の依存数式の更新とチャートの更新をトリガーします。