アドインのみのマニフェストで Office アプリケーションと API の要件を指定する

Office アドインは、特定の Office アプリケーション (Office ホストとも呼ばれます) または Office JavaScript ライブラリ (office.js) の特定のメンバーに依存する場合があります。 たとえば、次のようなアドインがあります。

• 1 つの Office アプリケーション (Word や Excel など) または複数のアプリケーションで実行します。
• 一部のバージョンの Office でのみ利用可能な Office JavaScript API をご利用ください。 たとえば、ボリューム ライセンスの永続的なバージョンの Excel 2016 では、Office JavaScript ライブラリのすべての Excel 関連 API がサポートされているわけではありません。

このような状況では、実行できない Office アプリケーションまたは Office バージョンにアドインがインストールされないようにする必要があります。

また、Office アプリケーションと Office のバージョンに基づいて、アドインのどの機能をユーザーに対して表示するかを制御するシナリオもあります。 次の 2 つの例を次に示します。

• アドインにはテキスト操作など Word と PowerPoint の両方で役立つ機能がありますが、スライド管理機能など、PowerPoint でのみ意味のある追加機能がいくつかあります。 アドインが Word で実行されている場合は、PowerPoint 専用の機能を非表示にする必要があります。
• アドインには、Office JavaScript API メソッドを必要とする機能があります。この機能は、Office アプリケーションの一部のバージョン (Microsoft 365 サブスクリプションの Excel など) でサポートされていますが、ボリューム ライセンスの永続的な Excel 2016 など、他のバージョンではサポートされていません。 ただし、アドインには、ボリューム ライセンスの永続的な Excel 2016 でサポートされている Office JavaScript API メソッドのみを必要とする他の機能があります。 このシナリオでは、そのバージョンの Excel 2016 にアドインをインストールできる必要がありますが、サポートされていないメソッドを必要とする機能はそれらのユーザーに非表示にする必要があります。

この記事は、アドインが期待どおりに機能し、できるだけ多くのユーザーが利用できるようにするために選択する必要のあるオプションについて理解するのに役立ちます。

最新の Office JavaScript API ライブラリを使用する

アドインでは、コンテンツ配信ネットワーク (CDN) から最新バージョンの Office JavaScript API ライブラリを読み込む必要があります。 これを行うには、アドインで最初に開く HTML ファイルに次の <script> タグがあることを確認します。 CDN URL で /1/ を使用することで、Office.js の最新版が参照されます。

<script src="https://officeapis.public.onecdn.static.microsoft/1/office.js" type="text/javascript"></script>

アドインをホストできる Office アプリケーションを指定する

既定では、アドインは、指定されたアドインの種類 (メール、作業ウィンドウ、コンテンツなど) でサポートされているすべての Office アプリケーションにインストールできます。 たとえば、作業ウィンドウ アドインは、Access、Excel、OneNote、PowerPoint、Project、Word に既定でインストールできます。

アドインを Office アプリケーションのサブセットにのみインストールできるようにするには、アドインのみのマニフェストで Hosts 要素と Host 要素を使用します。

たとえば、次の <Hosts> and <Host> 宣言では、アドインは、Excel on the web、Windows、iPad などの Excel のどのリリースにもインストールできますが、他の Office アプリケーションにはインストールできないことを指定します。

<Hosts>
  <Host Name="Workbook" />
</Hosts>

<Hosts>要素には、1 つ以上の<Host>要素を含めることができます。 アドインをインストール可能な Office アプリケーションごとに個別の <Host> 要素にする必要があります。 Name 属性は必須であり、次のいずれかの値に設定できます。

アドインをホストできる Office のバージョンとプラットフォームを指定する

アドインをインストール可能な Office のバージョンやビルド、またはプラットフォームを明示的に指定することはできません。また、アドインが使用するアドイン機能のサポートが新しいバージョンまたはプラットフォームに拡張されるたびにマニフェストを修正する必要があるため、明示的に指定することも望まないでしょう。 代わりに、アドインに必要な API をマニフェストで指定します。 Office では、API をサポートしていない Office のバージョンとプラットフォームの組み合わせにアドインがインストールされず、アドインが [個人用アドイン] に表示されないようにします。

