Excel JavaScript API を使用してイベントを操作する

  • [アーティクル]

この記事では、Excel のイベント操作に関連する重要な概念について説明します。また、Excel JavaScript API を使用したイベント ハンドラーの登録、イベントの処理、およびイベント ハンドラーの削除の方法を示すコード例も提供します。

Excel のイベント

Excel ブックで特定の種類の変更が発生するたびに、イベント通知がトリガーされます。 Excel JavaScript API を使用すると、イベント ハンドラーを登録できます。このハンドラーによって、特定のイベントが発生したときに、アドインで目的の関数を自動的に実行できるようになります。 現時点でサポートされているイベントは次のとおりです。

イベント 説明 サポートされているオブジェクト
onActivated オブジェクトがアクティブ化されたときに発生します。 Chart、ChartCollection、Shape、Worksheet、WorksheetCollection
onActivated ブックがアクティブになると発生します。 Workbook
onAdded オブジェクトがコレクションに追加されたときに発生します。 ChartCollection、 CommentCollection、 TableCollection、 WorksheetCollection
onAutoSaveSettingChanged ブックで autoSave の設定が変更されると発生します。 Workbook
onCalculated ワークシートの計算が完了したとき (あるいはコレクションのすべてのワークシートが完了したとき) に発生します。 Worksheet、WorksheetCollection
onChanged 個々のセルまたはコメントのデータが変更されたときに発生します。 CommentCollection、 Table、 TableCollection、 Worksheet、 WorksheetCollection
onColumnSorted 1 つ以上の列を並べ替えたときに発生します。 これは、左から右に並べ替えを実行したときに発生します。 Worksheet、WorksheetCollection
onDataChanged バインド内でデータまたは書式設定が変更されるときに発生します。 Binding
onDeactivated オブジェクトが非アクティブ化されたときに発生します。 Chart、ChartCollection、Shape、Worksheet、WorksheetCollection
onDeleted オブジェクトがコレクションから削除されたときに発生します。 ChartCollection、 CommentCollection、 TableCollection、 WorksheetCollection
onFormatChanged ワークシートで書式設定が変更されたときに発生します。 Worksheet、WorksheetCollection
onFormulaChanged 数式が変更されたときに発生します。 Worksheet、WorksheetCollection
onMoved ワークシートがブック内で移動されたときに発生します。 WorksheetCollection
onNameChanged ワークシート名が変更されたときに発生します。 Worksheet、WorksheetCollection
onProtectionChanged ワークシートの保護状態が変更されたときに発生します。 Worksheet、WorksheetCollection
onRowHiddenChanged 特定のワークシート上の行非表示状態が変更されたときに発生します。 Worksheet、WorksheetCollection
onRowSorted 1 つ以上の行を並べ替えたときに発生します。 これは、上から下に並べ替えを実行したときに発生します。 Worksheet、WorksheetCollection
onSelectionChanged アクティブなセルまたは選択範囲が変更されたときに発生します。 バインド、 テーブル、 ブック、 ワークシート、 WorksheetCollection
onSettingsChanged ドキュメント内の設定が変更されるときに発生します。 SettingCollection
onSingleClicked ワークシートで左クリック / タップされたアクションが発生したときに発生します。 Worksheet、WorksheetCollection
onVisibilityChanged ワークシートの表示設定が変更されたときに発生します。 Worksheet、WorksheetCollection

プレビューでのイベント

注:

次のイベントは現在、パブリック プレビューでのみ利用できます。 この機能を使用するには、 Office.js コンテンツ配信ネットワーク (CDN) の Office JavaScript API ライブラリのプレビュー バージョンを使用する必要があります。 TypeScript コンパイルおよび IntelliSense の 型定義ファイルは CDN で見つかり、DefinitelyTyped にあります。 これらの型は、npm install --save-dev @types/office-js-preview を使用してインストールできます。 今後予定されている API の詳細については、「Excel JavaScript API 要件セット」参照してください。

イベント 説明 サポートされているオブジェクト
onFiltered フィルターがオブジェクトに適用されたときに発生します。 Table、TableCollection、Worksheet、WorksheetCollection

イベント トリガー

