通过

使用仅外接程序清单指定 Office 应用程序和 API 要求

  • 项目

注意

有关使用 Microsoft 365 的统一清单指定要求的信息，请参阅 使用统一清单指定 Office 主机和 API 要求。

Office 加载项可能依赖于特定 Office 应用程序 (也称为 Office 主机) 或 Office JavaScript 库 (office.js) 的特定成员。 例如，你的外接程序可能：

  • 在单个 Office 应用程序 (运行，例如，Word、Excel) 或多个应用程序。
  • 使用仅在某些 Office 版本中可用的 Office JavaScript API。 例如，Excel 2016的批量许可永久版本不支持 Office JavaScript 库中所有与 Excel 相关的 API。

在这些情况下，你需要确保你的外接程序永远不会安装在 Office 应用程序或 Office 版本（不能运行它）上。

在某些情况下，你还希望根据用户的 Office 应用程序和 Office 版本控制加载项的哪些功能对用户可见。 两个示例如下：

  • 加载项具有在 Word 和 PowerPoint 中都有用的功能（如文本作），但它具有一些仅在 PowerPoint 中有意义的其他功能，例如幻灯片管理功能。 当加载项在 Word 中运行时，需要隐藏仅 PowerPoint 功能。
  • 加载项具有一项功能，该功能需要 Office JavaScript API 方法，该方法在某些版本的 Office 应用程序（如 Microsoft 365 订阅 Excel）中受支持，但不受其他版本的支持，例如批量许可永久Excel 2016。 但是，加载项具有其他功能，这些功能仅需要批量许可永久Excel 2016中支持的 Office JavaScript API 方法。 在此方案中，你需要在该版本的 Excel 2016 上安装加载项，但需要不受支持的方法的功能应该对这些用户隐藏。

本文可帮助你了解应选择的选项，以确保你的外接程序按预期运行，并遍及可能的最广泛的访问群体。

注意

有关 Office 加载项当前支持的位置的高级视图，请参阅 Office 外接程序的 Office 客户端应用程序和平台可用性 页。

提示

使用工具（例如 Office 外接程序的 Yeoman 生成器 或 Visual Studio 中的 Office 外接程序模板之一）创建外接程序项目时，本文所述的许多任务都是为你完成的。 在这种情况下，请将任务解释为，这意味着你应该验证它是否已完成。

使用最新的 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 web 版、Windows 和 iPad，但不能安装在任何其他 Office 应用程序上。

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

Hosts<> 元素可以包含一个或多个 <Host> 元素。 对于应可安装加载项的每个 Office 应用程序，应有一个单独的 <Host> 元素。 属性 Name 是必需的，可以设置为以下值之一。

名称 Office 客户端应用程序 可用的加载项类型
文档 web、Windows、Mac、iPad 上的Word 任务窗格
邮箱 Outlook 网页版、Windows (新的和经典) 、Mac、Android、iOS 邮件
笔记本 OneNote 网页版 任务窗格，内容
演示文稿 PowerPoint web 版、Windows、Mac、iPad 任务窗格，内容
项目 Windows 版 Project 任务窗格
工作簿 Excel web 版、Windows、Mac、iPad 任务窗格，内容
Database 访问 (过时) 任务窗格

注意

Office 应用程序在不同平台上受支持，并在桌面、Web 浏览器、平板电脑和移动设备上运行。 通常无法指定哪个平台可用于运行加载项。 例如，如果指定 Workbook，Excel web 版 和 Windows 上都可用于运行加载项。 但是，如果指定 Mailbox，则外接程序将不会在 Outlook 移动客户端上运行，除非你定义了 移动扩展点。

注意

仅外接程序清单不可能应用于多个类型：邮件、任务窗格或内容。 这意味着，如果希望外接程序可在 Outlook 和 Office 应用程序上安装，则必须创建 两 个加载项，一个具有邮件类型清单，另一个具有任务窗格或内容类型清单。

指定哪些 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 发布后，这些 API 与 DialogApi 1.1 中的所有 API 一起分组到 DialogApi 1.2 中。 要求集的每个版本都是所有早期版本的超集。

要求集支持因 Office 应用程序、Office 应用程序版本及其运行平台而异。 例如，在 Office 2021 之前，批量许可的 Office 永久版本不支持 DialogApi 1.2，但回到 Office 2016 的所有永久版本都支持 DialogApi 1.1。 你希望外接程序可在支持其使用的 API 的每种平台和 Office 版本组合上安装，因此应始终在清单中指定外接程序所需的每个要求集 的最低 版本。 本文稍后将详细介绍如何执行此作。

提示

