获取选项卡的上下文

  • 项目

选项卡需要上下文信息才能显示相关内容：

  • 有关用户、团队或公司的基本信息。
  • 区域设置和主题信息。
  • page.id标识此选项卡中的内容的 和 page.subPageId (TeamsJS v.2.0.0) 之前称为 entityId 和 subEntityId 。

用户上下文

在以下情况下，有关用户、团队或公司的上下文特别有用：

  • 在应用中创建资源或将资源与指定的用户或团队相关联。
  • 从Microsoft Entra ID或其他标识提供者启动身份验证流，无需用户再次输入其用户名。

有关详细信息，请参阅 在 Microsoft Teams 中对用户进行身份验证。

重要

尽管此用户信息可以帮助提供流畅的用户体验，但不得将其用作标识证明。 例如，攻击者可以在浏览器中加载页面并呈现有害信息或请求。

访问上下文信息

可以通过两种方式访问上下文信息：

通过插入 URL 占位符值获取上下文

在配置或内容 URL 中使用占位符。 确定实际配置或内容 URL 时，Microsoft Teams 会使用相关值替换占位符。 可用的占位符包括 上下文 对象上的所有字段。 常见占位符包括以下属性：

  • {page.id}：首次配置页面时定义的页面的开发人员定义的唯 一 ID。 (在 TeamsJS v.2.0.0) 之前称为 {entityId} 。
  • {page.subPageId}：在为页面中的特定项目生成 深层链接 时定义的此内容点的子页面的开发人员定义的唯一 ID。 (在 TeamsJS v.2.0.0) 之前称为 {subEntityId} 。
  • {user.loginHint}：适合用作Microsoft Entra ID的登录提示的值。 这通常是其主租户中当前用户的登录名。 (在 TeamsJS v.2.0.0) 之前称为 {loginHint} 。
  • {user.userPrincipalName}：当前租户中当前用户的用户主体名称。 (在 TeamsJS v.2.0.0) 之前称为 {userPrincipalName} 。
  • {user.id}：当前租户中当前用户的Microsoft Entra对象 ID。 (在 TeamsJS v.2.0.0) 之前称为 {userObjectId} 。
  • {app.theme}：当前用户界面 (ui) 主题，例如 default、 dark或 contrast。 (在 TeamsJS v.2.0.0) 之前称为 {theme} 。
  • {team.groupId}：选项卡所在的 Microsoft 365 组的 ID。 (在 TeamsJS v.2.0.0) 之前称为{groupId}
  • {user.tenant.id}：当前用户的Microsoft Entra租户 ID。 (在 TeamsJS v.2.0.0) 之前称为 {tid} 。
  • {app.locale}：格式为 languageId-countryId 的用户的当前区域设置，例如 en-us。 (在 TeamsJS v.2.0.0) 之前称为 {locale} 。

注意

上一 {upn} 占位符现已弃用。 出于向后兼容性，它目前是 {user.loginHint}的同义词。

例如，如果在应用清单中将选项卡 configurationUrl 属性设置为 "https://www.contoso.com/config?name={user.loginHint}&tenant={user.tenant.id}&group={team.groupId}&theme={app.theme}" ，并且登录用户具有以下属性：

  • 其用户名为 user@example.com。
  • 其公司租户 ID 为 e2653c-etc。
  • 他们是 ID 为 00209384-etc 的 Microsoft 365 组的成员。
  • 用户已将其 Teams 主题设置为 深色。

Teams 在配置选项卡时调用以下 URL：

https://www.contoso.com/config?name=user@example.com&tenant=e2653c-etc&group=00209384-etc&theme=dark

使用 Microsoft Teams JavaScript 库获取上下文

还可以使用 Microsoft Teams JavaScript 客户端库检索上下文信息。

可以通过调用 microsoftTeams.app.getContext().then((context) => {/*...*/});来检索信息。

以下代码提供了上下文变量的示例：

