Excel JavaScript API を使用してイベントを操作するWork with Events using the Excel JavaScript API

この記事では、Excel のイベント操作に関連する重要な概念について説明します。また、Excel JavaScript API を使用したイベント ハンドラーの登録、イベントの処理、およびイベント ハンドラーの削除の方法を示すコード例も提供します。This article describes important concepts related to working with events in Excel and provides code samples that show how to register event handlers, handle events, and remove event handlers using the Excel JavaScript API.

Excel のイベントEvents in Excel

Excel ブックで特定の種類の変更が発生するたびに、イベント通知がトリガーされます。 Excel JavaScript API を使用すると、イベント ハンドラーを登録できます。このハンドラーによって、特定のイベントが発生したときに、アドインで目的の関数を自動的に実行できるようになります。 現時点でサポートされているイベントは次のとおりです。Each time certain types of changes occur in an Excel workbook, an event notification fires. By using the Excel JavaScript API, you can register event handlers that allow your add-in to automatically run a designated function when a specific event occurs. The following events are currently supported.

イベントEvent 説明Description サポートされているオブジェクトSupported objects
onActivated オブジェクトがアクティブ化されたときに発生します。Occurs when an object is activated. ChartChartCollectionShapeWorksheetWorksheetCollectionChart, ChartCollection, Shape, Worksheet, WorksheetCollection
onAdded オブジェクトがコレクションに追加されたときに発生します。Occurs when an object is added to the collection. ChartCollectionTableCollectionWorksheetCollectionChartCollection, TableCollection, WorksheetCollection
onAutoSaveSettingChanged ブックで autoSave の設定が変更されると発生します。Occurs when the autoSave setting is changed on the workbook. WorkbookWorkbook
onCalculated ワークシートの計算が完了したとき (あるいはコレクションのすべてのワークシートが完了したとき) に発生します。Occurs when a worksheet has finished calculation (or all the worksheets of the collection have finished). WorksheetWorksheetCollectionWorksheet, WorksheetCollection
onChanged セル内のデータが変更されたときに発生します。Occurs when data within cells is changed. TableTableCollectionWorksheetWorksheetCollectionTable, TableCollection, Worksheet, WorksheetCollection
onColumnSorted 1 つ以上の列を並べ替えたときに発生します。Occurs when one or more columns have been sorted. これは、左から右に並べ替えを実行したときに発生します。This happens as the result of a left-to-right sort operation. WorksheetWorksheetCollectionWorksheet, WorksheetCollection
onDataChanged バインド内でデータまたは書式設定が変更されるときに発生します。Occurs when data or formatting within the binding is changed. BindingBinding
onDeactivated オブジェクトが非アクティブ化されたときに発生します。Occurs when an object is deactivated. ChartChartCollectionShapeWorksheetWorksheetCollectionChart, ChartCollection, Shape, Worksheet, WorksheetCollection
onDeleted オブジェクトがコレクションから削除されたときに発生します。Occurs when an object is deleted from the collection. ChartCollectionTableCollectionWorksheetCollectionChartCollection, TableCollection, WorksheetCollection
onFormatChanged ワークシートで書式設定が変更されたときに発生します。Occurs when the format is changed on a worksheet. WorksheetWorksheetCollectionWorksheet, WorksheetCollection
onRowSorted 1 つ以上の行を並べ替えたときに発生します。Occurs when one or more rows have been sorted. これは、上から下に並べ替えを実行したときに発生します。This happens as the result of a top-to-bottom sort operation. WorksheetWorksheetCollectionWorksheet, WorksheetCollection
onSelectionChanged アクティブなセルまたは選択範囲が変更されたときに発生します。Occurs when the active cell or selected range is changed. BindingTableWorksheetWorksheetCollectionBinding, Table, Worksheet, WorksheetCollection
onSettingsChanged ドキュメント内の設定が変更されるときに発生します。Occurs when the Settings in the document are changed. SettingCollectionSettingCollection
onSingleClicked ワークシートで左クリック / タップされたアクションが発生したときに発生します。Occurs when left-clicked/tapped action occurs in the worksheet. WorksheetWorksheetCollectionWorksheet, WorksheetCollection

