具有 Microsoft 365 统一应用清单的 Office 加载项
本文介绍 Microsoft 365 的统一应用清单。 它假定你熟悉 Office 外接程序清单。
提示
- 有关仅加载项清单的概述，请参阅 带有仅加载项清单的 Office 外接程序。
- 如果熟悉仅外接程序清单，可以阅读 将仅外接程序清单与 Microsoft 365 的统一清单进行比较，更轻松地了解 JSON 格式的统一清单。
Microsoft 正在对 Microsoft 365 开发人员平台进行大量改进。 这些改进在开发、部署、安装和管理所有类型的 Microsoft 365 扩展（包括 Office 加载项）方面提供了更多一致性。这些更改与现有加载项兼容。
一个重要的改进是能够使用相同的清单格式和架构为所有Microsoft 365 扩展创建单个分发单元。
我们已朝着这些目标迈出了重要的第一步，使你能够使用 Microsoft 365 的统一清单创建 Outlook 加载项。
注意
- 统一清单目前仅支持 Outlook 加载项，并且仅在 Office 中链接到 Microsoft 365 订阅并安装在 Windows、移动设备上或Outlook 网页版中。 我们正在努力将支持扩展到 Excel、PowerPoint 和 Word，以及 Outlook on Mac 和永久版本的 Office。
- 统一清单需要 Office 版本 2304 (内部版本 16320.00000) 或更高版本。
提示
准备好开始使用统一清单了吗？ 首先使用 Microsoft 365 的统一清单生成 Outlook 加载项。
统一清单的关键属性
统一应用清单版本的main参考文档位于统一清单参考。 (有关包含所有最新预览功能的清单参考，请参阅 统一清单的公共开发人员预览版。) 在本文中，我们简要介绍了当 Teams 应用 (或包含 office 外接程序) 时基本属性的含义。 接下来是“extensions”属性及其后代属性的一些基本文档。 示例统一清单中提供了加载项的完整 示例清单。
基属性
下表中列出的每个基本属性在 清单架构中都有更广泛的文档。 此表中未包含的基本属性对 Office 外接程序没有意义。
| JSON 属性 | 用途 |
|---|---|
| "$schema" | 标识清单架构。 |
| "manifestVersion" | 清单架构的版本。 |
| "id" | Teams 应用/加载项的 GUID。 |
| "version" | Teams 应用/外接程序的版本。 格式必须为 n.n.n ，每个 n 格式不能超过 5 位。 |
| "name" | Teams 应用/外接程序的公共短名称和长名称。 短名称显示在加载项的任务窗格顶部。 |
| "description" | Teams 应用/加载项的公共简短和长说明。 |
| “developer” | 有关 Teams 应用/加载项开发人员的信息。 |
| "localizationInfo" | 配置默认区域设置和其他受支持的区域设置。 |
| “validDomains” | 请参阅 指定安全域。 |
| "webApplicationInfo" | 标识 Azure Active Directory 中已知的 Teams 应用/外接程序的 Web 应用。 |
| "authorization" | 标识加载项所需的任何 Microsoft Graph 权限。 |
“extensions”属性
我们正在努力完成“扩展”属性及其后代属性的参考文档。 同时，下面提供了一些基本文档。 大多数（但不是全部）属性在外接程序的仅外接程序清单中具有等效的元素 (或属性) 。在大多数情况下，适用于 XML 元素或属性的说明和限制也适用于统一清单中等效的 JSON 属性。 将 仅外接程序清单与 Microsoft 365 的统一清单进行比较 的“扩展”属性“部分中的表可帮助你确定 JSON 属性的 XML 等效项。
注意
此表仅包含“extensions”的一些选定的代表性后代属性。 它不是“扩展”的所有子属性的详尽列表。 有关统一清单的完整参考，请参阅 Microsoft 365 的统一清单。 有关包含所有最新预览功能的清单参考，请参阅 公共开发人员预览版，了解 Microsoft 365 的统一清单。
| JSON 属性 | 用途 |
|---|---|
| "requirements.capabilities" | 标识加载项需要可安装 的要求集 。 |
| "requirements.scopes" | 标识可在其中安装加载项的 Office 应用程序。 例如，“邮件”表示可以在 Outlook 中安装加载项。 |
| "ribbons" | 加载项自定义的功能区。 |
| “ribbons.contexts” | 指定加载项自定义的命令图面。 例如，“mailRead”或“mailCompose”。 |
| “ribbons.fixedControls” (开发人员预览版) | 配置 集成垃圾邮件报告 加载项的 按钮并将其添加到 Outlook 功能区。 |
| “ribbons.spamPreProcessingDialog” (开发人员预览版) | 配置从 Outlook 功能区选择垃圾邮件报告加载项按钮后显示的预处理对话框。 |
| “ribbons.tabs” | 配置自定义功能区选项卡。 |
| “alternates” | 指定与等效的 COM 加载项、XLL 或两者的向后兼容性。 还指定用于在旧版 Office 上表示加载项的main图标。 |
| "runtimes" | 配置外接程序使用的 嵌入式运行时 ，包括 UI 很少或没有 UI 的各种加载项，例如自定义仅函数加载项和 函数命令。 |
| "autoRunEvents" | 配置指定事件的事件处理程序。 |
指定安全域
清单文件中有一个“validDomains”数组，用于告知 Office 应允许加载项导航到哪些域。 如指定要在加载项窗口中打开的域中所述，在 Office web 版 中运行时，任务窗格可以导航到任何 URL。 但是，在桌面平台中，如果外接程序尝试转到托管起始页的域以外的域中的 URL，该 URL 将在 Office 应用程序的加载项窗格外的新浏览器窗口中打开。
若要在桌面平台中替代此行为，请将要在外接程序窗口中打开的每个域添加到“validDomains”数组中指定的域列表。 如果加载项尝试转至该列表的域中的 URL，则它将在 Office 网页版和桌面版中的任务窗口中打开。 如果它尝试转到不在列表中的 URL，则在 Office 桌面版中，该 URL 将在新的浏览器窗口中打开， (加载项任务窗格外部) 。
示例统一清单
下面是外接程序的统一应用清单示例。 它不包含每个可能的清单属性。
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
"id": "00000000-0000-0000-0000-000000000000",
"version": "1.0.0",
"manifestVersion": "devPreview",
"name": {
"short": "Name of your app (<=30 chars)",
"full": "Full name of app, if longer than 30 characters (<=100 chars)"
},
"description": {
"short": "Short description of your app (<= 80 chars)",
"full": "Full description of your app (<= 4000 chars)"
},
"icons": {
"outline": "outline.png",
"color": "color.png"
},
"accentColor": "#230201",
"developer": {
"name": "Contoso",
"websiteUrl": "https://www.contoso.com",
"privacyUrl": "https://www.contoso.com/privacy",
"termsOfUseUrl": "https://www.contoso.com/servicesagreement"
},
"localizationInfo": {
"defaultLanguageTag": "en-us",
"additionalLanguages": [
{
"languageTag": "es-es",
"file": "es-es.json"
}
]
},
"webApplicationInfo": {
"id": "00000000-0000-0000-0000-000000000000",
"resource": "api://www.contoso.com/prodapp"
},
"authorization": {
"permissions": {
"resourceSpecific": [
{
"name": "Mailbox.ReadWrite.User",
"type": "Delegated"
}
]
}
},
"extensions": [
{
"requirements": {
"scopes": [ "mail" ],
"capabilities": [
{
"name": "Mailbox", "minVersion": "1.1"
}
]
},
"runtimes": [
{
"requirements": {
"capabilities": [
{
"name": "MailBox",
"minVersion": "1.10"
}
]
},
"id": "eventsRuntime",
"type": "general",
"code": {
"page": "https://contoso.com/events.html",
"script": "https://contoso.com/events.js"
},
"lifetime": "short",
"actions": [
{
"id": "onMessageSending",
"type": "executeFunction"
},
{
"id": "onNewMessageComposeCreated",
"type": "executeFunction"
}
]
},
{
"requirements": {
"capabilities": [
{
"name": "MailBox", "minVersion": "1.1"
}
]
},
"id": "commandsRuntime",
"type": "general",
"code": {
"page": "https://contoso.com/commands.html",
"script": "https://contoso.com/commands.js"
},
"lifetime": "short",
"actions": [
{
"id": "action1",
"type": "executeFunction"
},
{
"id": "action2",
"type": "executeFunction"
},
{
"id": "action3",
"type": "executeFunction"
}
]
}
],
"ribbons": [
{
"contexts": [
"mailCompose"
],
"tabs": [
{
"builtInTabId": "TabDefault",
"groups": [
{
"id": "dashboard",
"label": "Controls",
"controls": [
{
"id": "control1",
"type": "button",
"label": "Action 1",
"icons": [
{
"size": 16,
"url": "test_16.png"
},
{
"size": 32,
"url": "test_32.png"
},
{
"size": 80,
"url": "test_80.png"
}
],
"supertip": {
"title": "Action 1 Title",
"description": "Action 1 Description"
},
"actionId": "action1"
},
{
"id": "menu1",
"type": "menu",
"label": "My Menu",
"icons": [
{
"size": 16,
"url": "test_16.png"
},
{
"size": 32,
"url": "test_32.png"
},
{
"size": 80,
"url": "test_80.png"
}
],
"supertip": {
"title": "My Menu",
"description": "Menu with 2 actions"
},
"items": [
{
"id": "menuItem1",
"type": "menuItem",
"label": "Action 2",
"supertip": {
"title": "Action 2 Title",
"description": "Action 2 Description"
},
"actionId": "action2"
},
{
"id": "menuItem2",
"type": "menuItem",
"label": "Action 3",
"icons": [
{
"size": 16,
"url": "test_16.png"
},
{
"size": 32,
"url": "test_32.png"
},
{
"size": 80,
"url": "test_80.png"
}
],
"supertip": {
"title": "Action 3 Title",
"description": "Action 3 Description"
},
"actionId": "action3"
}
]
}
]
}
],
}
]
},
{
"contexts": [ "mailRead" ],
"tabs": [
{
"builtInTabId": "TabDefault",
"groups": [
{
"id": "dashboard",
"label": "Controls",
"controls": [
{
"id": "control1",
"type": "button",
"label": "Action 1",
"icons": [
{
"size": 16,
"url": "test_16.png"
},
{
"size": 32,
"url": "test_32.png"
},
{
"size": 80,
"url": "test_80.png"
}
],
"supertip": {
"title": "Action 1 Title",
"description": "Action 1 Description"
},
"actionId": "action1"
}
]
}
],
"customMobileRibbonGroups" [
{
"id": "myMobileGroup",
"label": "Contoso Actions",
"controls": [
{
"id": "msgReadFunctionButton",
"type": "mobileButton",
"label": "Action 1",
"icons": [
{
"size": 16,
"url": "test_16.png"
},
{
"size": 32,
"url": "test_32.png"
},
{
"size": 80,
"url": "test_80.png"
}
],
"supertip": {
"title": "Action 1 Title",
"description": "Action 1 Description"
},
"actionId": "action1"
}
]
}
]
"customMobileRibbonGroups": [
{
"id": "mobileDashboard",
"label": "Controls",
"controls": [
{
"id": "control1",
"type": "mobileButton",
"label": "Action 1",
"icons": [
{
"size": 16,
"url": "test_16.png"
},
{
"size": 32,
"url": "test_32.png"
},
{
"size": 80,
"url": "test_80.png"
}
],
"supertip": {
"title": "Action 1 Title",
"description": "Action 1 Description"
},
"actionId": "action1"
}
]
}
]
}
]
}
],
"autoRunEvents": [
{
"requirements": {
"capabilities": [
{
"name": "MailBox", "minVersion": "1.10"
}
]
},
"events": [
{
"type": "newMessageComposeCreated",
"actionId": "onNewMessageComposeCreated"
},
{
"type": "messageSending",
"actionId": "onMessageSending",
"options": {
"sendMode": "promptUser"
}
}
]
}
],
"alternates": [
{
"requirements": {
"scopes": [ "mail" ]
},
"prefer": {
"comAddin": {
"progId": "ContosoExtension"
}
},
"hide": {
"storeOfficeAddin": {
"officeAddinId": "00000000-0000-0000-0000-000000000000",
"assetId": "WA000000000"
}
},
"alternateIcons": {
"icon": {
"size": 64,
"url": "https://contoso.com/assets/icon64x64.jpg"
},
"highResolutionIcon": {
"size": 64,
"url": "https://contoso.com/assets/icon128x128.jpg"
}
}
}
]
}
]
}