指向应用程序的深层链接

项目
10/29/2024

深层链接配置为执行各种操作，例如打开选项卡、启动应用安装对话框或在应用中浏览。使用机器人和连接器消息中的深层链接通知用户选项卡或其项的更改。

可以为自定义应用创建深层链接。但是，如果Microsoft Teams 应用商店中的应用与自定义应用 ID 共享相同的应用 ID，则深层链接将从 Teams 应用商店打开应用，而不是自定义应用。在应用获得 Teams 移动平台批准后，还可以创建指向移动应用的深层链接。若要在 Teams iOS 上使用深层链接，需要 Apple App Store Connect Team ID。有关详细信息，请参阅如何更新 Apple App Store Connect 团队 ID。

深层链接允许用户了解有关应用的详细信息，并将其安装在不同的范围内。你还可以为应用用户创建深层链接，以转到应用中的特定页面。本文介绍如何创建深层链接：

打开应用程序安装对话框
在应用中浏览
转到与应用程序聊天
共享选项卡的深层链接
在 TeamsJS v1.x 中打开对话框 (称为任务模块)
调用 Stageview

注意

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

用于打开应用程序安装对话框的深层链接

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

使用应用 ID 手动配置深层链接
使用 TeamsJS 配置选项卡的深层链接

使用应用 ID 手动配置深层链接

下面是使用应用 ID 从 Teams 客户端打开应用安装对话框所需的深层链接格式：

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

其中 <your-app-id> ，应用程序 ID (f46ad259-0fe5-4f12-872d-c737b174bcb4) 。

不同类型的应用的应用 ID

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

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

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

应用程序可以使用 TeamsJS 库启动应用安装对话框，而无需手动生成深层链接。下面是如何在应用程序中使用 TeamsJS 触发应用安装对话框的示例：

TeamsJS v2
TeamsJS v1

// 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 的详细信息，请参阅 appInstallDialog 模块。

// Open an app install dialog from your tab
microsoftTeams.executeDeepLink("https://teams.microsoft.com/l/app/<appId>");

用于在应用中浏览的深层链接

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

TeamsJS 使跨 Outlook 和 Microsoft 365 扩展的 Teams 应用能够检查主机是否支持你尝试使用的功能。若要检查主机对功能的支持，可以使用与 API 命名空间关联的 isSupported() 函数。 TeamsJS 通过命名空间将 API 组织到功能中。例如，在使用命名空间中的 pages API 之前，可以检查返回pages.isSupported()的布尔值，并在应用和应用的 UI 上下文中执行相应的操作。

有关 TeamsJS 中的功能和 API 的详细信息，请参阅使用 TeamsJS 库生成选项卡和其他托管体验。

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

配置深层链接以手动浏览应用
使用 TeamsJS 配置选项卡的深层链接
配置深层链接以在选项卡之间导航

配置深层链接以手动浏览应用

注意

在 Microsoft Windows 中，由于 Windows ShellExecuteExecuteEx API 中的限制，Teams 无法处理超过 2048 个字符的 INTERNET_MAX_URL_LENGTH 深层链接。创建深层链接时，请确保 Teams 客户端和其他元数据的路径符合此限制。如果深层链接包含大量数据，请在链接中包含一个唯一标识符，你的应用可以使用该标识符从后端服务中提取必要的数据。

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

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

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

查询参数为：