有关要求集版本控制的详细信息，请参阅 Office 要求集可用性，有关要求集的完整列表以及每个要求集中 API 的信息，请从 Office 外接程序要求集开始。 大多数 Office.js API 的参考主题还指定它们属于 (（如果有任何) ）的要求集。

注意

某些要求集还具有与其关联的清单元素。 有关此事实何时与外接程序设计相关的信息，请参阅 在 VersionOverrides 元素中指定要求 。

Requirements 元素

使用 Requirements 元素及其子元素 Sets 指定 Office 应用程序必须支持的最低要求集才能安装外接程序。

应用程序特定模型中的所有 API 都在要求集中，但通用 API 模型中的一些 API 不在要求集中。 使用 方法 指定外接程序所需的无集 API 成员。 不能将 <Methods> 元素与 Outlook 外接程序一起使用。

如果 Office 应用程序或平台不支持 Requirements> 元素中指定的<要求集或 API 成员，则外接程序不会在该应用程序或平台中运行，并且不会显示在“我的外接程序”中。

注意

<Requirements> 元素对于除 Outlook 加载项之外的所有加载项都是可选的。xsi:type当根OfficeApp元素的 属性为 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> 元素可以包含一个或多个 <Set> 元素。 DefaultMinVersion指定所有子 <Set> 元素的默认值MinVersion。
  • Set 元素指定 Office 应用程序必须支持的要求集才能使加载项可安装。 属性 Name 指定要求集的名称。 指定 MinVersion 要求集的最低版本。 MinVersion重写父<集>中 DefaultMinVersion 属性的值。
  • Methods<> 元素可以包含一个或多个 Method 元素。 不能将 <Methods> 元素与 Outlook 外接程序一起使用。
  • <Method> 元素指定 Office 应用程序必须支持的单个方法，使加载项可安装。 属性 Name 是必需的，并指定使用其父对象限定的方法的名称。

针对备用体验进行设计

Office 外接程序平台提供的扩展性功能可以有效地分为三种类型：

如果外接程序对其某些功能使用特定的扩展性功能，但具有不需要扩展性功能的其他有用功能，则应设计外接程序，使其可安装在不支持扩展功能的平台和 Office 版本组合上。 它可以在这些组合上提供有价值的（尽管已减少）经验。

根据扩展性功能的实现方式，以不同的方式实现此设计：

在 VersionOverrides 元素中指定要求

VersionOverrides 元素主要添加到清单架构，但并非独占，以支持在安装加载项后必须立即可用的功能，例如外接程序命令 (自定义功能区按钮和菜单) 。 Office 在分析外接程序清单时必须了解这些功能。

假设外接程序使用这些功能之一，但加载项很有价值，并且应该可安装，即使在不支持该功能的 Office 版本上也是如此。 在此方案中，使用 Requirements 元素 (及其子 Sets 和 Methods 元素) 标识功能，这些元素作为 VersionOverrides> 元素本身的<子元素包含，而不是作为基OfficeApp元素的子元素包含。 这样做的效果是，Office 将允许安装加载项，但 Office 将忽略不支持此功能的 Office 版本中 VersionOverrides> 元素的某些子元素<。

具体而言，将忽略 VersionOverrides> 中<替代基本清单中的元素的子元素（如 <Hosts> 元素），并改用基本清单的相应元素。 但是，VersionOverrides> 中<可能存在实际实现其他功能的子元素，而不是替代基本清单中的设置。 两个示例是 WebApplicationInfo 和 EquivalentAddins。 假设平台和 Office 版本支持相应的功能，VersionOverrides> 的这些部分<不会被忽略。

有关 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> 元素之前<要小心谨慎。 在不支持要求的平台和版本组合上，将 不安装任何 外接程序命令， 即使那些调用不需要该要求的功能的外接程序命令也是如此。 例如，考虑具有两个自定义功能区按钮的加载项。 其中一个调用要求集 ExcelApi 1.4 (及更高版本) 中可用的 Office JavaScript API。 另一个调用仅在 ExcelApi 1.9 (及更高版本中可用的 API) 。 如果在 VersionOverrides> 中<提出了 ExcelApi 1.9 的要求，则当不支持 1.9 时，功能区上不会显示这两个按钮。 在此方案中，更好的策略是使用 在运行时检查 API 可用性中所述的技术。 第二个按钮调用的代码首先用于isSetSupported检查 ExcelApi 1.9 的支持。 如果不支持，代码会向用户显示一条消息，指出加载项的此功能在其 Office 版本中不可用。

提示

在基本清单中已出现的 VersionOverrides> 中<重复 <Requirement> 元素是没有意义的。 如果在基本清单中指定了要求，则外接程序无法安装，因为该要求不受支持，因此 Office 甚至不会分析 <VersionOverrides> 元素。

另请参阅