转换外接程序以使用 Microsoft 365 的统一清单

2025-06-20

若要将 Teams 功能或 Copilot 扩展添加到使用仅加载项清单的外接程序，或者为了将来证明外接程序，需要将其转换为使用 Microsoft 365 的统一清单。

注意

Microsoft 365 的统一清单可用于生产 Outlook 加载项。它仅作为 Excel、PowerPoint 和 Word 加载项的预览版提供。

将外接程序项目从仅外接程序清单转换为统一清单有三个基本任务。

确保清单已准备好进行转换。
将仅 XML 格式的外接程序清单本身转换为统一清单的 JSON 格式。
将新清单和两个图标映像文件打包 (稍后) 文件，以便旁加载或部署。 根据旁加载转换后的加载项的方式，此任务可能会自动完成。

注意

有关直接支持使用 Microsoft 365 统一清单的 Office 外接程序的客户端和平台的信息，请参阅具有 Microsoft 365 统一应用清单的 Office 外接程序。

注意

使用统一清单的加载项只能在 Office 版本 2304 (内部版本 16320.20000) 或更高版本上旁加载。
在 Visual Studio 中创建的项目与Visual Studio Code不同，目前无法转换。
如果使用 Teams 工具包或 Microsoft 365 代理工具包或 Office Yeoman 生成器中的“统一清单”选项创建了项目，则该项目已使用统一清单。

确保清单已准备好进行转换

以下部分介绍在转换清单之前必须满足的条件。

卸载加载项的现有版本

若要避免与 UI 控件名称冲突和其他问题，请确保在进行转换的计算机上未安装现有加载项。如果在卸载加载项时遇到任何困难，请参阅删除虚影加载项。

确保有两个特殊图像文件

如果仅外接程序清单中尚未将 <IconUrl> 和 <HighResolutionIconUrl (>) 元素，则将它们添加到 Description> 元素的<正下方。 DefaultValue 属性的值应该是图像文件的完整 URL。图像必须是指定的大小，如下表所示。

Office 应用程序	<IconUrl>	<HighResolutionIconUrl>
Outlook	64x64 像素	128x128 像素
所有其他 Office 应用程序	32x32 像素	64x64 像素

以下标记是一个示例。

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MailApp">
  <Id>01234567-89ab-cdef-0123-4567-89abcdef0123</Id>
  <Version>1.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-us</DefaultLocale>
  <DisplayName DefaultValue="Great Add-in"/>
  <Description DefaultValue="A great add-in."/>
  <IconUrl DefaultValue="https://localhost:3000/assets/icon-64.png" />
  <HighResolutionIconUrl DefaultValue="https://localhost:300/assets/icon-128.png" />

  <!-- Other markup omitted -->

根据需要减少外接程序命令的数量

使用统一清单的外接程序的加载项的外接程序命令不能超过 20 个。如果仅外接程序清单中的 Action> 元素总数<大于 20，则必须将外接程序重新设计为不超过 20 个。

更新清单中的外接程序 ID、版本、域和函数名称

将元素的值 <ID> 更改为新的随机 GUID。
更新元素的值 <Version> ，并确保它符合 semver 标准 (MAJOR。次要。PATCH) 。每个段的位数不能超过 5 位。例如，将值 1.0.0.0 更改为 1.0.1。不支持 semver 标准的预发行版和元数据版本字符串扩展。
请确保清单中加载项 URL 的域段指向 https://localhost:3000。
如果清单包含任何 <FunctionName> 元素，请确保其值少于 65 个字符。

重要

此元素的值必须与映射到 JavaScript 或 TypeScript 文件中的函数的作的名称与 Office.actions.associate 函数完全匹配。如果在清单中对其进行更改，请务必在传递给 associate() 的参数中actionId更改它。

根据需要缩短字符串值

根据转换的以下影响，根据需要查看和更改清单值。

的前 30 个字符 <DisplayName> 将成为统一清单中的值 "name.short" 。
的前 100 个字符 <DisplayName> 将成为统一清单中的值 "name.full" 。
的前 250 个字符 <Description> 将成为统一清单中的值 "description.short" 。
的前 4000 个字符 <Description> 将成为统一清单中的值 "description.full" 。
的前 32 个字符 <ProviderName> 将成为统一清单中的值 "developer.name" 。

验证修改后的仅加载项清单是否正常工作

验证修改后的仅外接程序清单。请参阅验证 Office 外接程序清单。
验证加载项是否可以旁加载并运行。请参阅旁加载 Office 加载项进行测试。

在尝试转换项目之前解决任何问题。

转换工具和选项

有多种方法可以执行剩余任务，具体取决于要用于项目的 IDE 和其他工具，以及用于创建项目的工具。

转换使用 Yeoman 生成器为 Office 加载项创建的项目 (又名“Yo Office”)
转换未使用 Yeoman 生成器为 Office 加载项创建的 NodeJS 和 npm 项目 (Yo Office)

注意

如果使用工具包的导入功能，则清单转换是将外接程序项目导入代理工具包的效果之一。有关详细信息，请参阅将外接程序项目导入代理工具包

转换使用 Office 加载项的 Yeoman 生成器创建的项目 (又名“Yo Office”)

如果项目是使用 Office 加载项的 Yeoman 生成器创建的，请使用以下步骤进行转换。

在项目的根目录中，打开命令提示符或 bash shell 并运行以下命令。这会转换清单并更新package.json以指定当前工具包。新的统一清单位于项目的根目录中，旧的仅外接程序清单位于 backup.zip 文件中。有关此命令的详细信息，请参阅 Office-Addin-Project。
```
npx office-addin-project convert -m <relative-path-to-XML-manifest>
```
运行 npm install。
若要旁加载加载项，请参阅使用 Yeoman 生成器为 Office 加载项 (Yo Office) 创建的旁加载加载项。

转换未使用 Yeoman 生成器为 Office 加载项创建的 NodeJS 和 npm 项目 (Yo Office)

如果你的项目不是使用 Yo Office 创建的，请使用 office-addin-manifest-converter 工具。

在项目的根目录中，打开命令提示符或 bash shell 并运行以下命令。此命令将统一清单置于子文件夹中，其名称与原始仅外接程序清单的文件名词干相同。例如，如果清单名为 MyManifest.xml，则会在 .\MyManifest\MyManifest.json 创建统一清单。有关此命令的更多详细信息，请参阅 Office-Addin-Manifest-Converter。

npx office-addin-manifest-converter convert <relative-path-to-XML-manifest>

创建统一清单后，可通过两种方法创建 zip 文件并旁加载它。有关详细信息，请参阅旁加载其他 NodeJS 和 npm 项目。

注意

如果原始外接程序仅清单使用任何 <Override> 元素来本地化清单中的字符串，则转换过程将为每个本地化语言生成 JSON 字符串文件。这些文件还必须包含在 zip 文件中，并且它们必须位于属性中 "localizationInfo.additionalLanguages.file" 指示的相对路径处。

后续步骤

考虑是否同时维护外接程序的旧版本和新版本。请参阅管理 Office 外接程序的统一清单和仅外接程序清单版本。

通过