次の方法で共有

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

  • [アーティクル]

注:

Microsoft 365 の統合マニフェストで要件を指定する方法については、「統合マニフェストで 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 アプリケーションの一部のバージョン (Microsoft 365 サブスクリプション Excel など) でサポートされているが、ボリューム ライセンスの永続的なExcel 2016など、他のバージョンではサポートされていない Office JavaScript API メソッドが必要な機能があります。 ただし、アドインには、ボリューム ライセンスの永続的なExcel 2016でサポートされている Office JavaScript API メソッドのみを必要とする他の機能があります。 このシナリオでは、そのバージョンのExcel 2016にアドインをインストールできる必要がありますが、サポートされていない方法を必要とする機能は、それらのユーザーには表示しないようにする必要があります。

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

注:

Office アドインが現在サポートされている場所の概要については、「Office アドインの Office クライアント アプリケーションとプラットフォームの可用性 」ページを参照してください。

ヒント

この記事で説明するタスクの多くは、Office アドイン の Yeoman ジェネレーター や Visual Studio の Office アドイン テンプレートの 1 つなど、ツールを使用してアドイン プロジェクトを作成するときに、全体または一部で実行されます。 このような場合は、タスクが完了したことを確認する必要があることを意味として解釈してください。

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

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

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>

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

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

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

たとえば、次の <Hosts> と <Host> 宣言では、アドインを Excel の任意のリリースにインストールできることを指定します。これには、Excel on the web、Windows、iPad が含まれますが、他の Office アプリケーションにはインストールできません。

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

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

名前 Office クライアント アプリケーション 使用可能なアドインの種類
ドキュメント Web、Windows、Mac、iPad 上のWord 作業ウィンドウ
Mailbox Outlook on the web、Windows (新規およびクラシック)、Mac、Android、iOS メール
Notebook OneNote on the web 作業ウィンドウ、コンテンツ
Presentation PowerPoint on the web、Windows、Mac、iPad 作業ウィンドウ、コンテンツ
Project Windows での Project 作業ウィンドウ
ブック Excel on the web、Windows、Mac、iPad 作業ウィンドウ、コンテンツ
Database Access (廃止) 作業ウィンドウ

注:

Office アプリケーションは、さまざまなプラットフォームでサポートされ、デスクトップ、Web ブラウザー、タブレット、モバイル デバイスで実行されます。 通常、アドインの実行に使用できるプラットフォームを指定することはできません。 たとえば、Workbookを指定した場合、Excel on the webと Windows の両方を使用してアドインを実行できます。 ただし、 Mailboxを指定した場合、 モバイル拡張機能ポイントを定義しない限り、アドインは Outlook モバイル クライアントで実行されません。

注:

アドインのみのマニフェストを複数の種類 (メール、作業ウィンドウ、またはコンテンツ) に適用することはできません。 つまり、アドインを Outlook と他の Office アプリケーションのいずれかにインストールできるようにする場合は、 2 つの アドイン (1 つはメール型マニフェスト、もう 1 つは作業ウィンドウまたはコンテンツ タイプ マニフェスト) を作成する必要があります。

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

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

重要

ベース マニフェストを使用して、アドインが重要な値である必要がある API メンバーを指定するだけです。 アドインで一部の機能に API を使用しているが、API を必要としないその他の便利な機能がある場合は、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 アプリケーションのバージョン、および実行されているプラットフォームによって異なります。 たとえば、DialogApi 1.2 は、Office 2021する前にボリューム ライセンスの永続的なバージョンの Office ではサポートされていませんが、DialogApi 1.1 は Office 2016 に戻るすべての永続的なバージョンでサポートされています。 使用する API をサポートするプラットフォームと Office バージョンのすべての組み合わせにアドインをインストールできるようにする必要があるため、必ずマニフェストで、アドインに必要な各要件セットの 最小 バージョンを指定する必要があります。 これを行う方法の詳細については、この記事の後半で説明します。

ヒント

要件セットのバージョン管理の詳細については、「 Office 要件セットの可用性」を参照し、要件セットの完全な一覧と各 API に関する情報については、 Office アドイン要件セットから始めます。 ほとんどの Office.js API のリファレンス トピックでは、所属する要件セット (存在する場合) も指定します。

注:

一部の要件セットには、マニフェスト要素も関連付けられています。 この事実がアドインの設計に関連する場合の詳細については、「 VersionOverrides 要素での要件の指定 」を参照してください。

Requirements 要素

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

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

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

注:

<Requirements> 要素は、Outlook アドインを除くすべてのアドインでは省略可能です。ルート OfficeApp 要素のxsi:type属性がMailAppされている場合は、アドインに必要なメールボックス要件セットの最小バージョンを指定する <Requirements> 要素が必要です。 詳細については、「 Outlook JavaScript API 要件セット」を参照してください。

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

  • TableBindings 要件セット。最小バージョンは "1.1" です。
  • OOXML 要件セット。最小バージョンは "1.1" です。
  • Document.getSelectedDataAsync 方式。
<OfficeApp ... >
  ...
  <Requirements>
     <Sets DefaultMinVersion="1.1">
        <Set Name="TableBindings" MinVersion="1.1"/>
        <Set Name="OOXML" 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 種類に分けることができます。

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

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

VersionOverrides 要素で要件を指定する

VersionOverrides 要素は、アドイン コマンド (カスタム リボン ボタンとメニュー) など、アドインのインストール直後に使用できる必要がある機能をサポートするために、主にマニフェスト スキーマに追加されましたが、排他的ではありません。 Office は、アドイン マニフェストを解析するときに、これらの機能について知っている必要があります。

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

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

<Requirements> 要素の子孫要素の詳細については、この記事の「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>

警告

アドインにアドイン コマンドが含まれている場合は、<VersionOverrides> に <Requirements> 要素を含める前に細心の注意を払ってください。 要件をサポートしていないプラットフォームとバージョンの組み合わせ では、要件 を 必要としない機能を呼び出すアドイン コマンドもインストールされません。 たとえば、2 つのカスタム リボン ボタンを持つアドインを考えてみましょう。 そのうちの 1 つは、要件セット ExcelApi 1.4 (以降) で使用できる Office JavaScript API を呼び出します。 他の API は、 ExcelApi 1.9 (以降) でのみ使用できる API を呼び出します。 <VersionOverrides でExcelApi 1.9 の要件を設定した場合> 1.9 がサポートされていない場合、どちらのボタンもリボンに表示されません。 このシナリオでは、「 実行時に API の可用性を確認する」で説明されている手法を使用することをお勧めします。 2 番目のボタンによって呼び出されたコードは、最初に isSetSupported を使用して、ExcelApi 1.9 のサポートをチェックします。 サポートされていない場合、コードは、アドインのこの機能が Office のバージョンでは使用できないことを示すメッセージをユーザーに提供します。

ヒント

基本マニフェストに既に表示されている <VersionOverrides> 内の <Requirement> 要素を繰り返しても意味がありません。 要件がベース マニフェストで指定されている場合、要件がサポートされていない場所にアドインをインストールできないため、Office は <VersionOverrides> 要素も解析しません。

関連項目