Office アドインのランタイム

Office アドインは、Office に埋め込まれたランタイムで実行されます。 解釈される言語として、JavaScript は JavaScript ランタイムで実行する必要があります。 Node.js と最新のブラウザーは、このようなランタイムの例です。

ランタイムの種類

Office アドインで使用されるランタイムには、次の 2 種類があります:

• JavaScript 専用ランタイム: WebSocket、フル CORS (クロスオリジン リソース共有)、およびデータのクライアント側ストレージのサポートで補完された JavaScript エンジン。 ローカル ストレージや Cookie はサポートされていません。
• ブラウザー ランタイム: JavaScript 専用ランタイムのすべての機能を含み、ローカル ストレージ、HTML をレンダリングするレンダリング エンジン、Cookie のサポートを追加します。

これらの型の詳細については、この記事の後半の JavaScript 専用ランタイムとブラウザー ランタイムを参照してください。

次の表は、ランタイムの種類ごとにアドインで使用できる機能を示しています。

次の表は、アドインのさまざまな機能に使用されるランタイムの種類によって整理された同じ情報を示しています。

Office on the web では、すべてが常にブラウザー型ランタイムで実行されます。 1 つの例外を除き、Web 上のアドイン内のすべてが同じブラウザー プロセス (ユーザーが Office on the web を開いたブラウザー プロセス) で実行されます。 例外は、Office.ui.displayDialogAsync の呼び出しでダイアログが開き、DialogOptions.displayInIFrame オプションが渡されないでtrue に設定されている場合です。 オプションが渡されない (既定値 false を持つ) 場合、ダイアログは独自のプロセスで開きます。 OfficeRuntime.displayWebDialog メソッドと OfficeRuntime.DisplayWebDialogOptions.displayInIFrame オプションにも同じ原則が適用されます。

アドインが Web 以外のプラットフォームで実行されている場合は、次の原則が適用されます。

• ダイアログは、独自のランタイム プロセスで実行されます。

• Outlook イベント ベースまたはスパム報告アドインは、独自のランタイム プロセスで実行されます。

  注:

  Outlook のイベント ベースのアクティブ化機能と統合されたスパム報告機能は、同じランタイムを使用する必要があります。 Outlook では、複数のランタイムは現在サポートされていません。

• 既定では、作業ウィンドウ、関数コマンド、Excel カスタム関数はそれぞれ独自のランタイム プロセスで実行されます。 ただし、一部の Office ホスト アプリケーションでは、アドイン マニフェストを構成して、2 つまたは 3 つすべてを同じランタイムで実行できます。 「共有ランタイム」を参照してください。

ホスト Office アプリケーションとアドインで使用される機能によっては、アドインに多くのランタイムが存在する場合があります。 通常、それぞれが独自のプロセスで実行されますが、必ずしも同時に実行されるわけではありません。 次に例を示します。

• ランタイムを共有せず、次の機能を含む PowerPoint または Word アドインには、3 つのランタイムがあります。

  • 作業ウィンドウ

  • 関数コマンド

  • ダイアログ (作業ウィンドウまたは関数コマンドからダイアログを起動できます。)

    注:

    複数のダイアログを同時に開くのは良い実践ではありませんが、ユーザーが作業ウィンドウから開き、関数コマンドから同時に別のダイアログを開く場合、このアドインには 4 つのランタイムがあることになります。 作業ウィンドウと関数コマンドの特定の呼び出しで一度に開くことができるダイアログは 1 つだけです。ただし、関数コマンドが複数回呼び出された場合は、呼び出しごとに先行タスクの上に新しいダイアログが開き、多数のランタイムが存在する可能性があります。 このリストの残りの部分では、複数のダイアログが開かれる可能性は無視されます。

• ランタイムを共有せず、次の機能を含む Excel アドインには 4 つものランタイムがあります。

  • 作業ウィンドウ
  • 関数コマンド
  • カスタム関数
  • ダイアログ (ダイアログは、作業ウィンドウ、関数コマンド、またはカスタム関数から起動できます)。

• 同じ機能を備え、作業ウィンドウ、関数コマンド、およびカスタム関数間で同じランタイムを共有するように構成された Excel アドインには 2 つのランタイムがあります。 共有ランタイムでは、一度に開くことができるダイアログは 1 つだけです。

• ダイアログがなく、作業ウィンドウ、関数コマンド、およびカスタム関数間で同じランタイムを共有するように構成されている点を除き、同じ機能を持つ Excel アドインには、1 つのランタイムがあります。

