通过

在应用清单中指定Microsoft 365 主机运行时要求

  • 项目

注意

在应用清单中指定 Microsoft 365 主机运行时要求的功能 (以前称为 Teams 应用清单) 为 公共开发人员预览版。

将 Microsoft Teams 个人选项卡或消息扩展应用升级为使用应用清单版本 1.13 或更高版本时，它默认在其他 Microsoft 365 应用程序主机中可用。 但是，如果应用还包含某些主机尚不支持的功能，则应用可能仅部分加载，从而导致计划外用户体验。

例如，考虑使用应用清单架构版本 1.17 定义的应用，其中包含一个机器人和一个表示机器人设置的配置选项卡。 该应用将在 Outlook 和 Microsoft 365 (Office) 应用中加载，但仅向用户显示“机器人配置”选项卡，而不显示机器人本身。

若要确保高质量的应用体验达到预期用户群，请在应用清单中指定应用的运行时要求。 这允许你在适用的 Microsoft 365 主机中定制其行为，或者在尚未准备好支持的上下文中省略它。

在以下方案中，指定应用的运行时要求非常有用：

  • 单向依赖项：当一个应用功能的唯一用途是支持应用中的另一个功能时，可以确保它仅在加载主应用功能时出现。 例如，如果应用同时包含选项卡和消息扩展，并且选项卡充当用户配置消息扩展功能的设置页面，则可以指定“设置”选项卡不会加载到不支持消息扩展的主机中。

  • 相互依赖关系： 当应用具有必须一起加载才能正常运行的特定应用功能时，可以确保应用仅在支持所有功能的 Microsoft 365 主机 中可用 。 例如，如果选项卡、机器人和消息扩展功能协同工作以支持应用中的核心用户方案，则可以指定这些功能始终一起加载，或者根本不加载。

  • 功能要求： 当应用具有特定 Microsoft 365 主机不支持的运行时要求的功能时，可以确保从这些主机中运行的应用体验中 无缝省略 这些功能 (（而不是加载），但不会) 这些功能。 例如，如果应用包含一个基于选项卡的仪表板视图，其中每个项都可以作为对话框打开，并且每个对话都包含随后提交给机器人的信息，则可以指定基于机器人的对话是应用在给定主机中加载所需的核心功能。

Microsoft 365 主机支持

以下Microsoft 365 主机应用程序支持在应用清单中指定运行时要求：

Microsoft 365 主机应用程序 Web 桌面 移动设备
Teams ✔️ ✔️ ✔️
Outlook ✔️ ✔️ (仅限新 Outlook) ✔️
Microsoft 365 (Office)
Microsoft 365 Copilot

指定应用功能 (elementRelationshipSet) 之间的关系

可以通过在应用清单中包含 来 elementRelationshipSet 指定应用的各个功能之间的关系。 使用此对象可以指定应用功能之间的 单向依赖项 和 相互依赖关系 。

可将以下应用清单功能指定为具有单向依赖项或相互依赖关系：

  • 选项卡：个人 (staticTabs) 和可配置 (configurableTabs)
  • 消息扩展 (composeExtensions) ，包括单个命令
  • 机器人 (bots)

每个应用功能由新引入的属性定义， id该 botId 属性映射到机器人、 entityId 静态选项卡和 id 可配置选项卡和消息扩展。 Teams 和其他Microsoft 365 主机支持包含单个可配置选项卡和/或单个消息扩展的应用。 如果主机支持扩展以容纳这些功能的多个实例，该 id 属性将面向未来应用。

重要

确保创建的关系符合以下验证规则：

  1. 在 下 elementRelationshipSet 指定的元素必须在应用清单中具有定义。 例如，element在应用清单中dependsOn没有相应定义的 对象的 部分oneWayDependencies中列出的 或 commandId (具有匹配id值) 会导致清单验证错误。 属性id必须在 或 composeExtension 中configurableTab指定，才能在 中elementRelationshipSet识别。
  2. 给定的功能集只能按 或 oneWayDependency进行分组，但不能同时分组mutualDependency。 例如，指定单向依赖项 (A 依赖于 B) ， (A 和 B 相互依赖) 会导致清单验证错误，因为 A 依赖 B 关系表示两次。
  3. 不允许使用循环单向依赖项。 例如，同时指定 A 依赖于 B 关系和 B 依赖于 A 关系会导致清单验证错误。

单向依赖项

oneWayDependencies使用 数组描述应用一个组件依赖于另一个组件的情况。 对于数组中的每个对象，指定依赖组件 () element ，指定它所依赖的组件 (dependsOn) 。 还可以指定需要支持特定应用功能的单个命令。 如果运行时主机不支持这些功能，则不会向用户提供这些功能 (尽管所有其他命令都) 运行。

以下 JSON 代码片段显示了对机器人具有单向依赖关系的特定消息扩展命令：

    "elementRelationshipSet": {
      "oneWayDependencies" : [
        {
          "element" : {
            "name" : "composeExtensions",
            "id" : "composeExtension-id",
            "commandIds": ["exampleCmd1", "exampleCmd2"]
          },
          "dependsOn" : [
              {"name" : "bots", "id" : "bot-id"}
            ]
        }
      ]
    }

相互依赖关系

mutualDependencies使用 数组对必须一起加载的应用功能进行分组，以支持其预期功能。 数组中的每个对象都表示一组相互依赖的应用功能。 以下 JSON 代码片段显示了相互依赖的机器人、静态选项卡、消息扩展和可配置选项卡：

    "elementRelationshipSet": {
      "mutualDependencies" : [
        [
                {"name" : "bots", "id" : "bot-id"}, 
                {"name" : "staticTabs", "id" : "staticTab-id"},
                {"name" : "composeExtensions", "id" : "composeExtension-id"},
                {"name" : "configurableTabs", "id": "configurableTab-id"}
        ]
      ]
    },

指定特定应用功能的运行时要求 (requirementSet)

在单个应用功能定义中，可以使用 指定特定的 TeamsJS 运行时要求 requirementSet。 这可确保应用功能仅在支持关键 TeamsJS 功能的 Microsoft 365 主机中加载。

可以将以下 TeamsJS 功能指定为 、 composeExtensions和 bots的staticTabs运行时要求：

以下 JSON 代码段显示了一个静态选项卡，该选项卡要求其主机支持 HTML 对话框， (TeamsJS v1.x 中称为任务模块，) 从选项卡和机器人调用：

    "staticTabs": [
        {
            "entityId": "idForPage",
            "name": "Display name of tab",
            "contentUrl": "https://contoso.com/content?host=msteams",
            "contentBotId": "Specifies to the app that tab is an Adaptive Card Tab. You can either provide the contentBotId or contentUrl.",
            "websiteUrl": "https://contoso.com/content",
            "scopes": [
                "personal"
            ],
            "requirementSet": {
                "hostMustSupportFunctionalities": [
                  {"name": "dialogUrl"},
                  {"name": "dialogUrlBot"}
                ]
            }
        }
    ],

代码示例

示例名称 Description JavaScript
目标要求：单向依赖项 演示如何指定应用功能之间的单向依赖关系的示例应用。 View
目标要求：相互依赖关系 演示如何指定应用功能之间的相互依赖关系的示例应用。 View

另请参阅