Office アプリケーションと API 要件を指定する

  • [アーティクル]

Office アドインは、特定の Office アプリケーション (Office ホストとも呼ばれます) または Office JavaScript API (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 要素を使用します。

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

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

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

名前 Office クライアント アプリケーション 使用可能なアドインの種類
データベース Access Web アプリ 作業ウィンドウ
ドキュメント 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 作業ウィンドウ、コンテンツ

注:

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

注:

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

重要

SharePoint で Access Web アプリとデータベースを作成して使用することは推奨されなくなりました。 代わりに、Microsoft PowerApps を使用して、コード作成が不要な Web とモバイル デバイス用ビジネス ソリューションをビルドすることをお勧めします。

アドインをホストできる 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 2013 に戻るすべての永続的なバージョンでサポートされています。 使用する API をサポートするプラットフォームと Office バージョンのすべての組み合わせにアドインをインストールできるようにする必要があるため、必ずマニフェストで、アドインに必要な各要件セットの 最小 バージョンを指定する必要があります。 これを行う方法の詳細については、この記事の後半で説明します。

ヒント

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

注:

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

要件セットに含まれていない API

アプリケーション固有のモデル内のすべての API は要件セットに含まれていますが、Common API モデルの API の一部は含まれていません。 また、アドインに必要な場合に、これらのセットレス API のいずれかをマニフェストで指定する方法もあります。 詳細については、この記事で後述します。

Requirements 要素

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

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

注:

<Requirements> 要素は、Outlook アドインを除くすべてのアドインでは省略可能です。ルート要素のxsi:type属性が である場合はMailApp、アドインに必要な<メールボックス要件>セットの最小バージョンを指定する Requirements 要素が必要です。OfficeApp 詳細については、「 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> 子要素と<メソッド子要素が>含まれています。
  • Sets> 要素には<、1 つ以上の <Set 要素を>含めることができます。 DefaultMinVersionは、すべての子 <Set 要素の既定値を>指定します。MinVersion
  • Set 要素は、アドインをインストールできるようにするために Office アプリケーションがサポートする必要がある要件セットを指定します。 属性は Name 、要件セットの名前を指定します。 は MinVersion 、要件セットの最小バージョンを指定します。 MinVersionは、親 Sets のDefaultMinVersion属性の値をオーバーライドします>。<
  • Methods> 要素には<、1 つ以上の Method 要素を含めることができます。 Outlook アドインで Methods> 要素を使用<することはできません。
  • Method> 要素は<、アドインをインストールできるようにするために Office アプリケーションがサポートする必要がある個々のメソッドを指定します。 Name属性は必須であり、その親オブジェクトで修飾されたメソッドの名前を指定します。

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

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

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

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

メソッドと要件セットのサポートのランタイム チェック

実行時にテストして、ユーザーの Office が isSetSupported メソッドで要件セットをサポートしているかどうかを検出します。 要件セットの名前と最小バージョンをパラメーターとして渡します。 要件セットがサポートされている場合は、 isSetSupported を返します true。 次のコードは一例です。

if (Office.context.requirements.isSetSupported('WordApi', '1.2'))
{
   // Code that uses API members from the WordApi 1.2 requirement set.
} else {
   // Provide diminished experience here. E.g., run alternate code when the user's Word is volume-licensed perpetual Word 2016 (which doesn't support WordApi 1.2).
}

このコードについては、以下の点に注意してください。

  • 最初のパラメーターが必要です。 これは、要件セットの名前を表す文字列です。 利用できる要件セットの詳細については、「Office アドインの要件セット」を参照してください。
  • 2 番目のパラメーターは省略可能です。 これは、ステートメント内 if のコードを実行するために Office アプリケーションがサポートする必要がある最小要件セット のバージョンを指定する文字列です (例: "1.9")。 使用しない場合は、バージョン "1.1" が想定されます。

警告

メソッドを isSetSupported 呼び出すとき、2 番目のパラメーターの値 (指定した場合) は数値ではなく文字列にする必要があります。 JavaScript パーサーは、1.1 や 1.10 などの数値を区別できません。一方、"1.1" や "1.10" などの文字列値の場合は区別できません。

次の表は、アプリケーション固有の API モデルの要件セット名を示しています。

Office アプリケーション RequirementSetName
Excel ExcelApi
OneNote OneNoteApi
Outlook Mailbox
PowerPoint PowerPointApi
Word WordApi

次に、共通 API モデル要件セットのいずれかで メソッドを使用する例を示します。

if (Office.context.requirements.isSetSupported('CustomXmlParts'))
{
    // Run code that uses API members from the CustomXmlParts requirement set.
}
else
{
    // Run alternate code when the user's Office application doesn't support the CustomXmlParts requirement set.
}

注:

これらのアプリケーションのメソッドと要件セットは isSetSupported 、CDN の最新の Office.js ファイルで使用できます。 CDN から Office.js を使用しない場合、未定義の古いバージョンのライブラリを使用している場合、アドインによって isSetSupported 例外が生成される可能性があります。 詳細については、「 最新の Office JavaScript API ライブラリを使用する」を参照してください。

アドインが要件セットの一部ではないメソッドに依存している場合は、次のコード例に示すように、ランタイム チェックを使用して、メソッドが Office アプリケーションでサポートされているかどうかを判断します。 要件セットに属さないメソッドの詳細な一覧については、「Office アドインの要件セット」を参照してください。

注:

アドインのコードでのこの種のランタイム チェックは、限定的に使用することをお勧めします。

次のコード例では、Office アプリケーションが をサポートしているかどうかを確認します document.setSelectedDataAsync。

if (Office.context.document.setSelectedDataAsync)
{
    // Run code that uses `document.setSelectedDataAsync`.
}

VersionOverrides 要素で要件を指定する

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

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

具体的には、ベース マニフェスト内の要素 (Hosts> 要素など<) をオーバーライドする VersionOverrides> の子要素は無視され、代わりにベース マニフェストの対応する要素が使用されます。< ただし、VersionOverrides には、基本マニフェストの設定を<オーバーライドするのではなく、実際に追加の機能を実装する子要素が存在する可能性があります。> と の 2 つの例を示WebApplicationInfoEquivalentAddinsします。 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 がサポートされていない場合、どちらのボタンもリボンに表示されません。 このシナリオでは、「 メソッドと要件セットのサポートのランタイム チェック」で説明されている手法を使用することをお勧めします。 2 番目のボタンによって呼び出されたコードは、最初に ExcelApi 1.9 のサポートをチェックするために使用isSetSupportedします。 サポートされていない場合は、アドインのこの機能が Office のバージョンでは使用できないというメッセージがユーザーに表示されます。

ヒント

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

関連項目