Office のホストと API の要件を指定するSpecify Office hosts and API requirements

期待どおりの動作をするうえで、Office アドインは特定の Office ホスト、要件セット、API メンバー、または API のバージョンに依存することがあります。たとえば、次のようなアドインがあります。Your Office Add-in might depend on a specific Office host, a requirement set, an API member, or a version of the API in order to work as expected. For example, your add-in might:

  • 1 つの Office アプリケーション (例: Word または Excel)、またはいくつかのアプリケーションで実行します。Run in a single Office application (Word or Excel), or several applications.

  • Office の一部のバージョンでのみ利用できる JavaScript API を使用します。たとえば、Excel 2016 で実行するアドインでは、Excel JavaScript API を使用することがあります。Make use of JavaScript APIs that are only available in some versions of Office. For example, you might use the Excel JavaScript APIs in an add-in that runs in Excel 2016.

  • アドインが使用する API メンバーをサポートするバージョンの Office でのみ実行します。Run only in versions of Office that support API members that your add-in uses.

この記事は、アドインが期待どおりに機能し、できるだけ多くのユーザーが利用できるようにするために選択する必要のあるオプションについて理解するのに役立ちます。This article helps you understand which options you should choose to ensure that your add-in works as expected and reaches the broadest audience possible.

注意

現時点での Office アドインのサポート状況の概要については、「Office アドインを使用できるホストおよびプラットフォーム」のページを参照してください。For a high-level view of where Office Add-ins are currently supported, see the Office Add-in host and platform availability page.

この記事で説明する中心的な概念を次の表に示します。The following table lists core concepts discussed throughout this article.

概念Concept 説明Description
Office アプリケーション、Office ホスト アプリケーション、Office ホスト、またはホストOffice application, Office host application, Office host, or host アドインの実行に使用される Office アプリケーション。たとえば、Word や Excel など。The Office application used to run your add-in. For example, Word, Word Online, Excel, and so on.
プラットフォームPlatform Office ホストを実行する場所。ブラウザーや iPad など。Where the Office host runs, such as in a browser or on an iPad.
要件セットRequirement set 関連する API メンバーの名前付きグループ。アドインは要件セットを使用して、Office ホストが、アドインによって使用される API メンバーをサポートしているかどうかを判別します。個々の API メンバーのサポートをテストするよりも、要件セットのサポートをテストするほうが簡単です。要件セットのサポートは、Office ホストと Office ホストのバージョンによって異なります。 A named group of related API members. Add-ins use requirement sets to determine whether the Office host supports API members used by your add-in. It's easier to test for the support of a requirement set than for the support of individual API members. Requirement set support varies by Office host and the version of the Office host.
要件セットはマニフェスト ファイルで指定されます。Requirement sets are specified in the manifest file. マニフェストで要件セットを指定するときは、アドインを実行するために Office ホストが提供する必要のある最小レベルの API サポートを設定します。When you specify requirement sets in the manifest, you set the minimum level of API support that the Office host must provide in order to run your add-in. マニフェストで指定されている要件セットをサポートしていない Office ホストはアドインを実行できず、アドインは [個人用アドイン] に表示されません。これにより、アドインが利用できる場所が制限されます。Office hosts that don't support requirement sets specified in the manifest can't run your add-in, and your add-in won't display in My Add-ins. This restricts where your add-in is available.In code using runtime checks. コードでは、ランタイム チェックを使用します。In code using runtime checks. 要件セットの詳細な一覧については、「Office アドインの要件セット」を参照してください。For the complete list of requirement sets, see Office Add-in requirement sets.
ランタイム チェックRuntime check アドインを実行している Office ホストが、アドインで使用されている要件セットまたはメソッドをサポートしているかどうかを判別するために実行時に行われるテスト。A test that is performed at runtime to determine whether the officenvshort host running your addin supports requirement sets or methods used by your off15app. ランタイム チェックを実行するには、if ステートメントを isSetSupported メソッド、要件セット、要件セットの一部でないメソッド名を指定して使用します。To perform a runtime check, you use an if statement with the isSetSupported method, the requirement sets, or the method names that aren't part of a requirement set. ランタイム チェックを使用すると、アドインを、最も多くのお客様が利用できるものにできます。Use runtime checks to ensure that your addin reaches the broadest number of customers. 要件セットとは異なり、ランタイム チェックでは、対象アドインを実行するために Office ホストが提供する必要のある最小レベルの API サポートは指定しません。Unlike requirement sets, runtime checks don't specify the minimum level of API support that the officenvshort host must provide for your addin to run. 代わりに、if ステートメントを使用して API メンバーがサポートされているかどうかを判別します。Instead, you use the if statement to determine whether an API member is supported. サポートされている場合には、アドインで追加機能を提供できます。If it is, you can provide additional functionality in your addin. ランタイム チェックを使用するときは、自分のアドインは必ず [個人用アドイン] に表示されます。Your off15app will always display in My Add-ins when you use runtime checks.

