Office アドインを初期化する

  • [アーティクル]

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

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

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

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

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

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

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

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

ヒント

Office.initialize の代わりに Office.onReady() を使用することをお勧めします。 Office.initialize引き続きサポートされていますが、Office.onReady()柔軟性が高くなります。 に割り当てることができるハンドラー Office.initialize は 1 つだけであり、Office インフラストラクチャによって 1 回だけ呼び出されます。 コード内のさまざまな場所でを呼び出 Office.onReady() し、異なるコールバックを使用できます。

これらの手法の違いの詳細については、「Office.initialize と Office.onReady の間の主な相違点」を参照してください。

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

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

Office.onReady() は、Office.js ライブラリが読み込まれているかどうかを確認するときに Promise オブジェクトを返す非同期関数です。 ライブラリが読み込まれると、Promise は、列挙値 (など) を持つ Office クライアント アプリケーションと、列挙値 (ExcelPC、OfficeOnlineMac、Wordなど) を持Office.HostTypeつプラットフォームを指定するOffice.PlatformTypeオブジェクトとして解決されます。 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 ホスト アプリケーションの外部で実行されていることを判断すると、コールバックを呼び出し、ホストとプラットフォームの両方で promise を null 解決します。

もう 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()しても "遅すぎる" ことはありません。 初期化イベントが既に発生している場合、コールバックがすぐに実行されます。

注:

スタートアップ ロジックがない場合でも、アドイン JavaScript を読み込むときには、Office.onReady() を呼び出すか、または空の関数を Office.initialize に割り当てる必要があります。 一部の Office アプリケーションとプラットフォームの組み合わせは、これらのいずれかが発生するまで作業ウィンドウを読み込むことはありません。 次の例はこの 2 つの方法を示しています。

Office.onReady();

Office.initialize = function () {};

デバッグの初期化

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

関連項目