{
 "app": {
   "host": {
     "clientType": "The type of host client. Possible values are android, ios, web, desktop, surfaceHub, teamsRoomsAndroid, teamsPhones, teamsDisplays rigel (deprecated, use teamsRoomsWindows instead)",
     "name": "",
     "ringId": "The current ring ID",
     "sessionId": "The unique ID for the current Teams session for use in correlating telemetry data"    },
   "iconPositionVertical": "",
   "locale": "The current locale of the user formatted as languageId-countryId (for example, en-us)",
   "osLocaleInfo": "",
   "parentMessageId": "The parent message ID from which this dialog is launched",
   "sessionId": "The unique ID for the current session used for correlating telemetry data",
   "theme": "The current UI theme: default | dark | contrast",
   "userClickTime": "",
   "userFileOpenPreference": ""  },
 "channel": {
   "defaultOneNoteSectionId": "The OneNote section ID that is linked to the channel",
   "displayName": "The name of the current channel",
   "id": "The channel ID in the format 19:[id]@thread.skype",
   "membershipType": "",
   "ownerGroupId": "",
   "ownerTenantId": "",
   "relativeUrl": "The relative path to the SharePoint folder associated with the channel"  },
 "chat": { "id": "The chat ID in the format 19:[id]@thread.skype" },
 "meeting": {
   "id": "The meeting ID used by tab when running in meeting context"  },
 "page": {
   "frameContext": "The context where tab URL is loaded (for example, content, task, setting, remove, sidePanel)",
   "id": "The developer-defined unique ID for the entity this content points to",
   "isFullScreen": "Indicates if the tab is in full-screen",
   "isMultiWindow": "The indication whether the tab is in a pop out window",
   "sourceOrigin": "",
   "subPageId": "The developer-defined unique ID for the sub-entity this content points to"  },
 "sharepoint": "The SharePoint context is available only when hosted in SharePoint",
 "sharepointSite": {
   "domain": "The domain of the root SharePoint site associated with the team",
   "path": "The relative path to the SharePoint site associated with the team",
   "url": "The root SharePoint site associated with the team"  },
 "team": {
   "displayName": "The name of the current team",
   "groupId": "Guid identifying the current Office 365 Group ID",
   "internalId": "The Microsoft Teams ID in the format 19:[id]@thread.skype",
   "isArchived": "Indicates if team is archived",
   "templateId": "",
   "type": "The type of team",
   "userRole": "The user's role in the team"  },
 "user": {
   "displayName": "",
   "id": "The Azure AD object id of the current user, in the current tenant",
   "isCallingAllowed": "Indicates if calling is allowed for the current logged in user",
   "isPSTNCallingAllowed": "Indicates if PSTN calling is allowed for the current logged in user",
   "licenseType": "The license type for the current user. Possible values are E1, E3, and E5 enterprise plans",
   "loginHint": "A value suitable as a login hint for Azure AD. This is usually the login name of the current user, in their home tenant",
   "tenant": {
     "id": "The Azure AD tenant ID of the current user",
     "teamsSku": "The license type for the current user tenant. Possible values are enterprise, free, edu, unknown"    },
   "userPrincipalName": "The principal name of the current user, in the current tenant"  }
}

TypeScript

import { app, Context } from "@microsoft/teams-js";

app.getContext().then((context: Context) => {
    /*...*/
});

等效 async/await 模式：

import { app, Context } from "@microsoft/teams-js";

async function example() {
  const context: Context = await app.getContext();
  /*...*/
}

JavaScript

import { app, Context } from "@microsoft/teams-js";

app.getContext().then((context) => {
    /*...*/
});

等效 async/await 模式：

import { app, Context } from "@microsoft/teams-js";

async function example() {
  const context = await app.getContext();
  /*...*/
}

下表列出了上下文对象的常用 上下文 属性：

TeamsJS v2 名称 TeamsJS v1 名称
team.internalId teamId
team.displayName teamName
channel.id channelId
channel.displayName channelName
chat.id chatId
app.locale 区域设置
page.id entityId
page.subPageId subEntityId
user.loginHint loginHint
user.userPrincipalName Upn
user.id userObjectId
user.tenant.id tid
team.groupId groupId
app.theme theme
page.isFullScreen isFullScreen
team.type teamType
sharepointSite.teamSiteUrl teamSiteUrl
sharepointSite.teamSiteDomain teamSiteDomain
sharepointSite.teamSitePath teamSitePath
channel.relativeUrl channelRelativeUrl
app.host.sessionId sessionId
team.userRole userTeamRole
team.isArchived isTeamArchived
app.host.clientType hostClientType
page.frameContext frameContext
sharepoint sharepoint
user.tenant.teamsSku tenantSKU
user.licenseType userLicenseType
app.parentMessageId parentMessageId
app.host.ringId ringId
app.sessionId appSessionId
user.isCallingAllowed isCallingAllowed
user.isPSTNCallingAllowed isPSTNCallingAllowed
meeting.id meetingId
channel.defaultOneNoteSectionId defaultOneNoteSectionId
page.isMultiWindow isMultiWindow