• 次の機能を備えた Outlook アドインには、4 つものランタイムがあります。 共有ランタイムは Outlook ではサポートされていません。

  • 作業ウィンドウ
  • 関数コマンド
  • イベント ベースのタスクまたは統合されたスパム報告機能
  • ダイアログ (ダイアログは作業ウィンドウまたは関数コマンドから起動できますが、イベント ベースのタスクからは起動できません)。

ランタイム間でデータを共有する

Excel、PowerPoint、Word アドインの場合、ダイアログ以外の 2 つ以上の機能でデータを共有する必要がある場合は、共有ランタイムを使用します。 Outlook、またはランタイムを共有できないシナリオでは、別の方法が必要です。 個別のランタイム プロセスにあるアドインの部分は、グローバル データを自動的に共有せず、アドインの Web アプリケーション サーバーによって個別のセッションとして扱われるため、Window.sessionStorage を使用してそれらの間でデータを共有することはできません。 次のガイダンスでは、共有ランタイムを使用していないことを前提としています。

• Office.ui.messageParent メソッドと Dialog.messageChild メソッドを使用して、ダイアログとその親作業ウィンドウ、関数コマンド、またはカスタム関数の間でデータを渡します。

  注:

  OfficeRuntime.storage メソッドをダイアログで呼び出すことはできません。そのため、これはダイアログと別のランタイムの間でデータを共有するためのオプションではありません。

• 作業ウィンドウと関数コマンドの間でデータを共有するには、Window.localStorage にデータを格納します。これは、同じ特定の配信元にアクセスするすべてのランタイムで共有されます。

  注:

  LocalStorage は JavaScript 専用ランタイムではアクセスできないため、Excel カスタム関数では使用できません。 また、Outlook イベント ベースのタスクとデータを共有するためにも使用できません (これらのタスクは一部のプラットフォームで JavaScript 専用ランタイムを使用するため)。

  Chrome や Edge などの Chromium ベースのブラウザーのバージョン 115 以降では、特定のサイドチャネル クロスサイト追跡を 防ぐためにストレージ パーティション分割がテストされています (「Microsoft Edge のブラウザー ポリシー」も参照してください)。 つまり、ローカル ストレージなどのストレージ API によって格納されたデータは、同じ配信元と同じ最上位サイトを持つコンテキストでのみ使用できます。 この問題を回避するには、ブラウザーで chrome://flags または edge://flags に移動し、試験段階のサード パーティ製ストレージ パーティション分割 (#third-party-storage-partitioning) フラグを [無効] に設定します。

  ヒント

  Window.localStorage のデータはアドインのセッション間で保持され、同じ配信元のアドインによって共有されます。 多くの場合、これらの特性はいずれも、アドインでは望ましくありません。

  • 特定のアドインの各セッションが新しく開始されるようにするには、アドインの起動時に Window.localStorage.clear メソッドを呼び出します。
  • 保存されている一部の値を永続化できますが、他の値を再初期化するには、初期値にリセットする必要がある項目ごとにアドインが開始するときに Window.localStorage.setItem を使用します。
  • アイテムを完全に削除するには、Window.localStorage.removeItem を呼び出します。

• Excel カスタム関数と他のランタイムの間でデータを共有するには、OfficeRuntime.storage を使用します。

• Outlook イベント ベースのタスクと作業ウィンドウまたは関数コマンドの間でデータを共有するには、Office.context.platform プロパティの値でコードを分岐する必要があります。

  • 値が PC (Windows) の場合は、Office.sessionData API を使用してデータを格納および取得します。
  • 値が Mac の場合は、このリストで前述したように Window.localStorage を使用します。

データを共有するその他の方法は次のとおりです:

• すべてのランタイムがアクセスできるオンライン データベースに共有データを格納します。
• アドインのドメインの Cookie に共有データを格納して、ブラウザー ランタイム間で共有します。 JavaScript 専用のランタイムでは、Cookie はサポートされていません。

詳細については、「アドインの状態と設定を保持する」および「Outlook アドインのアドイン メタデータを取得および設定する」を参照してください。

JavaScript 専用ランタイム

Office アドインで使用される JavaScript 専用ランタイムは、React Native 用に最初に作成されたオープン ソース ランタイムの変更です。 これには、WebSocket、フル CORS (クロスオリジン リソース共有)、OfficeRuntime.storage のサポートを補足する JavaScript エンジンが含まれています。 レンダリング エンジンがないため、Cookie やローカル ストレージはサポートされていません。

この種類のランタイムは、カスタム関数がランタイムを共有している場合を除き、Windows 上の Outlook および Excel カスタム関数でのみ、イベント ベースおよびスパム報告アドインで使用されます。

