Office アドインのランタイム

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

ランタイムの種類

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

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

これらの型の詳細については、 JavaScript 専用ランタイム と ブラウザー ランタイムに関する記事の後半で説明します。

次の表は、各種類のランタイムに応じて、アドインの考えられる機能を示しています。

ランタイムの種類	アドイン機能
JavaScript 専用	Excel カスタム関数 (ランタイムが 共有 されている場合、またはアドインが Office on the web で実行されている場合を除く) Outlook イベントベースのタスク (アドインがクラシック Outlook on Windows で実行されている場合のみ) Outlook 統合スパムレポート機能 (アドインがクラシック Outlook on Windows で実行されている場合のみ)
ブラウザー	作業ウィンドウ dialog function コマンド Excel カスタム関数 (ランタイムが共有されている場合、またはアドインが Office on the web で実行されている場合) Outlook イベントベースのタスク (アドインが Outlook on Mac または Outlook on the web または新しい Outlook on Windows で実行されている場合) Outlook 統合スパムレポート機能 (アドインが Outlook on Mac または Web 上、または新しい Outlook on Windows で実行されている場合のみ)

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

アドイン機能	Windows 上のランタイムの種類	Mac 上のランタイムの種類	Web 上のランタイムの種類
Excel のカスタム関数	JavaScript 専用 (ただし、ランタイムが共有されている場合は ブラウザー )	ブラウザー	ブラウザー
Outlook イベント ベースのタスク	JavaScript 専用 (クラシック Outlook on Windows) browser (新しい Outlook on Windows)	ブラウザー	ブラウザー
Outlook 統合スパムレポート機能 (プレビュー)	JavaScript 専用 (クラシック Outlook on Windows) browser (新しい Outlook on Windows)	ブラウザー	ブラウザー
作業ウィンドウ	ブラウザー	ブラウザー	ブラウザー
ダイアログ	ブラウザー	ブラウザー	ブラウザー
function コマンド	ブラウザー	ブラウザー	ブラウザー

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

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

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

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

  注:

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

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

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

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

  • 作業ウィンドウ

  • 関数コマンド

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

    注:

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

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

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

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

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

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

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

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

注:

• アドインが Office on the web でのみ使用され、 displayInIFrame オプションが [ true] に設定されているダイアログを開かないことがわかっている場合は、このセクションを無視できます。 アドイン内のすべてが同じランタイム プロセスで実行されるため、グローバル変数を使用して機能間でデータを共有できます。
• 上 の「ランタイムの種類」で説明したように、機能によって使用されるランタイムの種類は、プラットフォームによって部分的に異なります。 プラットフォームに基づいて分岐するアドイン コードを使用しないようにすることをお勧めします。そのため、このセクションのガイダンスでは、クロスプラットフォームで動作する手法をお勧めします。 分岐コードが必要なケースは次に示す 1 つだけです。

Excel、PowerPoint、Word アドインの場合、ダイアログを除く 2 つ以上の機能でデータを共有する必要がある場合は、 Shared ランタイム を使用します。 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 によって格納されたデータは、同じ配信元と同じトップレベル サイトを持つコンテキストでのみ使用できます。

  ヒント

  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、Full CORS (クロスオリジン リソース共有)、および OfficeRuntime.storage のサポートが追加された JavaScript エンジンが含まれています。 レンダリング エンジンは搭載されておらず、Cookie や ローカル ストレージもサポートされていません。

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

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

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

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

  注:

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

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

重要

2403 より前の Office for Windows バージョン (ビルド 16.0.17425.20000) と Office 2021 を通じた永続的ライセンス Office では、JavaScript 専用ランタイムは JavaScript 2016 標準の ECMAScript 2016 を直接サポートしています。 ただし、以降のバージョンの JavaScript または TypeScript を使用できます。 この方法の詳細については、「 JavaScript の最新バージョンのサポート」を参照してください。

ブラウザー ランタイム

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

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

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

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

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

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

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

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

注:

ランタイムが 共有されている場合、アドインをシャットダウンせずに、コードで作業ウィンドウを閉じることができる場合があります。 詳細については、「 Office アドインの作業ウィンドウを表示または非表示にする 」を参照してください。

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

共有ランタイム

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

注:

• ランタイムは、Excel、PowerPoint、Word でのみ共有できます。
• ランタイムを共有するようにダイアログを構成することはできません。 [ displayInIFrame ] オプションを [ true] に設定して Office on the web でダイアログを起動する場合を除き、各ダイアログには常に独自のダイアログがあります。
• 共有ランタイムでは、元の Microsoft Edge WebView (EdgeHTML) ランタイムは使用されません。 WebView2 (Chromium ベース) で Microsoft Edge を使用するための条件が満たされている場合 ( 「ブラウザーと Office アドインで使用される Webview コントロール」で指定されている場合)、そのランタイムが使用されます。 それ以外の場合は、Internet Explorer 11 ランタイムが使用されます。