Office アドインのランタイム

  • [アーティクル]

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

ランタイムの種類

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

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

次の表は、アドインの使用可能な機能が各種類のランタイムを使用する方法を示しています。

ランタイムの種類 アドイン機能
JavaScript 専用 Excel カスタム関数
(ランタイムが共有されている場合やアドインがOffice on the webで実行されている場合を除く)

Outlook イベントベースのタスク
(アドインが Outlook on Windows で実行されている場合のみ)

Outlook 統合スパムレポート機能 (プレビュー)
(アドインが Outlook on Windows で実行されている場合のみ)
ブラウザー 作業ウィンドウ

] ダイアログ

function コマンド

Excel カスタム関数
(ランタイムが共有されている場合、またはアドインがOffice on the webで実行されている場合)

Outlook イベント ベースのタスク
(アドインが Outlook on Mac またはOutlook on the webで実行されている場合)

Outlook 統合スパムレポート機能 (プレビュー)
(アドインが Outlook on Mac または Web、または新しい Outlook on Windows (プレビュー) で実行されている場合のみ)

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

アドイン機能 Windows 上のランタイムの種類 Mac 上のランタイムの種類 Web 上のランタイムの種類
Excel のカスタム関数 JavaScript 専用
(ただし、ランタイムが共有されている場合は ブラウザー )		 JavaScript 専用
(ただし、ランタイムが共有されている場合は ブラウザー )		 ブラウザー
Outlook イベント ベースのタスク JavaScript 専用
(クラシック Outlook on Windows)

ブラウザー
(新しい Outlook on Windows (プレビュー))		 ブラウザー ブラウザー
Outlook 統合スパムレポート機能 (プレビュー) JavaScript 専用
(クラシック Outlook on Windows)

ブラウザー
(新しい Outlook on Windows (プレビュー))		 ブラウザー ブラウザー
作業ウィンドウ ブラウザー ブラウザー ブラウザー
ダイアログ ブラウザー ブラウザー ブラウザー
function コマンド ブラウザー ブラウザー ブラウザー

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 つものランタイムがあります。

    • 作業ウィンドウ

    • 関数コマンド

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

      注:

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

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

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

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

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

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

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

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

注:

  • アドインがOffice on the webでのみ使用され、オプションが に設定trueされたダイアログdisplayInIFrameを開かないことがわかっている場合は、このセクションを無視できます。 アドイン内のすべてが同じランタイム プロセスで実行されるため、グローバル変数を使用して機能間でデータを共有できます。
  • 上 の「ランタイムの種類」で説明したように、機能によって使用されるランタイムの種類は、プラットフォームによって部分的に異なります。 プラットフォームに基づいて分岐するアドイン コードを使用しないようにすることをお勧めします。そのため、このセクションのガイダンスでは、クロスプラットフォームで動作する手法をお勧めします。 分岐コードが必要なケースは次に示す 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 によって格納されたデータは、同じ配信元と同じトップレベル サイトを持つコンテキストでのみ使用できます。 これを回避するには、ブラウザーで [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 プロパティの値でコードを分岐する必要があります。

    • 値が (Windows) の場合は PC 、 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 専用ランタイムでは、使用するメモリが少なくなり、ブラウザー ランタイムよりも高速に起動しますが、機能は少なくなります。

重要

JavaScript 専用ランタイムは、JAVAScript の 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 またはインターネット エクスプローラーによってランタイムが提供されます。 詳細については、「 Office アドインで使用されるブラウザーと Webview コントロール」を参照してください。

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

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

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

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

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

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

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

注:

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

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

共有ランタイム

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

注:

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