共有ランタイムを使用するように Office アドインを構成する
重要
共有ランタイムは、一部の Office アプリケーションでのみサポートされています。 詳細については、「共有ランタイム要件セット」を参照してください。
1 つの 共有ランタイムですべてのコードを実行するように Office アドインを構成できます。 これにより、アドイン間での調整が容易になり、アドインのすべての部分から DOM や CORS にアクセスできます。 また、ドキュメントを開いたときにコードを実行したり、リボン ボタンを有効または無効にするなどの追加機能も有効にできます。 共有ランタイムが使用できるようにアドインを構成するには、この記事の手順に従います。
アドイン プロジェクトの作成
新しいプロジェクトを開始する場合は、Office アドイン用の Yeoman ジェネレーターを使用して、Excel、PowerPoint、または Word アドイン プロジェクトを作成します。
コマンド yo office --projectType taskpane --name "my office add in" --host <host> --js true を実行します。ここで、<host> は次のいずれかの値です。
- Excel
- PowerPoint
- Word
重要
--name の引数値は、スペースがない場合でも二重引用符で囲む必要があります。
--projecttype、--name と--js コマンド ライン オプションのためのさまざまなオプションを使用できます。 オプションの完全な一覧については、「Office アドイン用の Yeoman ジェネレーター」 を参照してください。
ジェネレーターはプロジェクトを作成し、サポートしているノード コンポーネントをインストールします。 この記事の手順を使用して、共有ランタイムを使用するために既存の Visual Studio プロジェクトを更新することもできます。 ただし、マニフェストの XML スキーマの更新が必要になる場合があります。 詳細については、「Office アドインでの開発エラーのトラブルシューティング」を参照してください。
マニフェストを構成する
新規または既存のプロジェクトで共有ランタイムが使用できるように構成するには、次の手順を実行します。 これらの手順は、Office アドイン用の Yeoman ジェネレーターを使用してプロジェクトを生成したことを前提としています。
Visual Studio Code を開始し、アドイン プロジェクトを開きます。
manifest.xml ファイルを開きます。
Excel または PowerPoint アドインの場合は、要件セクションを更新して、shared runtime を含めます。
CustomFunctionsRuntime要件が存在する場合は、必ず削除してください。 XML は、次のようになります。<Hosts> <Host Name="Workbook"/> </Hosts> <Requirements> <Sets DefaultMinVersion="1.1"> <Set Name="SharedRuntime" MinVersion="1.1"/> </Sets> </Requirements> <DefaultSettings><VersionOverrides> セクションを見つけて、次の<Runtimes> セクションを追加します。 作業ウィンドウを閉じてもアドイン コードを実行できるように、有効期間は長くする必要があります。
resid値は Taskpane.Url で、manifest.xml ファイルの下部付近の<bt:Urls>セクションで指定された taskpane.html ファイルの場所を参照します。重要
residがマニフェストで異なる値を使用している場合、共有ランタイムは読み込まれません。 値を Taskpane.Url 以外の値に変更する場合は、この記事の次の手順に示すすべての場所の値も必ず変更してください。また、<Runtimes> セクションは、次の XML に示されている正確な順序で、<Host> 要素の後に入力する必要があります。
<VersionOverrides ...> <Hosts> <Host ...> <Runtimes> <Runtime resid="Taskpane.Url" lifetime="long" /> </Runtimes> ... </Host>カスタム関数を使用して Excel アドインを生成した場合は、 <Page> 要素を見つけます。 次に、ソースの場所を Functions.Page.Url から Taskpane.Url に変更します。
<AllFormFactors> ... <Page> <SourceLocation resid="Taskpane.Url"/> </Page> ...<FunctionFile> タグを見つけて、
residを Commands.Url から Taskpane.Url に変更します。 アクション コマンドがない場合は、 <FunctionFile> エントリがないため、この手順をスキップできます。</GetStarted> ... <FunctionFile resid="Taskpane.Url"/> ...manifest.xml ファイルを保存します。
webpack.config.js ファイルを構成する
webpack.config.js は、複数のランタイム ローダーをビルドします。 taskpane.html ファイルを介して共有ランタイムのみを読み込むよう変更する必要があります。
Visual Studio Code を起動し、生成したアドイン プロジェクトを開きます。
webpack.config.js ファイルを開きます。
webpack.config.js ファイルに次の functions.html プラグイン コードが含まれている場合は、それを削除します。
new HtmlWebpackPlugin({ filename: "functions.html", template: "./src/functions/functions.html", chunks: ["polyfill", "functions"] })webpack.config.js ファイルに次の commands.html プラグイン コードが含まれている場合は、それを削除します。
new HtmlWebpackPlugin({ filename: "commands.html", template: "./src/commands/commands.html", chunks: ["polyfill", "commands"] })プロジェクトで関数チャンクまたはコマンドチャンクのいずれかを使用した場合は、次に示すようにそれらをチャンク リストに追加します (次のコードは、プロジェクトで両方のチャンクを使用した場合のものです)。
new HtmlWebpackPlugin({ filename: "taskpane.html", template: "./src/taskpane/taskpane.html", chunks: ["polyfill", "taskpane", "commands", "functions"] })変更を保存してプロジェクトを再ビルドします。
npm run build
注:
プロジェクトに functions.html ファイルまたは commands.html ファイルがある場合は、それらを削除できます。 taskpane.html は、先ほど行った webpack 更新プログラムを使用して、functions.js と commands.js コードを共有ランタイムに読み込みます。
Office アドインの変更をテストする
次の手順を使用して、共有ランタイムを正しく使用していることを確認できます。
taskpane.js ファイルを開きます。
ファイルのすべての内容を次のコードで置き換えます。 これにより、作業ウィンドウが開かれた回数が表示されます。 onVisibilityModeChanged イベントの追加は、共有ランタイムでのみサポートされます。
/*global document, Office*/ let _count = 0; Office.onReady(() => { document.getElementById("sideload-msg").style.display = "none"; document.getElementById("app-body").style.display = "flex"; updateCount(); // Update count on first open. Office.addin.onVisibilityModeChanged(function (args) { if (args.visibilityMode === "Taskpane") { updateCount(); // Update count on subsequent opens. } }); }); function updateCount() { _count++; document.getElementById("run").textContent = "Task pane opened " + _count + " times."; }変更を保存してプロジェクトを実行します。
npm start
作業ウィンドウを開くたびに、開かれた回数が増加します。 _count の値は失われません。共有ランタイムは作業ウィンドウを閉じてもコードを実行したままにするためです。
開発サーバーを停止してアドインをアンインストールする準備ができたら、次のコマンドを実行します。
npm stop
ランタイムの有効期間
<Runtime> 要素を追加する場合は、値が long または short の有効期間も指定します。 この値を long に設定すると、ドキュメントを開くとアドインを起動したり、作業ウィンドウを閉じた後にコードを継続して実行したり、カスタム関数から CORS および DOM を使用したりできます。
注:
既定の有効期間の値は short ですが、Excel、PowerPoint、および Word アドインでは long を使うことをお勧めします。この例でランタイムを short に設定した場合、いずれかのリボン ボタンを押したときにアドインが起動しますが、リボン ハンドラーの実行が完了するとアドインが終了することがあります。 同様に、作業ウィンドウを開くとアドインが起動します。ただし、作業ウィンドウを閉じると、アドインが終了する場合があります。
<Runtimes>
<Runtime resid="Taskpane.Url" lifetime="long" />
</Runtimes>
注:
アドインにマニフェストに <Runtimes> 要素 (共有ランタイムに必要) が含まれており、WebView2 (Microsoft Edge Chromium ベース) を使用するための条件が満たされている場合、そのコントロールが使用されます。 条件が満たされていない場合は、Windows または Microsoft 365 のバージョンに関係なく Trident (Internet エクスプローラー 11) Webview コントロールを使用します。 詳細については、「 ランタイム と ブラウザー」および「Office アドインで使用される Webview コントロール」を参照してください。
共有ランタイムについて
Windows または Mac では、アドインはリボン ボタン、カスタム関数、作業ウィンドウのコードを個別のランタイム環境で実行します。 これにより、グローバル データを簡単に共有できない、カスタム関数からすべての CORS 機能にアクセスできないなどの制限が発生します。
ただし、同じランタイム (共有ランタイムとも呼ばれます) でコードを共有するように Office アドインを構成できます。 これにより、アドイン間での調整が容易になり、アドインのすべての部分から、作業ウィンドウの DOM や CORS にアクセスできます。
共有ランタイムを構成すると、次のシナリオが可能になります。
- Office アドインは、追加の UI 機能を使用できます。
- 以下は、Excel アドインでのみ使用できます。
- Office アドインにカスタム キーボード ショートカットを追加する
- Office アドインでカスタム コンテキスト タブを作成する
- カスタム関数で CORS がすべてサポートされます。
- カスタム関数で、Office.js API を呼び出して、スプレッドシート ドキュメントのデータを読み取ることができます。
Windows 上の Office の場合、共有ランタイムは WebView2 (Microsoft Edge Chromium ベース) を使用します。使用条件が「ブラウザーと Office アドインで使用される Webview コントロール」で説明されているように満たされている場合です。それ以外の場合は、Trident (インターネット エクスプローラー 11) を使用します。 また、アドインのリボンに表示するボタンはすべて、同じ共有ランタイムで実行されます。 次の図は、カスタム関数、リボン UI、作業ウィンドウ コードがすべて同じランタイムでどのように実行されるかを示しています。
複数の作業ウィンドウ
共有ランタイムを使用する予定がある場合は、複数の作業ウィンドウを使用するようにアドインを設計しないでください。 共有ランタイムは、1 つの作業ウィンドウのみサポートします。
<TaskpaneID> のない作業ウィンドウは、別の作業ウィンドウとして扱われますのでご注意ください。
関連項目
Office Add-ins