具有 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 加载项。
统一清单的关键属性
统一应用清单版本的主要参考文档位于 清单架构中。 该文章提供有关关键基本清单属性的信息,但不能包含“extensions”属性的任何文档,该属性是在统一清单中配置 Office 外接程序的属性。 因此,本文简要介绍了当 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”属性
我们正在努力完成“extensions”属性及其后代属性的参考文档。 同时,下面提供了一些基本文档。 大多数(但不是全部)属性在外接程序的仅外接程序清单中具有等效的元素 (或属性) 。在大多数情况下,适用于 XML 元素或属性的说明和限制也适用于统一清单中等效的 JSON 属性。 将 仅外接程序清单与 Microsoft 365 的统一清单进行比较 的“扩展”属性“部分中的表可帮助你确定 JSON 属性的 XML 等效项。
JSON 属性 | 用途 |
---|---|
"requirements.capabilities" | 标识加载项需要可安装 的要求集 。 |
"requirements.scopes" | 标识可在其中安装加载项的 Office 应用程序。 例如,“邮件”表示可以在 Outlook 中安装加载项。 |
"ribbons" | 加载项自定义的功能区。 |
“ribbons.contexts” | 指定加载项自定义的命令图面。 例如,“mailRead”或“mailCompose”。 |
“ribbons.tabs” | 配置自定义功能区选项卡。 |
“alternates” | 指定与等效的 COM 加载项、XLL 或两者的向后兼容性。 还指定用于在旧版 Office 上表示加载项的主图标。 |
"runtimes" | 配置外接程序使用的 嵌入式运行时 ,包括 UI 很少或没有 UI 的各种加载项,例如自定义仅函数加载项和 函数命令。 |
"autoRunEvents" | 配置指定事件的事件处理程序。 |
指定安全域
清单文件中有一个“validDomains”数组,用于告知 Office 应允许加载项导航到哪些域。 如指定要 在加载项窗口中打开的域中所述,在 Office 网页版中运行时,任务窗格可以导航到任何 URL。 但是,在桌面平台中,如果外接程序尝试转到托管起始页的域以外的域中的 URL,该 URL 将在 Office 应用程序的加载项窗格外的新浏览器窗口中打开。
若要在桌面平台中替代此行为,请将要在外接程序窗口中打开的每个域添加到“validDomains”数组中指定的域列表。 如果加载项尝试转至该列表的域中的 URL,则它将在 Office 网页版和桌面版中的任务窗口中打开。 如果它尝试转到不在列表中的 URL,则在 Office 桌面版中,该 URL 将在新的浏览器窗口中打开, (加载项任务窗格外部) 。
示例统一清单
下面是外接程序的统一应用清单示例。
{
"$schema": "https://raw.githubusercontent.com/OfficeDev/microsoft-teams-app-schema/op/extensions/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"
}
}
}
]
}
]
}