通过

指向应用程序的深层链接

  • 项目

Microsoft Teams 中的深层链接是功能强大的工具，允许用户直接导航到应用中的特定内容或操作。 深层链接配置为执行各种操作，例如打开选项卡、启动应用安装对话框或在应用中浏览。

注意

本主题反映 2.0.x 版的 Microsoft Teams JavaScript 客户端库 (TeamsJS) 。 如果使用的是早期版本，请参阅 TeamsJS 库概述 ，获取有关最新 TeamsJS 与早期版本之间的差异的指导。

下面是一些可以使用深层链接的方案：

  • 应用安装：可以使用深层链接，让用户了解有关应用的详细信息，并在不同的范围内安装它。
  • 机器人和连接器：可以使用 机器人 和 连接器 消息中的深层链接来通知用户选项卡或其项的更改。
  • 导航到特定页面：可以创建深层链接，使用户能够导航到应用中的特定页面。
  • 自定义应用：可以为自定义应用生成深层链接。 但是，如果Microsoft Teams 应用商店中的应用与自定义应用 ID 共享相同的应用 ID，则深层链接将从 Teams 应用商店打开应用，而不是自定义应用。
  • 对于移动版：在应用获得 Teams 移动客户端批准后，还可以创建指向移动应用的深层链接。 若要在 Teams iOS 上使用深层链接，需要 Apple App Store Connect Team ID。 有关详细信息，请参阅如何更新 Apple App Store Connect 团队 ID。

深层链接允许应用用户打开应用安装对话框，以了解有关该应用的任何信息或将其安装在不同的上下文中。 可以通过以下方式创建指向应用的深层链接：

使用深层链接，可以使用应用 ID 直接从 Teams 客户端打开应用安装对话框。

https://teams.microsoft.com/l/app/<your-app-id>?tenantId=<tenantId>

