选项卡链接展开和阶段视图

阶段视图是用户界面 (UI) 组件,可用于在 Teams 中全屏呈现内容或作为新窗口呈现内容。

注意

本文基于 Microsoft Teams JavaScript 客户端库版本 2.0.x。 如果使用的是早期版本,请参阅 TeamsJS ,获取有关最新 TeamsJS 与早期版本之间的差异的指导。

阶段视图

阶段视图是一个全屏 UI 组件,可用于呈现应用内容,为用户提供与应用互动的专注体验。 可以在聊天和频道中从自适应卡片或深层链接调用阶段视图。

  • 当用户从自适应卡片调用阶段视图时,“阶段视图”将在新的 Teams 窗口中打开,并在侧面板中打开原始聊天或频道线程。 此新应用画布称为 协作阶段视图。 协作阶段视图允许用户执行多任务并相互协作。

  • 协作阶段视图显示发起的聊天或线程,从中调用它,并帮助用户并排参与内容和对话。

下图是协作阶段视图的示例:

屏幕截图显示了 Teams 中的协作阶段视图。

阶段视图与对话框

阶段视图 对话 (TeamsJS v1.x) 中称为任务模块
阶段视图可用于向用户显示丰富的内容,例如页面、仪表板或文件。 它提供了丰富的功能,有助于在新弹出窗口和全屏画布中呈现内容。

应用内容在“阶段视图”中打开后,用户可以选择将内容固定为选项卡。

对于更多协作功能,通过自适应卡片 (在协作阶段视图中打开内容) 允许用户并行参与内容和对话,同时启用多窗口方案。
对话框 对于显示需要用户注意的消息或收集移动到下一步所需的信息特别有用。

警告

Microsoft 的云服务,包括 Web 版本的 Teams (teams.microsoft.com) 、Outlook (outlook.com) 和 Microsoft 365 (microsoft365.com) 域迁移到 cloud.microsoft 域。 在 2024 年 6 月之前执行以下步骤,以确保应用继续在 Teams Web 客户端上呈现:

  1. 将 TeamsJS SDK 更新到 v.2.19.0 或更高版本。 有关最新版本的 TeamsJS SDK 的详细信息,请参阅 Microsoft Teams JavaScript 客户端库

  2. 更新 Teams 应用中 的内容安全策略 标头,以允许应用访问 teams.cloud.microsoft 域。 如果 Teams 应用跨 Outlook 和 Microsoft 365 扩展,请确保允许应用访问 teams.cloud.microsoftoutlook.cloud.microsoftm365.cloud.microsoft 域。

若要通过选项卡中的深层链接调用阶段视图,必须在 app.openLink(url) API 中包装深层链接 URL。 深层链接中的阶段视图始终默认为模式体验 (,而不是 Teams 窗口) 。 虽然阶段视图深层链接可以通过卡中的操作OpenURL传递,但阶段视图深层链接适用于选项卡画布。 对于自适应卡片中的阶段视图,建议遵循 JSON 自适应卡片示例

下图是从深层链接调用阶段视图的示例:

屏幕截图显示卡的打开阶段。

语法

下面是阶段视图的深层链接语法:

https://teams.microsoft.com/l/stage/{appId}/0?context={"contentUrl":"contentUrl","websiteUrl":"websiteUrl","name":"Contoso"}

示例

下面是用于调用阶段视图的深层链接示例:


示例 1 具有 threadId 的 URL

未编码的 URL:

https://teams.microsoft.com/l/stage/be411542-2bd5-46fb-8deb-a3d5f85156f6/0?context={"contentUrl":"https://teams-alb.wakelet.com/teams/collection/e4173826-5dae-4de0-b77d-bfabafd6f191","websiteUrl":"https://teams-alb.wakelet.com/teams/collection/e4173826-5dae-4de0-b77d-bfabafd6f191?standalone=true","title":"Quotes: Miscellaneous","threadId":"19:9UryYW9rjwnq-vwmBcexGjN1zQSNX0Y4oEAgtUC7WI81@thread.tacv2"}

已编码的 URL:

https://teams.microsoft.com/l/stage/be411542-2bd5-46fb-8deb-a3d5f85156f6/0?context=%7B%22contentUrl%22%3A%22https%3A%2F%2Fteams-alb.wakelet.com%2Fteams%2Fcollection%2Fe4173826-5dae-4de0-b77d-bfabafd6f191%22%2C%22websiteUrl%22%3A%22https%3A%2F%2Fteams-alb.wakelet.com%2Fteams%2Fcollection%2Fe4173826-5dae-4de0-b77d-bfabafd6f191%3Fstandalone%3Dtrue%22%2C%22title%22%3A%22Quotes%3A%20Miscellaneous%22%2C%22threadId%22%3A%2219:9UryYW9rjwnq-vwmBcexGjN1zQSNX0Y4oEAgtUC7WI81@thread.tacv2%22%7D


示例 2 不带 threadId 的 URL

未编码的 URL:

https://teams.microsoft.com/l/stage/43f56af0-8615-49e6-9635-7bea3b5802c2/0?context={"contentUrl":"https://teams-alb.wakelet.com/teams/collection/e4173826-5dae-4de0-b77d-bfabafd6f191","websiteUrl":"https://teams-alb.wakelet.com/teams/collection/e4173826-5dae-4de0-b77d-bfabafd6f191?standalone=true","title":"Quotes: Miscellaneous"}

已编码的 URL:

https://teams.microsoft.com/l/stage/43f56af0-8615-49e6-9635-7bea3b5802c2/0?context=%7B%22contentUrl%22%3A%22https%3A%2F%2Fteams-alb.wakelet.com%2Fteams%2Fcollection%2Fe4173826-5dae-4de0-b77d-bfabafd6f191%22%2C%22websiteUrl%22%3A%22https%3A%2F%2Fteams-alb.wakelet.com%2Fteams%2Fcollection%2Fe4173826-5dae-4de0-b77d-bfabafd6f191%3Fstandalone%3Dtrue%22%2C%22title%22%3A%22Quotes%3A%20Miscellaneous%22%7D


注意

  • 粘贴 URL 之前,必须对所有深层链接进行编码。不支持未编码的 URL。
  • 属性 name 在深层链接中是可选的。 如果未包含,应用名称将替换它。
  • 也可以通过 OpenURL 操作传递深层链接。
  • 从特定上下文启动阶段视图时,请确保应用在该上下文中正常工作。 例如,如果阶段视图是从个人应用启动的,则必须确保应用具有个人范围。

协作阶段视图

注意

Teams Web 和移动客户端不支持协作阶段视图。

协作阶段视图是阶段视图的一项增强功能,允许用户在新 Teams 窗口中使用你的应用内容。 当用户从自适应卡片打开协作阶段视图时,应用内容会弹出到新的 Teams 窗口中,而不是默认的阶段视图模式。

在新 Teams 窗口中,“协作阶段视图”还会在侧面板中打开聊天。 聊天从最初共享用户的自适应卡片的群组聊天或频道线程引入对话。 用户可以继续直接在新窗口中进行协作。

下图是协作阶段视图的示例:

屏幕截图显示了 Teams 中的协作阶段视图。

协作阶段视图的优点

协作阶段视图有助于在 Teams 中使用应用内容解锁多任务处理方案。 用户可以在新 Teams 窗口中打开和查看应用内容,同时在同一窗口中进行有意义的对话和协作。 能够参与内容,同时就内容进行对话,从而提升应用的用户参与度。

功能 注意 桌面 Web 移动设备
协作阶段视图 从自适应卡片操作调用。 聊天或频道:使用聊天窗格打开 Teams 弹出窗口。 打开“阶段视图”模式。 打开“阶段视图”模式。
阶段视图 从深层链接调用。 仅当从选项卡应用(而不是自适应卡片)调用时,才建议使用。 打开“阶段视图”模式。 打开“阶段视图”模式。 打开“阶段视图”模式。

从自适应卡片调用协作阶段视图

当用户在聊天中输入应用内容 URL 时,将调用机器人并返回一个自适应卡片,其中包含用于打开 URL 的选项。 根据上下文和用户的客户端,URL 将在相应的阶段视图 UI 中打开。 当从聊天或频道中的自适应卡片 (而不是从深层链接) 调用协作阶段视图时,将打开一个新窗口。

下图是自适应卡片中的协作阶段视图的示例:

屏幕截图显示了从自适应卡片调用协作阶段视图的过程。

屏幕截图显示自适应卡片中的协作阶段视图。

示例

下面是在自适应卡片中创建协作阶段视图按钮的 JSON 代码示例:

{
  "type": "Action.Submit",
  "title": "Open",
  "data": {
    "msteams": {
      "type": "invoke",
      "value": {
        "type": "tab/tabInfoAction",
        "tabInfo": {
          "contentUrl": "contentUrl",
          "websiteUrl": "websiteUrl",
          "name": "Sales Report",
          "entityId": "entityId"
        }
      }
    }
  }
}

以下步骤演示如何调用协作阶段视图:

  • 当用户在 Teams 聊天中共享 URL 时,机器人会收到 composeExtensions/queryLink 调用请求。 机器人返回类型 tab/tabInfoAction为 的自适应卡片。
  • 当用户选择自适应卡片上的操作按钮时,将根据自适应卡片中的内容打开协作阶段视图。

注意

  • 将阶段视图深层链接传递到自适应卡片不会打开协作阶段视图。 阶段视图深层链接始终打开阶段视图模式。
  • 确保内容的 URL 在应用清单中的 列表中 validDomains
  • 调用请求类型必须为 composeExtensions/queryLink
  • invoke 工作流类似于 appLinking 工作流。
  • 为了保持一致性,建议将 Action.Submit 命名为 Open
  • websiteUrl 是要在 TabInfo 对象中传递的必需属性。
  • 如果没有针对 Teams 移动客户端的优化移动体验,则会在默认 Web 浏览器中打开通过 Microsoft Teams 应用商店 分发的应用的阶段视图。 浏览器将打开 TabInfo 对象的 websiteUrl 参数中指定的 URL。

查询参数

属性名称 类型 字符数 说明
entityId 字符串 64 此属性是选项卡显示的实体的唯一标识符,并且是必填字段。
name String 128 此属性是通道接口中选项卡的显示名称,是可选的字段。
contentUrl String 2048 此属性是 https:// 指向要显示在 Teams 画布中的实体 UI 的 URL,它是必填字段。
websiteUrl? String 2048 如果用户选择在 https:// 浏览器中查看,并且该属性是必填字段,则此属性是指向的 URL。
removeUrl? String 2048 此属性是 https:// 指向用户删除选项卡时要显示的 UI 的 URL,该选项卡是可选字段。

代码示例

示例名称 Description .NET Node.js 清单
阶段视图中的选项卡 用于在阶段视图中演示选项卡的 Microsoft Teams 选项卡示例应用。 View View View

后续步骤

另请参阅