具有 Microsoft 365 统一应用清单的 Office 加载项 (预览版)

  • 项目

本文介绍 Microsoft 365 的统一应用清单（预览版）。 它假定你熟悉 Office 外接程序清单。

提示

Microsoft 正在对 Microsoft 365 开发人员平台进行大量改进。 这些改进在开发、部署、安装和管理所有类型的 Microsoft 365 扩展（包括 Office 加载项）方面提供了更多一致性。这些更改与现有加载项兼容。

我们正在研究的一项重要改进是，能够基于 Microsoft 365 的 JSON 格式统一应用清单使用相同的清单格式和架构，为所有 Microsoft 365 扩展 (Teams 应用) 创建单个分发单元。

注意

Microsoft 365 平台的任何部分的任何扩展现在称为“Teams 应用”，即使它不扩展 Teams 应用程序本身。

我们已朝着这些目标迈出了重要的第一步，使你能够创建仅在 Windows 上运行的 Outlook 加载项，并为 Microsoft 365 创建统一清单。

注意

  • 统一清单可供预览，可能会根据反馈进行更改。 我们鼓励经验丰富的加载项开发人员进行试验。 不应在生产加载项中使用统一清单。
  • 统一清单的预览版仅支持 Outlook 加载项，并且仅在 Office 中从 Microsoft 365 订阅下载并安装在 Windows 上。 我们正在努力将支持扩展到 Excel、PowerPoint 和 Word 以及其他平台。
  • 统一清单需要 Office 版本 2304 (内部版本 16320.00000) 或更高版本。 你的 Microsoft 365 订阅通道必须是“Beta 版”。

提示

准备好开始使用预览版统一清单了吗？ 首先 使用 Microsoft 365 的统一清单生成 Outlook 加载项， (预览版) 。

统一清单的关键属性

统一应用清单预览版的main参考文档位于 Teams 的公共开发人员预览版应用清单架构中。 该文章提供有关关键基本清单属性的信息，但不能包含“extensions”属性的任何文档，该属性是在统一清单中配置 Office 外接程序的属性。 因此，本文简要介绍了当 Teams 应用 (或包含 office 加载项) 时基本属性的含义。 接下来是“extensions”属性及其后代属性的一些基本文档。 示例预览统一清单中提供了外接程序的完整 示例清单。

基属性

下表中列出的每个基本属性在 Teams 的公共开发人员预览版应用清单架构中都有更广泛的文档。 此表中未包含的基本属性对 Office 外接程序没有意义。

JSON 属性 用途
"$schema" 标识清单架构。
"manifestVersion" 清单架构的版本。
"id" Teams 应用/加载项的 GUID。
"version" Teams 应用/外接程序的版本。
"name" Teams 应用/外接程序的公共短名称和长名称。 短名称显示在加载项的任务窗格顶部。
"description" Teams 应用/加载项的公共简短和长说明。
“developer” 有关 Teams 应用/加载项开发人员的信息。
"localizationInfo" 配置默认区域设置和其他受支持的区域设置。
“validDomains” 请参阅 指定安全域。
"webApplicationInfo" 标识 Azure Active Directory 中已知的 Teams 应用/外接程序的 Web 应用。
"authorization" 标识加载项所需的任何 Microsoft Graph 权限。

“extensions”属性

我们正在努力完成“extensions”属性及其后代属性的参考文档。 同时，下面提供了一些基本文档。 大多数（但不是全部）属性在外接程序的 XML 清单中具有等效的元素 (或属性) 。在大多数情况下，适用于 XML 元素或属性的说明和限制也适用于统一清单中等效的 JSON 属性。 将 XML 清单与 Microsoft 365 的统一清单进行比较 的“extensions”属性“部分中的表可以帮助你确定 JSON 属性的 XML 等效项。

JSON 属性 用途
"requirements.capabilities" 标识加载项需要可安装 的要求集 。
"requirements.scopes" 标识可在其中安装加载项的 Office 应用程序。 例如，“邮件”表示可以在 Outlook 中安装加载项。
"ribbons" 加载项自定义的功能区。
“ribbons.contexts” 指定加载项自定义的命令图面。 例如，“mailRead”或“mailCompose”。
“ribbons.tabs” 配置自定义功能区选项卡。
"alternatives" 指定与等效的 COM 加载项、XLL 或两者的向后兼容性。
"runtimes" 配置外接程序使用的 嵌入式运行时 ，包括 UI 很少或没有 UI 的各种加载项，例如自定义仅函数加载项和 函数命令。
"autoRunEvents" 配置指定事件的事件处理程序。

指定安全域

清单文件中有一个“validDomains”数组，用于告知 Office 应允许加载项导航到哪些域。 如指定要在加载项窗口中打开的域中所述，在 Office web 版 中运行时，任务窗格可以导航到任何 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"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "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"
            }
          }
        }
      ]
    }
  ]
}

另请参阅