イベントに関するサンプルコード

SpreadJS は、ユーザー操作、データの変更、構造の変更、および高度なワークブック操作に対応するための包括的なイベントシステムを提供します。

すべてのイベントは GC.Spread.Sheets.Events クラスで定義されており、操作のスコープに応じて、Workbook または Worksheet にバインドできます。

このページでは、SpreadJS 全体で使用されるイベントモデル、バインドの仕組み、ライフサイクルパターン、および使用時の原則について説明します。

イベントのスコープ

SpreadJS のイベントは、イベントを発生させるオブジェクトに応じてスコープが決まります。

ワークブックレベルのイベント

ワークブックイベントは、ワークブック全体に影響する操作によってトリガーされます。たとえば、次のような操作があります。

アクティブシートの変更
クリップボード操作
テーブル構造の更新
コラボレーションワークフロー
計算の進行状況
権限の変更

これらのイベントは、Workbook インスタンスにバインドする必要があります。

ワークシートレベルのイベント

ワークシートイベントは、特定のシート内の操作によってトリガーされます。たとえば、次のような操作があります。

セル操作と選択
編集ライフサイクル
値および範囲の変更
行および列の操作
フィルタリングとソート
シェイプ、画像、フローティングオブジェクト、およびフォームコントロールの更新
ピボットテーブルおよび高度な機能の操作

これらのイベントは、Worksheet インスタンスにバインドする必要があります。

適切なスコープでイベントをバインドすると、予測可能な動作を確保し、不要なハンドラーを避けることができます。

イベントのバインドとバインド解除

イベントハンドラーを登録するには bind メソッドを使用し、解除するには unbind または unbindAll を使用します。

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);
});

各ハンドラーは、次の引数を受け取ります。

sender — イベントを発生させたオブジェクト（Workbook または Worksheet）
args — コンテキスト情報を含む、イベント固有の引数オブジェクト

ハンドラーを削除するには、次のようにします。

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

イベント引数モデル

引数プロパティはイベントの種類によって異なりますが、多くのイベントでは一貫したパターンが使用されます。

位置コンテキスト — row, col, sheet, sheetName
範囲コンテキスト — cellRange, changedCells
状態インジケーター — action, isUndo
制御フラグ — cancel

イベント固有の引数の詳細については、必ず API リファレンスを参照してください。

イベントライフサイクルパターン

多くの SpreadJS イベントでは、一貫したライフサイクルの命名パターンが使用されます。これらのパターンを理解すると、操作をどのタイミングでインターセプトするか、または操作に応答するかを判断しやすくなります。

1. Changing → Changed

構造または状態の変更に使用されます。

Changing — 操作が適用される前にトリガーされます。多くの場合、キャンセルできます。
Changed — 操作が完了した後にトリガーされます。

パターン例:

SheetChanging → SheetChanged
ColumnWidthChanging → ColumnWidthChanged

代表的なシナリオには、次のものがあります。

シートの挿入、削除、名前変更、または移動
行または列のプロパティの更新
フィルタリングおよびソート操作
テーブルおよび範囲の変更

Changing イベントは、検証や抑止に使用します。

Changed イベントは、操作後の処理や同期に使用します。

2. Starting → Ending → Ended

操作および編集ワークフローに使用されます。

Starting — 処理が開始される前
Ending — 完了直前（多くの場合、キャンセルできます）
Ended — 完了後

パターン例:

EditStarting
EditEnding
EditEnded

使用方法:

Starting で状態を初期化する
Ending で検証またはキャンセルする
Ended で確定した結果を処理する

キャンセル可能なイベント

一部のイベントでは、次のように設定することで既定の動作を抑止できます。

args.cancel = true;

キャンセル可能なイベントは通常、Changing または Ending の段階で発生します。

たとえば、次のような処理に使用できます。

編集モードの終了を防止する
シートの切り替えを防止する
貼り付け操作を防止する
列のサイズ変更を防止する

キャンセルは、Changing や Ending など、適切な事前アクション段階で行う必要があります。

Changed や Ended などの事後アクションイベントではキャンセルできません。

キャンセル可能なイベントは通常、次の目的で使用されます。

シートの切り替えを防止する
無効な編集をブロックする
サイズ変更操作を制限する
貼り付けアクションをインターセプトする
ビジネスルールを適用する

イベントカテゴリ

SpreadJS のイベントシステムは、次のような複数の機能領域に対応しています。

セル操作と選択
編集ライフサイクル
データおよび構造の変更
フィルタリング、ソート、グループ化、およびテーブル
シートおよびワークブックのライフサイクル
クリップボード連携
シェイプ、画像、フローティングオブジェクト、およびフォームコントロール
ピボットテーブル、レポートシート、およびテーブルシートの操作
計算およびコラボレーションワークフロー
権限および表示関連の操作

この構造により、開発者はユーザーアクションとシステム動作を細かく制御しながら、SpreadJS を複雑なアプリケーションロジックに統合できます。

詳細なイベント定義とパラメータ仕様については、API リファレンスの GC.Spread.Sheets.Events を参照してください。

使用ガイドライン

イベントロジックを実装する際は、次の点に注意してください。

正しいスコープ（Workbook または Worksheet）でイベントをバインドします。
事前アクションイベントを検証とキャンセルに使用します。
事後アクションイベントをログ記録と同期に使用します。
選択やスクロールなど、頻繁にトリガーされるイベント内では負荷の高い処理を避けます。
意図しない動作を防ぐため、シートを破棄または再作成する際にはハンドラーを削除します。

以下の各トピックでは、イベントの処理に関するさまざまなサンプルコードを示します。