始める前にBefore you begin

アドインで最新バージョンのアドイン マニフェスト スキーマを使用する必要があります。アドインでランタイム チェックを使用する場合は、最新の JavaScript API for Office (office.js) ライブラリを使用する必要があります。Your add-in must use the most current version of the add-in manifest schema. If you use runtime checks in your add-in, ensure that you use the latest JavaScript API for Office (office.js) library.

最新のアドイン マニフェスト スキーマを指定するSpecify the latest add-in manifest schema

アドインのマニフェストでは、アドイン マニフェスト スキーマのバージョン 1.1 を使用する必要があります。アドイン マニフェストの OfficeApp 要素を次のように設定します。Your add-in's manifest must use version 1.1 of the add-in manifest schema. Set the OfficeApp element in your add-in manifest as follows.

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:type="TaskPaneApp">

最新の JavaScript API for Office ライブラリを指定するSpecify the latest JavaScript API for Office library

ランタイム チェックを使用する場合、コンテンツ配信ネットワーク (CDN) から JavaScript API for Office ライブラリの最新版を参照します。その場合、HTML に次の script タグを追加します。CDN URL で /1/ を使用することで、Office.js の最新版が参照されます。If you use runtime checks, reference the most current version of the JavaScript API for Office library from the content delivery network (CDN). To do this, add the following script tag to your HTML. Using /1/ in the CDN URL ensures that you reference the most recent version of Office.js.

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

Office のホストや API の要件を指定するオプションOptions to specify Office hosts or API requirements

Office ホストまたは API の要件を指定するときに、検討すべき事項がいくつかあります。次の図に、アドインで使用すべき手法の判別方法を示します。When you specify Office hosts or API requirements, there are several factors to consider. The following diagram shows how to decide which technique to use in your add-in.

Office のホストまたは API の要件を指定する際に、アドインに最適なオプションを選択する

  • アドインを 1 つの Office ホストで実行する場合、マニフェストに Hosts 要素を設定します。詳しくは、「Hosts 要素を設定する」を参照してください。If your add-in runs in one Office host, set the Hosts element in the manifest. For more information, see Set the Hosts element.

  • アドインを実行するために Office ホストがサポートする必要のある最小レベルの要件セットまたは API メンバーを設定するには、マニフェストに Requirements 要素を設定します。詳しくは、「マニフェストで Requirements 要素を設定する」をご覧ください。To set the minimum requirement set or API members that an Office host must support to run your add-in, set the Requirements element in the manifest. For more information, see Set the Requirements element in the manifest.

  • Office ホストで特定の要件セットまたは API メンバーが利用可能である場合に追加の機能を提供する場合は、アドインの JavaScript コードでランタイム チェックを実行します。If you would like to provide additional functionality if specific requirement sets or API members are available in the Office host, perform a runtime check in your add-in's JavaScript code. たとえば、アドインが Excel 2016 で機能する場合は、Excel JavaScript API の API メンバーを使用して追加の機能を提供します。For example, if your add-in runs in Excel 2016, use API members from the new JavaScript API for Excel to provide additional functionality. 詳細については、「JavaScript コードでランタイム チェックを使用する」をご覧ください。For more information, see Use runtime checks in your JavaScript code.

Hosts 要素を設定するSet the Hosts element

アドインを 1 つの Office ホスト アプリケーションで実行するには、マニフェストで Hosts 要素と Host 要素を使用します。Hosts 要素を指定しない場合、アドインはすべてのホストで実行されます。To make your add-in run in one Office host application, use the Hosts and Host elements in the manifest. If you don't specify the Hosts element, your add-in will run in all hosts.