有关详细信息，请参阅上下文接口汇报和上下文接口 API 参考。

在专用频道中检索上下文

注意

专用频道目前仅提供个人开发人员预览版。

在专用频道中加载内容页面时，从 getContext 呼叫收到的数据会进行模糊处理，以保护通道的隐私。

当内容页面位于专用频道中时，以下字段会更改：

  • team.groupId：未定义专用频道
  • team.internalId：设置为专用频道的 threadId
  • team.displayName：设置为专用频道的名称
  • sharepointSite.url：设置为专用频道的不同、唯一的 SharePoint 网站的 URL
  • sharepointSite.path：设置为专用频道的不同、唯一的 SharePoint 网站的路径
  • sharepointSite.domain：设置为专用频道的不同、唯一 SharePoint 网站域的域
  • channel.ownerGroupId：设置为专用频道的主机团队组Id

如果页面使用这些值中的任何一个，字段的值 channel.membershipType 必须是 Private ，以确定页面是否在专用频道中加载，并且可以做出适当的响应。

注意

teamSiteUrl 也适用于标准通道。 如果页面使用这些值中的任何一个，字段的值 channelType 必须为 Shared ，以确定页面是否已加载到共享频道中，并且可以做出适当的响应。

获取共享频道中的上下文

在共享通道中加载内容 UX 时，使用从 getContext 调用收到的数据来更改共享通道。 如果选项卡使用以下任何值，则必须填充 channelType 字段以确定选项卡是否加载到共享频道中，并相应地做出响应。 对于共享频道， groupId 值为 null，因为主机团队的 groupId 无法准确反映共享频道的真实成员身份。 为了解决此问题，hostTeamGroupID新添加了 和 hostTenantID 属性，并且可用于调用 Microsoft 图形 API 来检索成员身份。 hostTeam 指创建共享频道的团队。 currentTeam 指当前用户从中访问共享频道的 Team。

有关这些概念和共享频道的详细信息，请参阅 共享频道。

在共享频道中使用以下 getContext 属性：

属性 说明
channelId 属性设置为共享通道线程 ID。
channelType 对于共享频道，属性设置为 sharedChannel 。
groupId 属性 null 适用于共享频道。
hostTenantId 属性是新添加的，用于描述主机的租户 ID，可用于与当前用户的 tid 租户 ID 属性进行比较。
hostTeamGroupId 属性是新添加的，描述主机团队的Microsoft Entra组 ID，对于进行 Microsoft 图形 API调用以检索共享频道成员身份非常有用。
teamId 属性是新添加的，并设置为当前共享团队的线程 ID。
teamName 属性设置为当前共享团队的 teamName。
teamType 属性设置为当前共享团队的 teamType。
teamSiteUrl 属性描述共享通道的 channelSiteUrl。
teamSitePath 属性描述共享通道的 channelSitePath。
teamSiteDomain 属性描述共享通道的 channelSiteDomain。
tenantSKU 属性描述主机团队的 tenantSKU。
tid 属性描述当前用户的租户 ID。
userObjectId 属性描述当前用户的 ID。
userPrincipalName 属性描述当前用户的 UPN。

有关共享频道的详细信息，请参阅 共享频道。

处理主题更改

重要

  • 默认情况下， 新的 Teams 客户端 支持 Teams 会议中的应用的浅色主题。 app.theme当 getContext API 中的 属性返回值时default，Teams 客户端处于浅色主题中。
  • 早期版本的 Teams 客户端仅支持 Teams 会议中应用的深色和对比度主题。

可以通过调用 microsoftTeams.app.registerOnThemeChangeHandler(function(theme) { /* ... */ })来注册应用，以在主题发生更改时收到通知。

theme函数中的 参数是值为 、 dark或 contrast的default字符串。

下图显示了 Teams 中的默认主题选项：

屏幕截图显示了 Teams 桌面客户端中的默认主题。

代码示例

示例名称 Description JavaScript
选项卡通道上下文 此示例演示如何在专用频道和共享频道中使用选项卡上下文对象的内容。 View

后续步骤

具有自适应卡片的生成选项卡

另请参阅