参数名称	说明	示例
`appId`	Microsoft Teams 管理中心的 ID。	fe4a8eba-2a31-4737-8e33-e5fae6fee194
`entityId`	选项卡的 ID，在配置选项卡时提供。生成用于深层链接的 URL 时，请继续使用实体 ID 作为 URL 中的参数名称。配置选项卡时，上下文对象将引用 `entityId` 为 `page.id`。	任务列表 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`

注意

个人选项卡具有 personal 作用域，而通道和组选项卡使用 team 或 group 作用域。这两种选项卡类型的语法略有不同，因为只有可配置的选项卡具有与其上下文对象关联的 channel 属性。有关选项卡范围的详细信息，请参阅应用清单。
仅当选项卡是使用库 v0.4 或更高版本配置的，因为它具有实体 ID 时，深层链接才能正常工作。指向没有实体 ID 的选项卡的深层链接仍会转到选项卡，但无法向选项卡提供子实体 ID。

示例：

链接到静态 (个人) 选项卡本身:

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123
链接到静态 (个人) 选项卡内的任务项目:

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456"}
链接到可配置选项卡本身：

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123&context={"channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}
链接到可配置选项卡中的任务项：

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456","channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}
链接到添加到会议或群组聊天的选项卡应用:

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456?context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

重要

确保所有查询参数和空格都正确编码了 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 配置选项卡的深层链接

可以通过 TeamsJS 在应用中配置深层链接，以允许应用用户浏览应用中的不同页面。以下代码演示如何导航到 Teams 应用中的特定实体：

TeamsJS v2
TeamsJS v1

可以使用 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 */ }

有关使用页面功能的详细信息，请参阅 pages.navigateToApp() 和其他导航选项的“页面”命名空间。如果需要，请使用 app.openLink () 函数直接打开深层链接。

若要从选项卡触发深层链接，请调用：

microsoftTeams.executeDeepLink(/*deepLink*/);

跨 Microsoft 365 Office 扩展的 Teams 应用的导航行为取决于两个因素：

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

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

配置深层链接以在选项卡之间导航

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*/});
}

以下代码演示如何导航到应用的默认选项卡：


if (pages.currentApp.isSupported()) {
    const navPromise = pages.currentApp.navigateToDefaultPage();
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}
else {/*Handle situation where capability isn't supported*/}

注意

选项卡应用导航仅在新的 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，请参阅不同类型的应用的应用 ID。

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

TeamsJS v2
TeamsJS v1

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

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

需要将以下参数替换为相应的信息：

subPageId：要向其进行深层链接的页面内项的唯一标识符。
subPageLabel：用于显示深层链接的项的标签。
subPageWebUrl：客户端无法呈现页面时使用的回退 URL。

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

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

microsoftTeams.shareDeepLink({ subEntityId: <subEntityId>, subEntityLabel: <subEntityLabel>, subEntityWebUrl: <subEntityWebUrl> })

需要将以下参数替换为相应的信息：

subEntityId：要向其进行深层链接的选项卡内项的唯一标识符。
subEntityLabel：用于显示深层链接的项的标签。
subEntityWebUrl：一个可选参数，其中包含在客户端不支持呈现选项卡时要使用的回退 URL。

注意

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

SharePoint 框架选项卡的深层链接

可以在机器人、连接器或消息扩展卡使用以下深层链接格式：https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>。

注意

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

查询参数为：

appID：清单 ID，例如 fe4a8eba-2a31-4737-8e33-e5fae6fee194。
entityID：在配置选项卡时提供的项 ID。例如 tasklist123。
entityWebUrl：具有回退 URL 的可选参数，在客户端不支持呈现选项卡时使用 - https://tasklist.example.com/123 或 https://tasklist.example.com/list123/task456。
entityName：选项卡中项的标签，用于显示深层链接时使用，例如 Task List 123 或 Task 456。

例如：https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&TaskList

用于打开对话框的深层链接

对话深层链接是对象的序列化 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_ID`中的 validDomains 数组必须包含的域（`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>.

示例：

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

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

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

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

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

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

用于调用 Stageview 的深层链接

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

代码示例

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

通过

指向应用程序的深层链接

用于打开应用程序安装对话框的深层链接

使用应用 ID 手动配置深层链接

不同类型的应用的应用 ID

用于在应用中浏览的深层链接

配置深层链接以手动浏览应用

使用 TeamsJS 配置选项卡的深层链接

配置深层链接以在选项卡之间导航

配置后退按钮导航

将焦点返回到主机应用

与应用程序的聊天的深层链接

SharePoint 框架选项卡的深层链接

用于打开对话框的深层链接

到会议侧面板的深层链接

用于调用 Stageview 的深层链接

代码示例

其他资源

通过

指向应用程序的深层链接

用于打开应用程序安装对话框的深层链接

使用应用 ID 手动配置深层链接

不同类型的应用的应用 ID

用于在应用中浏览的深层链接

配置深层链接以手动浏览应用

使用 TeamsJS 配置选项卡的深层链接

配置深层链接以在选项卡之间导航

配置后退按钮导航

将焦点返回到主机应用

与应用程序的聊天的深层链接

共享选项卡的深层链接

SharePoint 框架选项卡的深层链接

用于打开对话框的深层链接

生成深层链接以将内容共享到会议阶段

到会议侧面板的深层链接

用于调用 Stageview 的深层链接

代码示例

其他资源