要件セット

アドインに必要な API を指定するプロセスを簡略化するために、Office ではほとんどの API を 要件セットにグループ化しています。 共通 API オブジェクト モデルの API は、サポートする開発機能によってグループ化されています。 たとえば、テーブル バインディングに接続されているすべての API は、"TableBindings 1.1" という要件セットに含まれています。 アプリケーション固有のオブジェクト モデルの API は、実稼働アドインで使用するためにリリースされた時期によってグループ化されています。

要件セットはバージョン管理されています。 たとえば、 ダイアログ ボックス をサポートする API は、要件セットの DialogApi 1.1 に含まれています。 作業ウィンドウからダイアログへのメッセージングを可能にする追加の API がリリースされたときに、DialogApi 1.1 のすべての API とともに DialogApi 1.2 にグループ化されました。 要件セットの各バージョンは、以前のすべてのバージョンのスーパーセットです。

要件セットのサポートは、Office アプリケーション、Office アプリケーションのバージョン、および実行されているプラットフォームによって異なります。 たとえば、ExcelApi 1.17 は Office 2024 以前のボリューム ライセンスの永続的なバージョンの Office ではサポートされていませんが、ExcelApi 1.14 は Office 2021 でサポートされます。 アドインは、使用する API をサポートするプラットフォームと Office バージョンのすべての組み合わせにインストールできるようにする必要があるため、アドインが必要とする各要件セットの 最小 バージョンを常にマニフェストで指定する必要があります。 この方法の詳細については、この記事の後半で説明します。

Requirements 要素

Requirements 要素とその子要素セットを使用して、アドインをインストールするために Office アプリケーションがサポートする必要がある最小要件セットを指定します。

アプリケーション固有のモデルのすべての API は要件セットに含まれますが、共通 API モデルの一部は要件セットに含まれていません。 メソッドを使用して、アドインに必要なセットレス API メンバーを指定します。 Outlook アドインで <Methods> 要素を使用することはできません。

Office アプリケーションまたはプラットフォームが、 <Requirements> 要素で指定された要件セットまたは API メンバーをサポートしていない場合、アドインはそのアプリケーションまたはプラットフォームでは実行されず、[ マイ アドイン] にも表示されません。

次のコード例は、以下をサポートするすべての Office アプリケーションにインストール可能なアドインを構成する方法を示しています。

• TableBindings 最小バージョンが "1.1" の要件セット。
• OoxmlCoercion 最小バージョンが "1.1" の要件セット。
• Document.getSelectedDataAsync メソッド。

<OfficeApp ... >
  ...
  <Requirements>
     <Sets DefaultMinVersion="1.1">
        <Set Name="TableBindings" MinVersion="1.1"/>
        <Set Name="OoxmlCoercion" MinVersion="1.1"/>
     </Sets>
     <Methods>
        <Method Name="Document.getSelectedDataAsync"/>
     </Methods>
  </Requirements>
    ...
</OfficeApp>

この例の次の点に注意してください。

• <Requirements> 要素には、<Sets> と <Methods> の子要素が含まれます。
• <Sets>要素には、1 つ以上の<Set>要素を含めることができます。 DefaultMinVersionすべての子<Set>要素の既定のMinVersion値を指定します。
• Set 要素は、アドインをインストール可能にするために Office アプリケーションがサポートする必要がある要件セットを指定します。 Name 属性は、要件セットの名前を指定します。 MinVersionは、要件セットの最小バージョンを指定します。 MinVersion親<Sets>の DefaultMinVersion 属性の値をオーバーライドします。
• <Methods>要素には、1 つ以上の Method 要素を含めることができます。 Outlook アドインで <Methods> 要素を使用することはできません。
• <Method>要素は、アドインをインストール可能にするために Office アプリケーションがサポートする必要がある個々のメソッドを指定します。 Name 属性は必須であり、親オブジェクトで修飾されたメソッドの名前を指定します。