たとえば、次の HostsHost の宣言は、アドインが Excel のすべてのリリース (Excel on the web、Windows、および iPad を含む) で動作することを示しています。For example, the following Hosts and Host declaration specifies that the add-in will work with any release of Excel, which includes Excel on Windows, Excel Online, and Excel for iPad.

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

Hosts 要素には、1 つ以上の Host 要素を含めることができます。Host 要素は、アドインで必要な Office ホストを指定します。Name 属性は必須で、次のいずれかの値に設定できます。The Hosts element can contain one or more Host elements. The Host element specifies the Office host your add-in requires. The Name attribute is required and can be set to one of the following values.

名前Name Office ホスト アプリケーションOffice host applications
データベースDatabase Access Web アプリAccess web apps
ドキュメントDocument Windows 用 Word、Mac 用 Word、iPad 用 Word、Word on the webWord on Windows, Word on Mac, Word on iPad, Word on the web
MailboxMailbox Outlook on Windows、Outlook on Mac、Outlook on the web、Outlook on Android、Outlook on iOSOutlook on Windows, Outlook on Mac, Outlook on the web, Outlook on Android, Outlook on iOS
PresentationPresentation Windows 用 PowerPoint、Mac 用 PowerPoint、iPad 用 PowerPoint、PowerPoint on the webPowerPoint on Windows, PowerPoint on Mac, PowerPoint on iPad, PowerPoint on the web
ProjectProject Windows での ProjectProject 2016 or later on Windows
WorkbookWorkbook Windows 用 Excel、Mac 用 Excel、iPad 用 Excel、Excel on the webExcel on Windows, Excel on Mac, Excel on iPad, Excel on the web

注意

Name 属性により、アドインを実行できる Office ホスト アプリケーションが指定されます。The Name attribute specifies the Office host application that can run your add-in. Office ホストはさまざまなプラットフォームに対応しており、デスクトップ、Web ブラウザー、タブレット、モバイル デバイスで実行できます。Office hosts are supported on different platforms and run on desktops, web browsers, tablets, and mobile devices. アドインを実行するために使用するプラットフォームを指定することはできません。You can't specify which platform can be used to run your add-in. たとえば、Mailbox を指定した場合は、アドインの実行に Windows 用 Outlook と Outlook on the web の両方を使用できます。For example, if you specify Mailbox, both Outlook and Outlook Web App can be used to run your add-in.

重要

SharePoint で Access Web アプリとデータベースを作成して使用することは推奨されなくなりました。We no longer recommend that you create and use Access web apps and databases in SharePoint. 代わりに、Microsoft PowerApps を使用して、コード作成が不要な Web とモバイル デバイス用ビジネス ソリューションをビルドすることをお勧めします。As an alternative, we recommend that you use Microsoft PowerApps to build no-code business solutions for web and mobile devices.

マニフェストで Requirements 要素を設定するSet the Requirements element in the manifest

Requirements 要素は、アドインを実行するために Office ホストによってサポートされている必要がある最小要件セットまたは API メンバーを指定します。Requirements 要素は、アドインで使用される要件セットと個々のメソッドの両方を指定できます。アドイン マニフェスト スキーマのバージョン 1.1 では、Requirements 要素は Outlook アドイン以外のすべてのアドインで省略可能です。The Requirements element specifies the minimum requirement sets or API members that must be supported by the Office host to run your add-in. The Requirements element can specify both requirement sets and individual methods used in your add-in. In version 1.1 of the add-in manifest schema, the Requirements element is optional for all add-ins, except for Outlook add-ins.

警告

アドインで必須の重要な要件セットまたは API メンバーを指定するには、Requirements 要素のみを使用します。Only use the Requirements element to specify critical requirement sets or API members that your add-in must use. Office ホストまたはプラットフォームが、Requirements 要素で指定した要件セットまたは API メンバーをサポートしない場合、アドインはそのホストまたはプラットフォームでは実行されず、[個人用アドイン] にも表示されません。そうならないように、Office ホストのすべてのプラットフォーム (Excel on the web、Windows、iPad など) でアドインが使用できるようにしてください。If the Office host or platform doesn't support the requirement sets or API members specified in the Requirements element, the add-in won't run in that host or platform, and won't display in My Add-ins. Instead, we recommend that you make your add-in available on all platforms of an Office host, such as Excel for Windows, Excel Online, and Excel for iPad. _すべて_の Office ホストとプラットフォームでアドインを使用できるようにするには、Requirements 要素ではなく、ランタイム チェックを使用します。To make your add-in available on all Office hosts and platforms, use runtime checks instead of the Requirements element.