警告

onSelectionChanged は現在不安定です。onSelectionChanged is currently unstable. onSelectionChanged を確実に使用するための回避策があります。There is a workaround to reliably use onSelectionChanged. HTML ホーム ページの <head> セクションに次のコードを追加します。Add the following code to the <head> section of your HTML home page:

<script> MutationObserver=null; </script>

この問題に関する説明は、「office-js GitHub リポジトリ」にあります。A full discussion of the issue can be found on the office-js GitHub repo.

プレビューでのイベントEvents in preview

注意

次のイベントは現在、パブリック プレビューでのみ利用できます。The following events are currently available only in public preview. この機能を使用するには、office JavaScript ライブラリのプレビューバージョンをoffice の JS CDNから使用する必要があります。To use this feature, you must use the preview version of the Office JavaScript library from the Office.js CDN. TypeScript のコンパイルおよび IntelliSense 用の型定義ファイルは、CDN と、定義された定義ファイルにあります。The type definition file for TypeScript compilation and IntelliSense is found at the CDN and DefinitelyTyped. これらの種類は、でnpm install --save-dev @types/office-js-previewインストールできます。You can install these types with npm install --save-dev @types/office-js-preview. 今後予定されている API の詳細については、「Excel JavaScript API 要件セット」参照してください。For more information on our upcoming APIs, please visit Excel JavaScript API requirement sets.

イベントEvent 説明Description サポートされているオブジェクトSupported objects
onFiltered フィルターがオブジェクトに適用されたときに発生します。Occurs when a filter is applied to an object. TableTableCollectionWorksheetWorksheetCollectionTable, TableCollection, Worksheet, WorksheetCollection
onRowHiddenChanged 特定のワークシート上の行非表示状態が変更されたときに発生します。Occurs when the row-hidden state changes on a specific worksheet. WorksheetWorksheetCollectionWorksheet, WorksheetCollection

イベント トリガーEvent triggers

Excel ブックのイベントは、次の事項でトリガーできます。Events within an Excel workbook can be triggered by:

  • ブックを変更する Excel ユーザー インターフェイス (UI) からのユーザー操作User interaction via the Excel user interface (UI) that changes the workbook
  • ブックを変更する Office アドイン (JavaScript) コードOffice Add-in (JavaScript) code that changes the workbook
  • ブックを変更する VBA アドイン (マクロ) コードVBA add-in (macro) code that changes the workbook

Excel の既定の動作に準拠する変更により、それに対応するブックのイベントがトリガーされます。Any change that complies with default behavior of Excel will trigger the corresponding event(s) in a workbook.

イベント ハンドラーのライフサイクルLifecycle of an event handler

アドインがイベント ハンドラーを登録すると、そのイベント ハンドラーが作成されます。An event handler is created when an add-in registers the event handler. アドインがイベント ハンドラーを登録解除するか、アドインが更新、再読み込み、または閉じられると、イベント ハンドラーは破棄されます。It is destroyed when the add-in unregisters the event handler or when the add-in is refreshed, reloaded, or closed. イベント ハンドラーは Excel ファイルの一部として保持されず、また Excel on the web のセッション間でも保持されません。Event handlers do not persist as part of the Excel file, or across sessions with Excel on the web.

注意事項

イベントが登録されているオブジェクト (onChanged イベントが登録されているテーブルなど) が削除されると、イベント ハンドラーはトリガーされませんが、アドインまたは Excel セッションが更新または閉じるまではメモリで維持されます。When an object to which events are registered is deleted (e.g., a table with an onChanged event registered), the event handler no longer triggers but remains in memory until the add-in or Excel session refreshes or closes.

イベントと共同編集Events and coauthoring