代替エクスペリエンスのための設計

Office アドイン プラットフォームが提供する機能拡張は、有用に次の 3 つに分けることができます。

• アドインのインストール直後に利用できる機能拡張。 この種の機能は、マニフェストで VersionOverrides 要素を構成することで利用できます。 この種の機能の例として、カスタム リボン ボタンとメニューであるアド イン コマンドがあります。
• アドインの実行時にのみ使用でき、Office.js JavaScript API を使用して実装される機能拡張性機能。たとえば、 ダイアログ ボックスなどです。
• 実行時にのみ使用できるが、Office.js JavaScript と <VersionOverrides> 要素内の構成を組み合わせて実装される機能拡張機能。 たとえば、 Excel カスタム関数、 シングル サインオン、 カスタム コンテキスト タブなどがあります。

アドインの機能の一部に特定の機能拡張機能を使用しているが、拡張機能を必要としない他の便利な機能がある場合は、拡張機能をサポートしていないプラットフォームと Office のバージョンの組み合わせにインストールできるようにアドインを設計する必要があります。 それは、減少したものの、これらの組み合わせに関する貴重な経験を提供できます。

この設計は、機能拡張機能の実装方法に応じて異なる方法で実装します。

• JavaScript だけで実装された機能については、「 実行時に API が使用できるかどうかを確認する」を参照してください。
• <VersionOverrides>要素を構成する必要がある機能については、「VersionOverrides 要素での要件の指定」を参照してください。

VersionOverrides 要素で要件を指定する

VersionOverrides 要素は、アドイン コマンド (カスタム リボン ボタンやメニュー) など、アドインのインストール後すぐに使用できるようにする必要がある機能をサポートするために、主に (これに限定されません) マニフェスト スキーマに追加されました。 Office は、アドイン マニフェストを解析するときに、これらの機能を認識する必要があります。

アドインでこれらの機能のいずれかを使用しているが、そのアドインは価値があり、その機能をサポートしていない Office バージョンでもインストール可能であるとします。 このシナリオでは、基本 OfficeApp 要素の子としてではなく、<VersionOverrides>要素自体の子として含める Requirements 要素 (およびその子の Sets 要素と Methods 要素) を使用して、この機能を識別します。 これを行うと、Office はアドインのインストールを許可しますが、Office はこの機能がサポートされていない Office バージョンの <VersionOverrides> 要素の特定の子要素を無視します。

具体的には、<Hosts>要素など、基本マニフェスト内の要素をオーバーライドする<VersionOverrides>の子要素は無視され、代わりに基本マニフェストの対応する要素が使用されます。 ただし、 <VersionOverrides> には、基本マニフェストの設定をオーバーライドするのではなく、実際に追加機能を実装する子要素が存在することができます。 2 つの例が WebApplicationInfo と EquivalentAddins です。 Office のプラットフォームとバージョンが対応する機能をサポートしている限り、 <VersionOverrides> のこれらの部分は無視 されません 。

<Requirements> 要素の子要素の詳細については、この記事で前述した「要件要素」を参照してください。

次に例を示します。

<VersionOverrides ... >
   ...
   <Requirements>
      <Sets DefaultMinVersion="1.1">
         <Set Name="WordApi" MinVersion="1.2"/>
      </Sets>
   </Requirements>
   <Hosts>

      <!-- ALL MARKUP INSIDE THE HOSTS ELEMENT IS IGNORED WHEREVER WordApi 1.2 IS NOT SUPPORTED -->

      <Host xsi:type="Workbook">
         <!-- markup for custom add-in commands -->
      </Host>
   </Hosts>
</VersionOverrides>

関連項目

• Office アドイン マニフェスト
• Office アドインの要件セット
• Office アドインのサンプル