ドキュメントを開くときにコードを実行するように構成する

ドキュメントを開いたらすぐにコードを読み込んで実行するように、Office 用アドインを構成できます。これは、イベントハンドラーの登録、作業ウィンドウ用データの事前読み込み、UI の同期、またはアドインが表示される前に表示される前にその他のタスクを実行する必要がある場合に役立ちます。

ヒント

この資料では、ドキュメントを開いたときにコードを実行するようにアドインがプログラムで自動的に構成できるようにする機能について説明します。この手法には ドキュメントスコープがあり、各ドキュメントに個別に適用する必要があります。この機能は、次の 3 つの同様の機能とは異なります。

アドインをマニフェストで構成し 、ドキュメントが 開かれたときにコードを実行することができます。この機能は、 Office アプリケーションスコープです。 Microsoft 365 テナントの管理ポータルで Microsoft 365 管理者がアドインをインストールすると、アドインがサポートするようにマニフェストで構成されている Office アプリケーションで開かれているすべての Office ドキュメントに対してアドインが起動され、コードが実行されます。詳細については、「イベントでアドインをアクティブ化する」を参照してください。特に OnDocumentOpened イベントに関する情報。
アドインは、ドキュメントが開いたときに自動的にアドインの作業ウィンドウを開くようにプログラムでドキュメントを構成できます。また、この機能は各ドキュメントに個別に適用する必要があります。詳細については、「ドキュメントを含む作業ウィンドウを自動的に開く」を参照してください。
アドインは、エンドユーザーがインストールした ときに 作業ウィンドウを開くようにマニフェストで構成できます。この機能のスコープは 1 つのドキュメント (アドインのインストール時に開かれているドキュメント) に限定されます。詳細については、「アドインのインストール時に作業ウィンドウを自動的に開く」を参照してください。

実行時にコードが呼び出すメソッドを使用して構成が実装されます。つまり、ユーザーが初めてドキュメントを開いたときにはアドインが実行されません。ドキュメントで初めてアドインを手動で開く必要があります。メソッドが実行された後、 Office.initialize、 Office.onReady、またはユーザーがそれを実行するコードパスを利用した場合。その後、ドキュメントを再度開くと、アドインがすぐに読み込まれ、 Office.initialize または Office.onReady メソッドでコードが実行されます。

注:

この記事では、Office アドインが共有ランタイムを使用するように構成されている必要があります。詳細については、「共有ランタイムを使用するように Office アドインを構成する」を参照してください。

重要

共有ランタイムは、一部の Office アプリケーションでのみサポートされています。詳細については、「共有ランタイム要件セット」を参照してください。

ドキュメントが開いたときに読み込まれるようにアドインを構成する

次のコードは、ドキュメントを開いたときに読み込まれて実行が開始されるようにアドインを構成します。

Office.addin.setStartupBehavior(Office.StartupBehavior.load);

注:

setStartupBehavior メソッドは非同期です。

スタートアップコードを Office.initialize または Office.onReady に配置します

ドキュメントを開いたときに読み込むように構成すると、アドインはすぐに実行されます。 Office.initialize イベントハンドラーが呼び出されます。スタートアップコードを Office.initialize または Office.onReady イベントハンドラーに配置します。

次の Excel アドインコードは、アクティブなワークシートの変更イベントに対するイベントハンドラーを登録する方法を示しています。ドキュメントを開いたときに読み込むようにアドインを構成すると、ドキュメントが開いたときにこのコードによってイベントハンドラーが登録されます。作業ウィンドウを開く前に変更イベントを処理できます。

// This is called as soon as the document opens.
// Put your startup code here.
Office.initialize = () => {
  // Add the event handler.
  Excel.run(async context => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.onChanged.add(onChange);

    await context.sync();
    console.log("A handler has been registered for the onChanged event.");
  });
};

/**
 * Handle the changed event from the worksheet.
 *
 * @param event The event information from Excel
 */
async function onChange(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);
  });
}

次の PowerPoint アドインコードは、PowerPoint ドキュメントから選択変更イベントのイベントハンドラーを登録する方法を示しています。ドキュメントを開いたときに読み込むようにアドインを構成すると、ドキュメントが開いたときにこのコードによってイベントハンドラーが登録されます。作業ウィンドウを開く前に変更イベントを処理できます。

// This is called as soon as the document opens.
// Put your startup code here.
Office.onReady(info => {
  if (info.host === Office.HostType.PowerPoint) {
    Office.context.document.addHandlerAsync(Office.EventType.DocumentSelectionChanged, onChange);
    console.log("A handler has been registered for the onChanged event.");
  }
});

/**
 * Handle the changed event from the PowerPoint document.
 *
 * @param event The event information from PowerPoint
 */
async function onChange(event) {
  console.log("Change type of event: " + event.type);
}

ドキュメントを開いたときに無読み込み動作になるようにアドインを構成する

"ドキュメントを開いたときに実行" 動作を無効にするシナリオが考えられるかもしれません。次のコードでは、ドキュメントを開いたときに起動しないようにアドインを構成できます。代わりに、ユーザーが何らかの方法で操作すると開始されます (リボンボタンを選択したり、作業ウィンドウを開いたりします)。メソッドがパラメーターとして Office.StartupBehavior.load を指定して現在のドキュメントで以前に呼び出されていない場合、このコードは効果がありません。

注:

アドインが Office.initialize または Office.onReady で Office.StartupBehavior.load をパラメーターとしてメソッドを呼び出すと、動作が再び有効になります。したがって、このシナリオでは、オフにすることは、次回文書を開くときにのみ適用されます。それ以降の すべての 開き方には適用されません。

Office.addin.setStartupBehavior(Office.StartupBehavior.none);

現在の読み込み動作を取得する

アドインが、現在のドキュメントを次回開いたときに自動的に起動するように構成されているかどうかを知る必要があるシナリオがあります。現在の起動動作を確認するには、次のメソッドを実行します。このメソッドは Office.StartupBehavior 値を返します。

let behavior = await Office.addin.getStartupBehavior();

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-02