• Excel カスタム関数に使用すると、ワークシートが再計算されるか、カスタム関数が計算されるときにランタイムが起動します。 ブックが閉じられるまでシャットダウンされません。

• Outlook イベント ベースまたはスパム報告アドインで使用すると、イベントが発生したときにランタイムが起動します。 次のうちの最初に発生したときにこれは終了します。

  • イベント ハンドラーは、そのイベント パラメーターの completed メソッドを呼び出します。
  • トリガー イベントから 5 分が経過しました。
  • ユーザーは、メッセージ作成ウィンドウなど、イベントがトリガーされたウィンドウからフォーカスを変更します (イベント ベースのアドインにのみ適用されます)。

  注:

  Outlook のイベント ベースのアクティブ化機能と統合されたスパム報告機能は、同じランタイムを使用する必要があります。 Outlook では、複数のランタイムは現在サポートされていません。

JavaScript 専用のランタイムでは、使用するメモリが少なく、ブラウザー ランタイムよりも高速に起動されますが、機能は少なくなります。

ブラウザー ランタイム

Office アドインは、Office が実行されているプラットフォーム (Web、Mac、または Windows) と、Windows と Office のバージョンとビルドに応じて、異なるブラウザーの種類のランタイムを使用します。 たとえば、ユーザーが FireFox ブラウザーで Office on the web を実行している場合、Firefox ランタイムが使用されます。 ユーザーが Mac で Office を実行している場合は、Safari ランタイムが使用されます。 ユーザーが Windows で Office を実行している場合は、Windows と Office のバージョンに応じて、Edge または Internet Explorer がランタイムを提供します。 詳細については、「Office アドインで使用されるブラウザーと Web ビュー コントロール」を参照してください。

これらのランタイムはすべて HTML レンダリング エンジンを含み、WebSocket、フル CORS (クロスオリジン リソース共有)、ローカル ストレージ、Cookie のサポートを提供します。

ブラウザーのランタイムの有効期間は、実装されている機能と、それが共有されているかどうかによって異なります。

• 作業ウィンドウを含むアドインが起動されると、既に実行されている共有ランタイムでない限り、ブラウザー ランタイムが起動します。 共有ランタイムの場合は、ドキュメントが閉じられたときにシャットダウンされます。 共有ランタイムでない場合は、作業ウィンドウが閉じられたときにシャットダウンされます。

• ダイアログが開くと、ブラウザー ランタイムが起動します。 ダイアログが閉じられたときにシャットダウンされます。

• 関数コマンドが実行されると (ユーザーがそのボタンまたはメニュー項目を選択したときに発生します)、既に実行されている共有ランタイムでない限り、ブラウザー ランタイムが起動します。 共有ランタイムの場合は、ドキュメントが閉じられたときにシャットダウンされます。 共有ランタイムでない場合は、次のうちのいずれかが最初に発生したときにシャットダウンされます。

  • 関数コマンドは、そのイベント パラメーターの completed メソッドを呼び出します。
  • トリガー イベントから 5 分が経過しました。 (関数コマンドでダイアログが開き、親ランタイムがタイムアウトしても開いたままの場合、ダイアログが閉じられるまでダイアログ ランタイムは実行されたままになります。)

• Excel カスタム関数が共有ランタイムを使用している場合、ブラウザー型ランタイムは、共有ランタイムがまだ他の理由で開始されていない場合にカスタム関数が計算されるときに開始されます。 ドキュメントが閉じられたときにシャットダウンされます。

ブラウザー ランタイムには、JavaScript 専用ランタイムよりも多くの機能がありますが、起動が遅くなり、より多くのメモリが使用されます。

共有ランタイム

"共有ランタイム" はランタイムの一種ではありません。 これは、アドインの機能によって共有されているブラウザー型ランタイムを指します。それ以外の場合は、それぞれ独自のランタイムを持ちます。 具体的には、ランタイムを共有するためにアドインの作業ウィンドウと関数コマンドを構成するオプションがあります。 Excel アドインでは、作業ウィンドウまたは関数コマンドのランタイムまたはその両方を共有するようにカスタム関数を構成することもできます。 これを行うと、カスタム関数は、JavaScript 専用のランタイムではなく、ブラウザー型のランタイムで実行されます。それ以外の場合と同様です。 共有ランタイムの利点と制限事項、および共有ランタイムを使用するようにアドインを構成する手順については、「共有ランタイムを使用するようにアドインを構成する」を参照してください。 簡単に言うと、JavaScript のみのランタイムでは、使用するメモリが少なく、起動速度は速くなりますが、機能は少なくなります。