次のものをサポートするすべての Office ホスト アプリケーションで読み込まれるアドインのコード例を以下に示します。The following code example shows an add-in that loads in all Office host applications that support the following:

  • TableBindings 要件セット。最小バージョンは "1.1"。TableBindings requirement set, which has a minimum version of 1.1.

  • OOXML 要件セット。最小バージョンは "1.1"。OOXML requirement set, which has a minimum version of 1.1.

  • Document.getSelectedDataAsync メソッド。Document.getSelectedDataAsync method.

<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>
  • Requirements 要素には Sets 子要素と Methods 子要素が含まれます。The Requirements element contains the Sets and Methods child elements.

  • Sets 要素には、1 つ以上の Set 要素を含めることができます。DefaultMinVersion は、すべての Set 子要素の MinVersion の既定値を指定します。The Sets element can contain one or more Set elements. DefaultMinVersion specifies the default MinVersion value of all child Set elements.

  • Set 要素は、アドインを実行するために Office ホストがサポートする必要のある要件セットを指定します。The Set element specifies requirement sets that the Office host must support to run the add-in. Name 属性は、要件セットの名前を指定します。The Name attribute specifies the name of the requirement set. MinVersion は、要件セットの最小バージョンを指定します。The MinVersion specifies the minimum version of the requirement set. MinVersion は、DefaultMinVersion の値よりも優先されます。MinVersion overrides the value of DefaultMinVersion. 要件セットと API メンバーが属する要件セットのバージョンの詳細については、「「Office アドインの要件セット」を参照してください。For more information about requirement sets and requirement set versions that your API members belong to, see Office Add-in requirement sets.

  • Methods 要素には、1 つ以上の Method 要素を含めることができます。Outlook アドインで Methods 要素を使用することはできません。The Methods element can contain one or more Method elements. You can't use the Methods element with Outlook add-ins.

  • Method 要素は、アドインが実行される Office ホストでサポートされている必要のある個々のメソッドを指定します。Name 属性は必須であり、親オブジェクトで修飾されたメソッドの名前を指定します。The Method element specifies an individual method that must be supported in the Office host where your add-in runs. The Name attribute is required and specifies the name of the method qualified with its parent object.

JavaScript コードでランタイム チェックを使用するUse runtime checks in your JavaScript code

特定の要件セットが Office ホストでサポートされる場合、追加の機能を提供すると効果的な場合があります。You might want to provide additional functionality in your add-in if certain requirement sets are supported by the Office host. たとえば、アドインで Word 2016 を実行する場合、既存のアドインで Word JavaScript API を使用することがあります。For example, you might want to use the new Word JavaScript APIs Word in your existing add-in if your add-in runs in Word 2016. その場合、要件セットの名前を指定し、isSetSupported メソッドを使用します。To do this, you use the isSetSupported method with the name of the requirement set. isSetSupported により実行時に、アドインを実行する Office ホストが要件セットをサポートするかどうかが判断されます。isSetSupported determines, at runtime, whether the Office host running the add-in supports the requirement set. 要件セットがサポートされる場合、isSetSupportedtrue を返し、その要件セットから API メンバーを使用する追加コードを実行します。If the requirement set is supported, isSetSupported returns true and runs the additional code that uses the API members from that requirement set. Office ホストで要件セットがサポートされない場合、isSetSupportedfalse を返し、追加コードは実行されません。If the Office host doesn't support the requirement set, isSetSupported returns false and the additional code won't run. 次のコードは、isSetSupported と共に使用する構文を示しています。The following code shows the syntax to use with isSetSupported.

if (Office.context.requirements.isSetSupported(RequirementSetName, MinimumVersion))
{
   // Code that uses API members from RequirementSetName.
}

  • RequirementSetName (必須) は、要件セットの名前を表す文字列です (例: "ExcelApi"、"Mailbox" など)。RequirementSetName (required) is a string that represents the name of the requirement set. 利用できる要件セットの詳細については、「Office アドインの要件セット」を参照してください。For more information about available requirement sets, see Office Add-in requirement sets.
  • MinimumVersion (省略可能) では、if ステートメントの範囲内でコードを実行するために、ホストがサポートする必要がある最小要件セットのバージョンを指定します (例: "1.9")。MinimumVersion (optional) is a string that specifies the minimum requirement set version that the host must support in order for the code within the if statement to run (e.g., "1.9").