Excel ブックのイベントは、次の事項でトリガーできます。

  • ブックを変更する Excel ユーザー インターフェイス (UI) からのユーザー操作
  • ブックを変更する Office アドイン (JavaScript) コード
  • ブックを変更する VBA アドイン (マクロ) コード

Excel の既定の動作に準拠する変更により、それに対応するブックのイベントがトリガーされます。

イベント ハンドラーのライフサイクル

アドインがイベント ハンドラーを登録すると、そのイベント ハンドラーが作成されます。 アドインがイベント ハンドラーを登録解除するか、アドインが更新、再読み込み、または閉じられると、イベント ハンドラーは破棄されます。 イベント ハンドラーは Excel ファイルの一部として保持されず、また Excel on the web のセッション間でも保持されません。

注意

イベントが登録されているオブジェクト (onChanged イベントが登録されているテーブルなど) が削除されると、イベント ハンドラーはトリガーされませんが、アドインまたは Excel セッションが更新または閉じるまではメモリで維持されます。

イベントと共同編集

共同編集機能により、複数のユーザーが連携して同じ Excel ブックを同時に編集できるようになります。 などonChanged、共同編集によってトリガーできるイベントの場合、対応する Event オブジェクトには、イベントが現在のユーザー () によってローカルにトリガーされたか、リモート共同認証 () によってトリガーされたかをevent.source = Localevent.source = Remote示すソース プロパティが含まれます。

イベント ハンドラーの登録

次のコード例では、ワークシートの onChanged イベントに対応するイベント ハンドラーを Sample という名前で登録します。 このコードでは、そのワークシートでデータが変更されたときに、handleChange 関数を実行するように指定しています。

await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getItem("Sample");
    worksheet.onChanged.add(handleChange);

    await context.sync();
    console.log("Event handler successfully registered for onChanged event in the worksheet.");
}).catch(errorHandlerFunction);

イベントの処理

前の例で示したように、イベント ハンドラーの登録時には、特定のイベントが発生したときに実行する関数を指定します。 その関数は、目的のシナリオに必要なアクションを実行するように設計できます。 次のコード例は、イベントに関する情報を単にコンソールに出力するイベント ハンドラー関数を示しています。

async function handleChange(event) {
    await Excel.run(async (context) => {
        await context.sync();        
        console.log("Change type of event: " + event.changeType);
        console.log("Address of event: " + event.address);
        console.log("Source of event: " + event.source);       
    }).catch(errorHandlerFunction);
}

イベント ハンドラーを削除する

次のコード例では、ワークシートの onSelectionChanged イベントに対応するイベント ハンドラーを Sample という名前で登録して、そのイベントの発生時に実行される handleSelectionChange 関数を定義しています。 また、そのイベント ハンドラーを削除するために、後から呼び出すことができる remove() 関数も定義しています。 イベント ハンドラーの RequestContext 作成に使用する が、それを削除するために必要であることに注意してください。

let eventResult;

async function run() {
  await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getItem("Sample");
    eventResult = worksheet.onSelectionChanged.add(handleSelectionChange);

    await context.sync();
    console.log("Event handler successfully registered for onSelectionChanged event in the worksheet.");
  });
}

async function handleSelectionChange(event) {
  await Excel.run(async (context) => {
    await context.sync();
    console.log("Address of current selection: " + event.address);
  });
}

async function remove() {
  await Excel.run(eventResult.context, async (context) => {
    eventResult.remove();
    await context.sync();
    
    eventResult = null;
    console.log("Event handler successfully removed.");
  });
}

イベントの有効化と無効化

イベントを無効にすると、アドインのパフォーマンスが向上する可能性があります。 たとえば、アプリがイベントを受信する必要がないことや、複数エンティティの一括編集を実行中にイベントを無視できるすることがあります。

イベントはランタイム レベルで有効または無効にできます。 enableEvents プロパティは、イベントが発生したかどうかと、イベント ハンドラーがアクティブになったかどうかを判別します。

次のコード サンプルは、イベントのオンとオフを切り替える方法を示しています。

await Excel.run(async (context) => {
    context.runtime.load("enableEvents");
    await context.sync();

    let eventBoolean = !context.runtime.enableEvents;
    context.runtime.enableEvents = eventBoolean;
    if (eventBoolean) {
        console.log("Events are currently on.");
    } else {
        console.log("Events are currently off.");
    }
    
    await context.sync();
});

関連項目