Office アドインを初期化する

Office アドインには、次のような処理を行うスタートアップ ロジックがよくあります。

• ユーザーの Office のバージョンが、ご使用のコードが呼び出す Office API をすべてサポートしているかを確認します。

• 特定の名前を含むワークシートなど、特定の成果物の有無を確認します。

• Excel でユーザーにいくつかのセルを選択するプロンプトを表示し、選択した値で初期化されたグラフを挿入します。

• バインディングを確立します。

• Office ダイアログ API を使用して、アドインの設定の既定値をユーザーに確認します。

ただし、Office アドインは、ライブラリが読み込まれるまで Office JavaScript API を正常に呼び出すことはできません。 この記事では、コードでライブラリが読み込まれたことを確認する 2 つの方法について説明します。

• Office.onReady() を使用して初期化します。
• Office.initialize を使用して初期化します。

アドインの初期化時のイベントのシーケンスの詳細については、「DOM とランタイム環境を読み込む」を参照してください。

Office.onReady() を使用した初期化

Office.onReady() は、Office.js ライブラリが読み込まれているかどうかをチェックするときに、Promise オブジェクトを返す非同期関数です。 ライブラリが読み込まれるとき (に限り)、Office クライアント アプリケーションを Office.HostType 列挙値 (Excel、Word など)、およびプラットフォームを Office.PlatformType 列挙値 (PC、Mac、OfficeOnline など) で指定するオブジェクトとして Promise を解決します。 Office.onReady() を呼び出すときにライブラリが既に読み込まれている場合、Promise をすぐに解決します。

Office.onReady() を呼び出す方法の 1 つは、コールバック関数を渡すことです。 次に例を示します。

Office.onReady(function(info) {
    if (info.host === Office.HostType.Excel) {
        // Do Excel-specific initialization (for example, make add-in task pane's
        // appearance compatible with Excel "green").
    }
    if (info.platform === Office.PlatformType.PC) {
        // Make minor layout changes in the task pane.
    }
    console.log(`Office.js is now ready in ${info.host} on ${info.platform}`);
});

また、コールバックを渡す代わりに、then() メソッドを Office.onReady() の呼び出しにチェーン接続することもできます。 たとえば、次のコードで、ユーザーのバージョンの Excel が、アドインで呼び出す可能性があるすべての API をサポートしているかを確認します。

Office.onReady()
    .then(function() {
        if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
            console.log("Sorry, this add-in only works with newer versions of Excel.");
        }
    });

async と await キーワードを TypeScript で使用する同じ例を次に示します。

(async () => {
    await Office.onReady();
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
})();

独自の初期化ハンドラーやテストを含む追加の JavaScript フレームワークを使用している場合、通常、そのようなフレームワークは Office.onReady() への応答内に配置される必要があります。 たとえば、JQuery の $(document).ready() メソッドは次のように参照します:

Office.onReady(function() {
    // Office is ready.
    $(document).ready(function () {
        // The document is ready.
    });
});

ただし、この実習には例外があります。 たとえば、ブラウザーのツールを使用してご使用の UI をデバッグするため、(Office アプリケーション内にサイドロードする代わりに) ブラウザーでご利用のアドインを開く必要があるとします。 このシナリオでは、Office.js が Office ホスト アプリケーションの外部で実行されていることを判断すると、コールバックを呼び出し、null を使用して、ホストとプラットフォームの両方に対して promise を解決します。

別の例外としては、アドインの読み込み中に、作業ウィンドウに進行状況のインジケーターを表示する場合です。 このシナリオでは、コードで jQuery ready を呼び出す必要があり、コールバックを使用して進行状況のインジケーターを表示します。 その後、Office.onReady のコールバックで、進行状況のインジケーターを最終的な UI に置き換えることができます。

Office.initialize を使用した初期化

Office.js ライブラリが読み込まれ、ユーザーとの対話の準備が完了すると、初期化イベントが発生します。 初期化ロジックを実装する Office.initialize にハンドラーを割り当てることができます。 ユーザーのバージョンの Excel が、アドインで呼び出す可能性があるすべての API をサポートしているかを確認する例は、次のとおりです。

Office.initialize = function () {
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
};

独自の初期化ハンドラーまたはテストを含む追加の JavaScript フレームワークを使用している場合は、通常、Office.initialize イベント内に配置する必要があります (この場合は、「Office.onReady() を使用して初期化する」セクションで説明した例外も適用されます)。 たとえば、JQuery の $(document).ready() メソッドは次のように参照します:

Office.initialize = function () {
    // Office is ready.
    $(document).ready(function () {
        // The document is ready.
    });
  };

作業ウィンドウ アドインとコンテンツ アドインの場合、Office.initialize で追加の reason パラメーターが提供されます。 このパラメーターでは、アドインがどのように現在のドキュメントに追加されたかが示されます。 これは、最初にアドインが挿入されたときと、既にアドインがドキュメント内に存在しているときに、別のロジックを提供するために使用できます。

Office.initialize = function (reason) {
    $(document).ready(function () {
        switch (reason) {
            case 'inserted': console.log('The add-in was just inserted.');
            case 'documentOpened': console.log('The add-in is already part of the document.');
        }
    });
 };

詳細については、Office.initialize イベントに関するページ、および InitializationReason 列挙型に関するページを参照してください。

Office.initialize と Office.onReady の間の主な相違点

• Office.initialize にハンドラーは 1 つだけ割り当てることができ、1 回だけは、Office のインフラストラクチャで呼び出されますが、Office.onReady() の呼び出しはコードと異なる場所にして、異なるコールバックを使用します。 たとえば、ご利用のコードでは、カスタム スクリプトが初期化ロジックを実行するコールバックを読み込むとすぐに Office.onReady() を呼び出しますが、ご利用のコードには、そのスクリプトが異なるコールバックで Office.onReady() を呼び出す、ボタンを作業ウィンドウに含めることもできます。 その場合は、ボタンがクリックされたときに 2 番目のコールバックが実行されます。

• Office.initialize イベントは、Office.js 自体が初期化される内部プロセスの最後に発生します。 内部のプロセスが終了した後、すぐに発生します。 イベントにハンドラーを割り当てるコードが、イベント発生後に長時間実行される場合、ハンドラーは実行されません。 たとえば、WebPack タスク マネージャーを使用する場合は、Office.js が読み込まれた後で、カスタム JavaScript を読み込む前に、ポリフィルのファイルを読み込むためのアドインのホーム ページを構成する場合があります。 ご使用のスクリプトでハンドラーの読み込みと割り当てが行われる時点で、初期化イベントは既に発生しています。 ですが、Office.onReady() を呼び出すのに "遅すぎる" ことは決してありません。 初期化イベントが既に発生している場合、コールバックがすぐに実行されます。

Office.onReady();

Office.initialize = function () {};

デバッグの初期化

Office.initialize 関数と Office.onReady() 関数のデバッグについては、「Initialize 関数と onReady 関数のデバッグ」を参照してください。

関連項目

• Office JavaScript API について
• DOM とランタイム環境を読み込む