警告

isSetSupported メソッドを呼び出すときに、 MinimumVersion パラメーターの値 (指定された場合) は、文字列にする必要があります。 When calling the isSetSupported method, the value of the MinimumVersion parameter (if specified) should be a string. これは、JavaScript パーサーでは、1.1 や 1.10 のような数値の間の差異を区別できないが、"1.1" や "1.10" などの文字列値ではできるからです。This is because the JavaScript parser cannot differentiate between numeric values such as 1.1 and 1.10, where as it can for string values such as "1.1" and "1.10". number のオーバーロードは非推奨になります。The number overload is deprecated.

次のように、Office ホストに関連付けられている RequirementSetNameisSetSupported を使用します。Use isSetSupported with the RequirementSetName associated with the Office host as follows.

Office ホストOffice host RequirementSetNameRequirementSetName
ExcelExcel ExcelApiExcelApi
OneNoteOneNote OneNoteApiOneNoteApi
OutlookOutlook MailboxMailbox
WordWord WordApiWordApi

isSetSupported メソッドおよびこれらの要件セットは、CDN の最新の Office.js ファイルで利用できます。The isSetSupported method, and the ExcelAPI and WordAPI requirement sets, are available in the latest Office.js file available from the CDN. CDN の Office.js を使用しない場合、アドインで例外が表示されることがあります。isSetSupported が定義されていないためです。If you don't use Office.js from the CDN, your add-in might generate exceptions because isSetSupported will be undefined. 詳細については、「最新の JavaScript API for Office ライブラリを指定する」を参照してください。For more information, see Specify the latest JavaScript API for Office library.

次のコードの例は、さまざまな要件セットや API メンバーをサポートするさまざまな Office ホストにおいて、アドインで各種の機能を提供する方法を示しています。The following code example shows how an add-in can provide different functionality for different Office hosts that might support different requirement sets or API members.

if (Office.context.requirements.isSetSupported('WordApi', '1.1'))
{
    // Run code that provides additional functionality using the Word JavaScript API when the add-in runs in Word 2016 or later.
}
else if (Office.context.requirements.isSetSupported('CustomXmlParts'))
{
    // Run code that uses API members from the CustomXmlParts requirement set.
}
else
{
    // Run additional code when the Office host is not Word 2016 or later and does not support the CustomXmlParts requirement set.
}

要件セットにないメソッドを使用したランタイム チェックRuntime checks using methods not in a requirement set

API の一部のメンバーは、要件のセットに属していません。Some API members don't belong to requirement sets. これは JavaScript API for Office 名前空間 (Outlook Mailbox API を除く Office. で始まるすべての名前空間) に属する API メンバーにのみ適用され、Word JavaScript API 名前空間 (Word. で始まるすべての名前空間)、Excel JavaScript API 名前空間 (Excel. で始まるすべての名前空間) や OneNote JavaScript API (OneNote. で始まるすべての名前空間) に属する API メンバーには適用されません。This only applies to API members that are part of the JavaScript API for Office namespace (anything under Office.), not API members that belong to the Word JavaScript API (anything in Word.) or Excel add-ins JavaScript API reference (anything in Excel.) namespaces. 要件セットに属さないメソッドにアドインが依存するとき、ランタイム チェックを利用し、メソッドが Office ホストでサポートされているかどうかを判断できます。たとえば、次のコード例のようになります。When your add-in depends on a method that is not part of a requirement set, you can use the runtime check to determine whether the method is supported by the Office host, as shown in the following code example. 要件セットに属さないメソッドの詳細な一覧については、「Office アドインの要件セット」を参照してください。For a complete list of methods that don't belong to a requirement set, see Office Add-in requirement sets.

注意

アドインのコードでのこの種のランタイム チェックは、限定的に使用することをお勧めします。We recommend that you limit the use of this type of runtime check in your add-in's code.

次のコードの例は、ホストが document.setSelectedDataAsync をサポートしているかどうかをチェックします。The following code example checks whether the host supports document.setSelectedDataAsync.

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

関連項目See also