Office アドインを初期化する

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

• ユーザーのバージョンの Office で、コードで呼び出されるすべての Office API がサポートされていることを確認します。

• 特定の名前のワークシートなど、特定の成果物が存在することを確認します。

• Excel で一部のセルを選択するようにユーザーに求め、選択した値で初期化されたグラフを挿入します。

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

• Office Dialog API を使用して、既定のアドイン設定の値をユーザーに求めます。

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

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

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

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

Office.onReady() は、Office.js ライブラリが読み込まれているかどうかを確認するときに Promise オブジェクトを返す非同期関数です。 ライブラリが読み込まれると、Promise は、 Office.HostType 列挙値 (Excel、 Word など) を持つ Office クライアント アプリケーションと、 Office.PlatformType 列挙値 (PC、 Mac、 OfficeOnline など) を持つプラットフォームを指定するオブジェクトとして解決されます。 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.");
        }
    });

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

(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 を解決します。

もう 1 つの例外は、アドインの読み込み中に作業ウィンドウに進行状況インジケーターを表示する場合です。 このシナリオでは、コードで 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 とランタイム環境を読み込む