共同編集機能により、複数のユーザーが連携して同じ Excel ブックを同時に編集できるようになります。共同編集でトリガーできるイベント (onChanged など) の場合、対応する Event オブジェクトには source プロパティが含まれるようになります。このプロパティは、イベントが現在のユーザーによってローカルにトリガーされた (event.source = Local) ものか、リモートの共同作成者によってトリガーされた (event.source = Remote) ものかを示します。With coauthoring, multiple people can work together and edit the same Excel workbook simultaneously. For events that can be triggered by a coauthor, such as onChanged, the corresponding Event object will contain a source property that indicates whether the event was triggered locally by the current user (event.source = Local) or was triggered by the remote coauthor (event.source = Remote).

イベント ハンドラーの登録Register an event handler

次のコード例では、ワークシートの onChanged イベントに対応するイベント ハンドラーを Sample という名前で登録します。 このコードでは、そのワークシートでデータが変更されたときに、handleDataChange 関数を実行するように指定しています。The following code sample registers an event handler for the onChanged event in the worksheet named Sample. The code specifies that when data changes in that worksheet, the handleDataChange function should run.

Excel.run(function (context) {
    var worksheet = context.workbook.worksheets.getItem("Sample");
    worksheet.onChanged.add(handleChange);

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

イベントの処理Handle an event

前の例で示したように、イベント ハンドラーの登録時には、特定のイベントが発生したときに実行する関数を指定します。 その関数は、目的のシナリオに必要なアクションを実行するように設計できます。 次のコード例は、イベントに関する情報を単にコンソールに出力するイベント ハンドラー関数を示しています。As shown in the previous example, when you register an event handler, you indicate the function that should run when the specified event occurs. You can design that function to perform whatever actions your scenario requires. The following code sample shows an event handler function that simply writes information about the event to the console.

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

イベント ハンドラーを削除するRemove an event handler

次のコード例では、ワークシートの onSelectionChanged イベントに対応するイベント ハンドラーを Sample という名前で登録して、そのイベントの発生時に実行される handleSelectionChange 関数を定義しています。 また、そのイベント ハンドラーを削除するために、後から呼び出すことができる remove() 関数も定義しています。The following code sample registers an event handler for the onSelectionChanged event in the worksheet named Sample and defines the handleSelectionChange function that will run when the event occurs. It also defines the remove() function that can subsequently be called to remove that event handler.

var eventResult;

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

    return context.sync()
        .then(function () {
            console.log("Event handler successfully registered for onSelectionChanged event in the worksheet.");
        });
}).catch(errorHandlerFunction);

function handleSelectionChange(event)
{
    return Excel.run(function(context){
        return context.sync()
            .then(function() {
                console.log("Address of current selection: " + event.address);
            });
    }).catch(errorHandlerFunction);
}

function remove() {
    return Excel.run(eventResult.context, function (context) {
        eventResult.remove();

        return context.sync()
            .then(function() {
                eventResult = null;
                console.log("Event handler successfully removed.");
            });
    }).catch(errorHandlerFunction);
}

イベントの有効化と無効化Enable and disable events

イベントを無効にすると、アドインのパフォーマンスが向上する可能性があります。The performance of an add-in may be improved by disabling events. たとえば、アプリがイベントを受信する必要がないことや、複数エンティティの一括編集を実行中にイベントを無視できるすることがあります。For example, your app might never need to receive events, or it could ignore events while performing batch-edits of multiple entities.

イベントはランタイム レベルで有効または無効にできます。Events are enabled and disabled at the runtime level. enableEvents プロパティは、イベントが発生したかどうかと、イベント ハンドラーがアクティブになったかどうかを判別します。The enableEvents property determines if events are fired and their handlers are activated.

次のコード サンプルは、イベントのオンとオフを切り替える方法を示しています。The following code sample shows how to toggle events on and off.

Excel.run(function (context) {
    context.runtime.load("enableEvents");
    return context.sync()
        .then(function () {
            var eventBoolean = !context.runtime.enableEvents;
            context.runtime.enableEvents = eventBoolean;
            if (eventBoolean) {
                console.log("Events are currently on.");
            } else {
                console.log("Events are currently off.");
            }
        }).then(context.sync);
}).catch(errorHandlerFunction);

関連項目See also