指定 Office 应用程序和 API 要求Specify Office applications and API requirements

Office 外接程序可能依赖于特定的 Office 应用程序、要求集、API 成员或 API 版本才能按预期工作。Your Office Add-in might depend on a specific Office application, a requirement set, an API member, or a version of the API in order to work as expected. 例如,你的外接程序可能:For example, your add-in might:

  • 在单个 Office 应用程序(如,Word 或 Excel)或多个应用程序中运行。Run in a single Office application (e.g., 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.

  • 只能在 Office 的某些版本中运行,这些版本支持供你的外接程序使用的 API 成员。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 外接程序的 Office 客户端应用程序和平台 可用性 页面。For a high-level view of where Office Add-ins are currently supported, see the Office client application and platform availability for Office Add-ins page.

下表列出了本文中讨论的核心概念。The following table lists core concepts discussed throughout this article.

概念Concept 说明Description
Office 应用程序、Office 客户端应用程序Office application, Office client application 用于运行加载项的 Office 应用程序。例如 Word、Excel 等。The Office application used to run your add-in. For example, Word, Excel, and so on.
平台Platform Office 应用程序的运行位置,例如浏览器或 iPad。Where the Office application runs, such as in a browser or on an iPad.
要求集Requirement set 命名的一组相关的 API 成员。A named group of related API members. 外接程序使用要求集来确定 Office 应用程序是否支持外接程序使用的 API 成员。Add-ins use requirement sets to determine whether the Office application supports API members used by your add-in. 测试对要求集的支持比对单个的 API 成员的支持更为容易。It's easier to test for the support of a requirement set than for the support of individual API members. 要求集支持因 Office 应用程序和 Office 应用程序的版本而异。Requirement set support varies by Office application and the version of the Office application.
要求集在清单文件中指定。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 application must provide in order to run your add-in. 不支持清单中指定的要求集的 Office 应用程序无法运行您的外接程序,并且您的外接程序不会显示在"我的外接程序 "中。这将限制加载项的可用位置。Office applications 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. 有关要求集的完整列表,请参阅 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 Office application running your add-in supports requirement sets or methods used by your add-in. 若要执行运行时检查,请使用 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 add-in reaches the broadest number of customers. 与要求集不同,运行时检查不会指定 Office 应用程序必须为外接程序运行提供的最低级别的 API 支持。Unlike requirement sets, runtime checks don't specify the minimum level of API support that the Office application must provide for your add-in 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 add-in. 使用运行时检查时,你的外接程序将始终在“我的外接程序”中显示。Your add-in will always display in My Add-ins when you use runtime checks.

开始之前Before you begin

您的外接程序必须使用最新版本的外接程序清单架构。Your add-in must use the most current version of the add-in manifest schema. 如果在外接程序中使用运行时检查,请确保使用最新的 Office JavaScript API (office.js) 库。If you use runtime checks in your add-in, ensure that you use the latest Office JavaScript API (office.js) library.

指定最新的外接程序清单架构Specify the latest add-in manifest schema

外接程序清单必须使用外接程序清单架构版本 1.1。Your add-in's manifest must use version 1.1 of the add-in manifest schema. OfficeApp 如下方式设置外接程序清单中的元素。Set the OfficeApp element in your add-in manifest as follows.

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

指定最新的 Office JavaScript API 库Specify the latest Office JavaScript API library

如果使用运行时检查,请从 CDN 服务器的内容交付网络引用 Office JavaScript API 库 (最新版本) 。If you use runtime checks, reference the most current version of the Office JavaScript API library from the content delivery network (CDN). 若要执行此操作,请将以下 script 标记添加到 HTML 中。To do this, add the following script tag to your HTML. 使用 CDN URL 中的 /1/ 可以确保引用的是最新版本的 Office.js。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 applications or API requirements

指定 Office 应用程序或 API 要求时,有几个因素需要考虑。When you specify Office applications 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 要求时,为外接程序选择最佳选项

  • 如果加载项在一个 Office 应用程序中运行,请设置 Hosts 清单中的元素。If your add-in runs in one Office application, set the Hosts element in the manifest. 有关详细信息,请参阅 设置 Hosts 元素For more information, see Set the Hosts element.

  • 若要设置 Office 应用程序运行加载项时必须支持的最低要求集或 API 成员,请设置 Requirements 清单中的元素。To set the minimum requirement set or API members that an Office application must support to run your add-in, set the Requirements element in the manifest. 有关详细信息,请参阅在清单中设置 Requirements 元素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 application, 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 Excel JavaScript API to provide additional functionality. 有关详细信息,请参阅在你的 JavaScript 代码中使用运行时检查For more information, see Use runtime checks in your JavaScript code.

设置 Hosts 元素Set the Hosts element

若要使外接程序在一个 Office 客户端应用程序中运行,请使用 Hosts 清单中的 and Host 元素。To make your add-in run in one Office client application, use the Hosts and Host elements in the manifest. 如果不指定元素,加载项将在 Office 加载项支持的所有 Office 应用程序中 Hosts 运行。If you don't specify the Hosts element, your add-in will run in all Office applications supported by Office Add-ins.

例如,以下和声明指定外接程序将适用于任何 Excel 版本,其中包括 Hosts Excel 网页版、Windows 版和 Host 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 the web, Windows, and iPad.

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

Hosts 元素可以包含一个或多个 Host 元素。The Hosts element can contain one or more Host elements. Host 元素指定加载项所需的 Office 应用程序。The Host element specifies the Office application your add-in requires. Name该属性是必需的,可以设置为下列值之一。The Name attribute is required and can be set to one of the following values.

名称Name Office 客户端应用程序Office client applications
数据库Database Access Web AppAccess web apps
文档Document Word 网页、Windows、Mac、iPadWord on the web, Windows, Mac, iPad
邮箱Mailbox Outlook 网页版、Windows、Mac、Android、iOSOutlook on the web, Windows, Mac, Android, iOS
演示文稿Presentation PowerPoint 网页、Windows、Mac、iPadPowerPoint on the web, Windows, Mac, iPad
项目Project Windows 版 ProjectProject on Windows
工作簿Workbook Excel 网页、Windows、Mac、iPadExcel on the web, Windows, Mac, iPad

备注

该属性 Name 指定可以运行加载项的 Office 客户端应用程序。The Name attribute specifies the Office client application that can run your add-in. Office 应用程序在不同的平台上受支持,并且运行在台式机、Web 浏览器、平板电脑和移动设备上。Office applications 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. 例如,如果指定,则 Web 上的 Outlook 和 Windows 上的 Outlook 均可用于 Mailbox 运行加载项。For example, if you specify Mailbox, both Outlook on the web and on Windows 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

该元素指定运行外接程序时 Office 应用程序必须支持的最低要求集 Requirements 或 API 成员。The Requirements element specifies the minimum requirement sets or API members that must be supported by the Office application to run your add-in. Requirements 元素可以指定要求集和外接程序中使用的单个方法。The Requirements element can specify both requirement sets and individual methods used in your add-in. 在外接程序清单架构的版本 1.1 中,该元素对于除 Outlook 外接程序之外的所有加载项 Requirements 都是可选的。In version 1.1 of the add-in manifest schema, the Requirements element is optional for all add-ins, except for Outlook add-ins.

警告

仅使用此元素指定加载项必须使用的关键要求集 Requirements 或 API 成员。Only use the Requirements element to specify critical requirement sets or API members that your add-in must use. 如果 Office 应用程序或平台不支持元素中指定的要求集或 API 成员,加载项将不会在应用程序或平台中运行,也不会显示在"我的外接程序 Requirements "中。相反,我们建议你在 Office 应用程序的所有平台上(如 Web 上的 Excel、Windows 和 iPad)上提供加载项。If the Office application or platform doesn't support the requirement sets or API members specified in the Requirements element, the add-in won't run in that application 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 application, such as Excel on the web, Windows, and iPad. 若要使加载项在所有 Office 应用程序和平台上可用,请使用运行时检查而不是 Requirements 元素。To make your add-in available on all Office applications and platforms, use runtime checks instead of the Requirements element.

以下代码示例显示了一个外接程序,该加载项在支持以下功能的所有 Office 客户端应用程序中加载:The following code example shows an add-in that loads in all Office client 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 包含 SetsMethods 子元素。The Requirements element contains the Sets and Methods child elements.

  • Sets 元素可以包含一个或多个 Set 元素。The Sets element can contain one or more Set elements. DefaultMinVersion 指定所有 MinVersion 子元素的 Set 默认值。DefaultMinVersion specifies the default MinVersion value of all child Set elements.

  • 该元素指定 Office 应用程序必须支持的要求集以 Set 运行外接程序。The Set element specifies requirement sets that the Office application 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 替代 API 成员所属的要求集和要求集版本详细信息,请参阅 DefaultMinVersion Office 外接程序要求集MinVersion overrides the value of DefaultMinVersion For more information about requirement sets and requirement set versions that your API members belong to, see Office Add-in requirement sets.

  • Methods 元素可以包含一个或多个 Method 元素。无法将元素 Methods 与 Outlook 外接程序一同使用。The Methods element can contain one or more Method elements. You can't use the Methods element with Outlook add-ins.

  • 该元素指定在运行加载项的 Office 应用程序中必须支持的 Method 单个方法。该属性是必需的,并指定使用其父 Name 对象限定的方法的名称。The Method element specifies an individual method that must be supported in the Office application 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 application. 例如,如果你的加载项在 Word 2016 中运行,则你可能想要在现有的加载项中使用 Word JavaScript API。For example, you might want to use the Word JavaScript APIs 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 application running the add-in supports the requirement set. 如果支持要求集,则返回 true 并运行使用该要求集 isSetSupported 的 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 应用程序不支持要求集,则返回 isSetSupported false, 其他代码将不会运行。If the Office application doesn't support the requirement set, isSetSupported returns false and the additional code won't run. 以下代码显示要用于的语法 isSetSupportedThe 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 (e.g., "ExcelApi", "Mailbox", etc.). 有关可用要求集的详细信息,请参阅 Office 加载项要求集For more information about available requirement sets, see Office Add-in requirement sets.
  • MinimumVersion (可选) 是一个字符串,指定 Office 应用程序必须支持的最低要求集版本,以便语句中的代码运行 (例如 if "1.9") 。MinimumVersion (optional) is a string that specifies the minimum requirement set version that the Office application 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.

isSetSupported Office RequirementSetName 应用程序关联的使用,如下所示。Use isSetSupported with the RequirementSetName associated with the Office application as follows.

Office 应用程序Office application RequirementSetNameRequirementSetName
ExcelExcel ExcelApiExcelApi
OneNoteOneNote OneNoteApiOneNoteApi
OutlookOutlook MailboxMailbox
WordWord WordApiWordApi

这些应用程序的方法和要求集在 CDN 上Office.js isSetSupported 文件提供。The isSetSupported method and the requirement sets for these applications are available in the latest Office.js file on 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. 有关详细信息,请参阅"指定最新的 Office JavaScript API 库"。For more information, see Specify the latest Office JavaScript API library.

以下代码示例演示外接程序如何为可能支持不同要求集或 API 成员的不同 Office 应用程序提供不同的功能。The following code example shows how an add-in can provide different functionality for different Office applications 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 application 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. 这仅适用于属于 Office JavaScript API命名空间的 API 成员 (除了 Outlook 邮箱 API) 之外的任何内容,但不包括属于) 中的 Word JavaScript API (任何内容、) 中的 Excel JavaScript API (任何内容或) 命名空间中的 Office. Word. Excel. OneNote JavaScript API OneNote. (任何内容。This only applies to API members that are part of the Office JavaScript API namespace (anything under Office. except Outlook Mailbox APIs), but not API members that belong to the Word JavaScript API (anything in Word.), Excel JavaScript API (anything in Excel.), or OneNote JavaScript API (anything in OneNote.) 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 application, 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.

下面的代码示例检查 Office 应用程序是否支持 document.setSelectedDataAsyncThe following code example checks whether the Office application supports document.setSelectedDataAsync.

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

另请参阅See also