次の方法で共有

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 など) でサポートされる Office JavaScript API メソッドが必要な機能がありますが、ボリューム ライセンスの永続的な Excel 2016 など、他のバージョンではサポートされていません。 ただし、アドインには、ボリューム ライセンスの永続的な 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.1/hosted/office.js" type="text/javascript"></script>

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

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

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

たとえば、次の <Hosts>と <Host> 宣言では、Web、Windows、iPad 上の Excel を含む Excel の任意のリリースにアドインをインストールできますが、他の Office アプリケーションにはインストールできません。

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

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

名前 Office クライアント アプリケーション 使用可能なアドインの種類
ドキュメント Word on the web, Windows, Mac, iPad 作業ウィンドウ
Mailbox Outlook on the web, Windows (新規 およびクラシック), Mac, Android, iOS メール
Notebook OneNote on the web 作業ウィンドウ、コンテンツ
Presentation Web 上のPowerPoint、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 要素での要件の指定 」を参照してください。

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

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

Requirements 要素

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

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 のバージョンの組み合わせにインストールできるようにアドインを設計する必要があります。 これらの組み合わせに関する貴重な、減少したエクスペリエンスを提供できます。

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

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

実行時にテストして、ユーザーの 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 は機能がサポートされていない 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 がサポートされていない場合、どちらのボタンもリボンに表示されません。 このシナリオでは、「 メソッドと要件セットのサポートのランタイム チェック」で説明されている手法を使用することをお勧めします。 2 番目のボタンによって呼び出されたコードは、最初に isSetSupported を使用して ExcelApi 1.9 のサポートを確認します。 サポートされていない場合は、アドインのこの機能が Office のバージョンでは使用できないというメッセージがユーザーに表示されます。

ヒント

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

関連項目