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

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

Excel のイベント

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

プレビューでのイベント

イベント トリガー

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

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

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

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

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

イベントと共同編集

共同編集機能により、複数のユーザーが連携して同じ Excel ブックを同時に編集できるようになります。 onChangedなど、共同編集者によってトリガーできるイベントの場合、対応する Event オブジェクトには、イベントが現在のユーザー (event.source == Local) によってローカルでトリガーされたか、リモート共同編集 (event.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() {
  // The `RequestContext` used to create the event handler is needed to remove it.
  // In this example, `eventContext` is being used to keep track of that context.
  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();
});

関連項目

• Office アドインの Excel JavaScript オブジェクト モデル