<your-app-id> 是 fxxxxxxx-0xxx-4xxx-8xxx-cxxxxxxxx) 的应用程序 (ID。

不同类型的应用的应用 ID

下表列出了不同类型的应用 ID，这些 ID 用于不同类型的应用，用于深层链接：

应用类型 应用 ID 的类型
在 Teams 中上传的自定义应用 清单 ID
提交到组织目录的应用 组织目录 ID
提交到 Teams 应用商店的应用 应用商店 ID

有关详细信息，请参阅 如何基于应用清单 ID 查找 ID。

应用可以使用 Microsoft Teams JavaScript 客户端库 (TeamsJS) 来启动应用安装对话框，而无需手动生成深层链接。 下面是如何在应用中使用 TeamsJS 触发应用安装对话框的示例：

// Open an app install dialog from your tab
if(appInstallDialog.isSupported()) {
    const dialogPromise = appInstallDialog.openAppInstallDialog({ appId: "<appId>" });
    dialogPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

有关详细信息，请参阅 appInstallDialog。

应用用户可以使用 TeamsJS 在选项卡中浏览 Teams 中的内容。 如果你的选项卡需要将用户与 Teams 中的其他内容（如频道、消息、其他选项卡）连接，或者打开计划对话框，则可以使用深层链接在应用中浏览。 在少数情况下，还可以使用 TeamsJS 完成导航，建议尽可能使用 TeamsJS 的类型化功能。

可以通过以下方式配置深层链接以在应用中浏览：

个人选项卡具有 personal 作用域，而通道和组选项卡使用 team 或 group 作用域。 这两种选项卡类型的语法略有不同，因为只有可配置选项卡具有 channel 与其上下文对象关联的属性。 有关选项卡范围的详细信息，请参阅 应用清单。

若要在机器人、连接器或消息扩展卡中创建深层链接，请使用以下格式：

https://teams.microsoft.com/l/entity/<appId>/<entityId>?tenantId=<tenantId>&webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>&openInMeeting=false

  • 如果机器人发送包含 TextBlock 和深层链接的消息，则当用户选择链接时，将打开新的浏览器选项卡。 在 Linux 上运行时，会在 Chrome 和 Teams 桌面应用中发生这种情况。

  • 如果机器人将相同的深层链接 URL 发送到 Action.OpenUrl，则当用户选择链接时，Teams 选项卡将在当前浏览器选项卡中打开。

查询参数

参数名称 说明
appId  Microsoft Teams 管理中心的 ID。

示例：fe4a8eba-2a31-4737-8e33-e5fae6fee194
entityId  选项卡的 ID，在 配置选项卡时提供。生成用于深层链接的 URL 时，请继续使用实体 ID 作为 URL 中的参数名称。 配置选项卡时，上下文对象将 引用 entityId 为 page.id。

示例：Tasklist 123
entityWebUrl 或 subEntityWebUrl  在客户端不支持呈现选项卡时要是用的具有回退 URL 的可选字段。

示例：https://tasklist.example.com/123
或
https://tasklist.example.com/list123/task456
entityLabel 或 subEntityLabel  选项卡中项的标签，用于显示深层链接时使用。

示例：任务列表 123 或任务 456
context.subEntityId  选项卡内项的 ID。生成用于深层链接的 URL 时，请继续在 subEntityId URL 中用作参数名称。 配置选项卡时，上下文对象将 引用 subEntityId 为 page.subPageId。

示例：任务 456
context.channelId  选项卡 上下文 中提供的 Microsoft Teams 频道 ID。 此属性仅在具有 团队范围的可配置选项卡中可用。 它在具有 个人 范围的静态选项卡中不可用。

示例：19：cbe3683f25094106b826c9cada3afbe0@thread.skype
context.chatId  可在选项卡 上下文 中用于群组和会议聊天的聊天 ID。

示例：17：b42de192376346a7906a7dd5cb84b673@thread.v2
context.contextType  会议仅支持 contextType 聊天。

示例：聊天
openInMeeting 使用 openInMeeting 控制目标选项卡与会议关联的用户体验。 如果用户在正在进行的会议体验中与深层链接交互，Teams 会在会议内侧面板中打开应用。 将此值设置为 ， false 无论会议状态如何，始终在会议聊天选项卡而不是侧面板中打开应用。 Teams 会忽略 除 之外 false的任何值。

示例：false

重要

  • 确保所有查询参数和空格都正确编码了 URI。 下面是 URI 编码的查询参数的示例：

    var encodedWebUrl = encodeURIComponent('https://tasklist.example.com/123/456&label=Task 456');
var encodedContext = encodeURIComponent(JSON.stringify({"subEntityId": "task456"}));
var taskItemUrl = 'https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=' + encodedWebUrl + '&context=' + encodedContext;

  • Outlook 不支持指向具有编码 URI 的 Teams 应用的深层链接。

可以通过 TeamsJS 在应用中配置深层链接，以允许用户浏览应用中的不同页面。 跨 Microsoft 365 Office 扩展的 Teams 应用的导航行为取决于两个因素：

  1. 深层链接指向的目标。
  2. 运行 Teams 应用的主机。

如果 Teams 应用在深层链接作为目标的主机中运行，则应用将直接在主机中打开。 但是，如果 Teams 应用在与深层链接目标不同的主机中运行，则首先在浏览器中打开该应用。


支持 TeamsJS 中的深层链接

TeamsJS 使跨 Outlook 和 Microsoft 365 扩展的 Teams 应用能够检查主机是否支持你尝试使用的功能。 若要检查主机对功能的支持，可以使用与 API 命名空间关联的 isSupported() 函数。 TeamsJS 通过命名空间将 API 组织到功能中。 例如，在使用命名空间中的 pages API 之前，可以检查返回pages.isSupported()的布尔值，并在应用和应用的 UI 上下文中执行相应的操作。 有关详细信息，请参阅 使用 TeamsJS 库生成选项卡和其他托管体验。

以下代码演示如何导航到 Teams 应用中的特定实体：

可以使用 pages.navigateToApp() 函数从选项卡触发导航，如以下代码所示：

if (pages.isSupported()) {
  const navPromise = pages.navigateToApp({ appId: <appId>, pageId: <pageId>, webUrl: <webUrl>, subPageId: <subPageId>, channelId:<channelId>});
  navPromise.
     then((result) => {/*Successful navigation*/}).
     catch((error) => {/*Failed navigation*/});
}
else { /* handle case where capability isn't supported */ }

TeamsJS 库 的页面 功能支持在应用中的选项卡之间导航。 具体而言， pages.currentApp 命名空间提供一个函数 navigateTo(NavigateWithinAppParams) ，允许导航到当前应用中的特定选项卡，以及一个用于导航到应用清单中定义的第一个选项卡的函数 navigateToDefaultPage() 。 以下代码演示如何导航到特定的默认选项卡：

以下代码演示如何导航到特定选项卡：

if (pages.currentApp.isSupported()) {
    const navPromise = pages.currentApp.navigateTo({pageId: <pageId>, subPageId: <subPageId>});
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}
else {/*Handle situation where capability isn't supported*/
    const navPromise = pages.navigateToApp({appId: <appId>, pageId: <pageId>});
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}

注意

选项卡应用导航仅在 新的 Teams 客户端中受支持。

配置后退按钮导航

当应用有多个选项卡时，用户可以使用 Microsoft 365 主机应用的后退按钮向后浏览导航历史记录。 但是，历史记录不包括用户在选项卡中执行的操作。如果要增强后退按钮体验，可以维护自己的内部导航堆栈，并为后退按钮选择配置自定义处理程序。 这可以通过 命名空间中的 pages.backStack 函数来实现registerBackButtonHandler()。

注册处理程序后，它会帮助你在系统执行操作之前处理导航请求。 如果处理程序能够管理请求，则它应返回 true ，以便系统无需执行进一步操作。 如果内部堆栈为空，它应返回 false ，以便系统可以改为调用 navigateBack() 函数并采取相应的操作。

将焦点返回到主机应用

用户开始使用选项卡中的元素后，默认情况下，焦点将保留在 iFrame 的元素上，直到用户选择其外部。 如果 iFrame 是使用键盘快捷方式 (Tab 键或 F6 键) 导航的用户的一部分，则可以专注于主机应用。 可以使用 函数专注于主机应用 pages.returnFocus() 。 函数 returnFocus() 接受一个布尔值，指示在主机应用中前进焦点的方向; true 对于向前和 false 向后。 通常，向前突出显示搜索栏，向后突出显示应用栏。

你可以通过手动配置深层链接，允许应用用户浏览到与应用程序的个人聊天。

https://teams.microsoft.com/l/entity/<appId>/conversations?tenantId=<tenantId>

appId 是应用程序 ID。 有关详细信息，请参阅 不同类型的应用的应用 ID。

可以在 Teams 应用中共享指向实体的深层链接，以导航到选项卡应用中的内容和信息。 例如，如果选项卡应用包含任务列表，则团队成员可以创建和共享指向单个任务的链接。 当应用用户选择链接时，它会导航到侧重于特定项目的选项卡。

以最适合你的 UI 的任何方式向每个项目添加 复制链接 操作。 当用户执行此操作时，调用 pages.shareDeepLink() 以显示一个对话框，其中包含用户可以复制到剪贴板的链接。 进行此呼叫时，请传递你的项目的 ID。 当链接被跟踪并重新加载选项卡时，你会在 上下文 中恢复它。

pages.shareDeepLink({ subPageId: <subPageId>, subPageLabel: <subPageLabel>, subPageWebUrl: <subPageWebUrl> })

必须将以下参数替换为适当的信息：

参数名称 说明
subPageId 要深层链接到的页面内项的唯一标识符。
subPageLabel 用于显示深层链接的项的标签。
subPageWebUrl 客户端无法呈现页面时使用的回退 URL。

有关详细信息，请参阅 pages.shareDeepLink () 。

注意

  • 此深层链接不同于 “复制到选项卡” 菜单项的链接，后者仅生成指向此选项卡的深层链接。
  • shareDeepLink 不适用于 Teams 移动平台。

SharePoint 框架 (SPFx) 选项卡的深层链接允许用户直接导航到 SharePoint 网站或 Teams 应用中的特定选项卡。 这通过提供对相关内容和功能的快速访问来增强用户体验。

可以在机器人、连接器或消息扩展卡使用以下深层链接格式：

https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>.

注意

  • 当机器人发送 TextBlock 包含深层链接的消息时，当用户选择链接时，将打开一个新的浏览器选项卡。 这发生在 Linux 上运行的 Chrome 和 Microsoft Teams 桌面应用中。
  • 如果机器人在 中 Action.OpenUrl发送相同的深层链接 URL，则当用户选择链接时，Teams 选项卡将在当前浏览器中打开。 未打开新的浏览器选项卡。

查询参数

值 说明
APP_ID 清单 ID。

示例：fxxxxxxx-0xxx-4xxx-8xxx-cxxxxxxxxxxx
entityID 配置选项卡时提供的项 ID。

示例：tasklist123
entityWebUrl 客户端不支持呈现选项卡时使用的回退 URL。

示例： https://tasklist.example.com/123 或 https://tasklist.example.com/list123/task456
entityName 选项卡中项的标签，用于显示深层链接时使用。

示例： Task List 123 或 Task 456

对话深层链接是对象的序列化 TaskInfo ，其中包含另外两个详细信息， APP_ID 以及 （可选） BOT_APP_ID。

  • https://teams.microsoft.com/l/task/APP_ID?url=<TaskInfo.url>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=BOT_APP_ID

  • https://teams.microsoft.com/l/task/APP_ID?card=<TaskInfo.card>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=BOT_APP_ID

有关 <TaskInfo.url>、<TaskInfo.card>、<TaskInfo.height>、<TaskInfo.width> 和 <TaskInfo.title> 的数据类型和允许的值，请参阅 TaskInfo 对象。

提示

使用 card 参数（例如 JavaScript encodeURI() 函数）时对深层链接 URL 进行编码。

下表提供了有关 APP_ID 和 BOT_APP_ID 的信息：

值 类型 必需 说明
APP_ID string 是 - 对于第三方应用，请使用清单中的应用 id 或 APP_ID Teams 管理中心的应用，因为它们相同。

- 对于为组织生成的自定义应用或自定义应用， (LOB 应用) ，请使用 APP_ID Teams 管理中心中的 或使用图形 API。

- 清单中的 APP_IDvalidDomains 数组必须包含 的域（url如果 url 存在于深层链接 URL 中）。 当从选项卡或机器人调用对话框时，应用 ID 已经是已知的，这就是为什么它未包含在 中 TaskInfo的原因。
BOT_APP_ID string 否 如果指定了 completionBotId 的值，则使用 task/submit invoke 消息将 result 对象发送到指定的机器人。 必须在应用的清单中将指定 BOT_APP_ID 为机器人，无法将其发送到任何机器人。

注意

APP_ID 在许多情况下 BOT_APP_ID ，如果应用有一个建议的机器人用作应用的 ID，并且如果有机器人，则和 可以相同。

用于在会议阶段共享内容的深层链接

还可以生成深层链接，以 共享应用以暂存 和开始或加入会议。

有关将内容共享到阶段的深层链接，请参阅 在会议中将内容共享到阶段的深层链接。

注意

  • 生成用于在会议中将内容共享到阶段的深层链接仅在 公共开发人员预览版中可用。
  • 仅在 Teams 桌面客户端中支持用于将内容共享到会议阶段的深层链接。

可以在会议中生成 指向会议侧面板 的深层链接。

使用以下格式进行到会议端面板的深层链接：

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>.

默认情况下，深层链接在会议侧面板中打开。 若要直接在应用而不是会议端面板中打开深层链接，请添加 openInMeeting=false ，如以下深层链接格式所示：

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>&openInMeeting=false

有关详细信息，请参阅 指向选项卡的深层链接。

在以下情况下，深层链接不会在会议侧面板中打开：

  • 没有活动会议。
  • 应用未 sidePanel 在应用清单中声明上下文。
  • openInMeeting 在深层链接中设置为 false 。
  • 深层链接在会议窗口或组件之外选择。
  • 深层链接与当前会议不匹配，例如，如果深层链接是从另一个会议创建的。

可以通过在 API 中 app.openLink(url) 包装深层链接 URL，通过选项卡的深层链接调用 Stageview。 也可以通过卡片中的 OpenURL 操作传递深层链接。 API openMode 中定义的 属性确定 Stageview 响应。 有关详细信息，请参阅 通过深层链接调用 Stageview。

最佳做法

  • 仅当选项卡使用库 v0.4 或更高版本配置时，深层链接才正常工作，因为它具有实体 ID。 指向没有实体 ID 的选项卡的深层链接仍会转到选项卡，但无法向选项卡提供 sub'EntityId。
  • 在 Microsoft Windows 中，由于 Windows ShellExecuteExecuteEx API 中的限制，Teams 无法处理超过 2048 个字符的 INTERNET_MAX_URL_LENGTH 深层链接。
  • 创建深层链接时，请确保 Teams 客户端和其他元数据的路径符合此限制。
  • 如果深层链接包含大量数据，请在链接中包含一个唯一标识符，你的应用可以使用该标识符从后端服务中提取必要的数据。

代码示例

示例名称 Description .NET Node.js
深层链接消耗 subEntityId 此示例演示如何使用从机器人聊天到使用 的选项卡的 subEntityId深层链接。 它还显示了以下项的深层链接：
- 导航到应用
- 导航到聊天
- 打开配置文件对话框
- 打开计划对话框		 View View
选项卡应用导航 此示例演示如何在应用内的选项卡之间导航。 不适用 View