团队 JavaScript 客户端 SDK

Microsoft Teams JavaScript 客户端 SDK 可帮助你在 Teams、Office 和 Outlook 中创建托管体验,其中应用内容托管在 iframe 中。 SDK 有助于开发具有以下 Teams 功能的应用:

从版本 2.0.0 开始,除了 Microsoft Teams 之外,还重构了现有的 Teams 客户端 SDK(@microsoft/teams-js 或简称 TeamsJS),以使 Teams 应用能够在 Outlook 和 Office 中运行。 从功能角度来看,最新版本的 TeamsJS 支持所有现有的 (v.1.x.x) Teams 应用功能,同时添加在 Outlook 和 Office 中托管 Teams 应用的可选功能。

下面是各种应用方案的当前版本控制指南:

TeamsJS 版本 应用清单版本 后续步骤
扩展到 Office/Outlook 的 Teams 应用 TeamsJS v.2.0 或更高版本 1.13 或更高版本 扩展 Teams 应用以跨 Microsoft 365 运行创建新的 Microsoft 365 应用
仅限 Teams 的现有应用 如果可能,仍支持更新到 TeamsJS v.2.0 (v.1.12*) 。 1.12 了解 TeamsJS 向后兼容性TeamsJS v.2.0 更新
仅限 Teams 的新应用 TeamsJS v.2.0 或更高版本 1.12 使用 Teams 工具包创建新的 Teams 应用

*尽可能使用最新的 TeamsJS(v.2.0 或更高版本),以利用最新的改进和新功能支持(包括仅限 Teams 的应用)。TeamsJS v.1.12 继续受到支持,但不会添加任何新功能或改进。否则,1.12 和 1.13 架构将相同。有关 TeamsJS 的详细信息,请参阅 Teams JavaScript 客户端 SDK

本文的其余部分将引导你了解 Teams JavaScript 客户端 SDK 的结构和最新更新。

Microsoft 365 支持(在 Office 和 Outlook 中运行 Teams 应用)

TeamsJS v.2.0 为某些类型的 Teams 应用引入了在 Microsoft 365 生态系统中运行的能力。 目前,适用于 Teams 应用的其他 Microsoft 365 应用程序主机(包括 Office 和 Outlook)支持一部分可为 Teams 平台构建的应用程序类型和功能。 此支持将随时间推移而扩展。 有关 Teams 应用的主机支持摘要,请参阅跨 Microsoft 365 扩展 Teams 应用

下表列出了 Teams 选项卡和对话框(任务模块)功能(公共命名空间),以及对在其他 Microsoft 365 主机中运行的扩展支持。

提示

可通过对给定功能(命名空间)调用 isSupported() 函数,来在运行时检查主机是否支持该功能。

功能 主机支持 注释
应用 Teams、Outlook、Office、适用于 Android 的 Office 应用 表示应用初始化和生命周期的命名空间。
appInitialization 已弃用。 替换为 app 命名空间。
appInstallDialog Teams、Office
身份验证 Teams、Outlook、Office、适用于 Android 的 Office 应用
日历 Outlook(仅限 Windows 桌面版)
通话 Teams
聊天 Teams
对话框 Teams、Outlook、Office 表示对话的命名空间(以前称为“任务模块”。 请参阅有关对话的说明。
地理位置
位置 Teams 请参阅有关应用权限的说明。
mail Outlook(仅限 Windows 桌面版)
媒体 Teams 请参阅有关应用权限的说明。
菜单 Teams
货币 Teams
pages Teams、Outlook、Office、适用于 Android 的 Office 应用 表示页面导航的命名空间。 请参阅有关深层链接的说明。
people Teams
个人资料
search
共享 Teams
settings 已弃用。 已被 pages.config 取代。
stageView Teams
tasks 已弃用。 已被 dialog 功能取代。 请参阅有关对话的说明。
teamsCore Teams 包含 Teams 特定功能的命名空间。
video Teams
webStorage Teams

应用权限

在 Teams 外部运行的应用尚不支持要求用户授予设备权限的应用功能(例如位置)。 在 Outlook 或 Office 中运行时,当前无法在“设置”或应用标头中检查应用权限。 如果在 Office 或 Outlook 中运行的 Teams 应用调用触发设备权限的 TeamsJS(或 HTML5)API,则该 API 将生成错误,并且无法显示要求用户同意的系统对话框。

当前的指导是修改代码以捕获故障:

  • 在使用某项功能之前检查它的 isSupported()mediameetingfiles 尚不支持 isSupported 调用,并且尚不能在 Teams 之外使用。
  • 在调用 TeamsJS 和 HTML5 API 时捕获和处理错误。

当 API 不受支持或生成错误时,请添加逻辑以正常失败或提供解决方法。 例如:

  • 将用户定向到应用的网站。
  • 指示用户使用 Teams 中的应用完成流。
  • 通知用户功能尚不可用。

此外,最佳做法是确保应用清单仅指定它使用的设备权限。

深层链接

在 TeamsJS 版本 2.0 之前,所有深层链接方案都是使用 shareDeepLink(生成指向应用特定部分的链接)和 executeDeepLink应用或在应用导航到深层链接)处理的。 TeamsJS v.2.0 引入了一个新的 API navigateToApp,用于以一致的方式跨应用主机(Office 和 Outlook 以及 Teams)导航到应用中的页面(和子页)。 下面是深层链接方案的更新指南:

使用 pages.shareDeepLink(在 TeamsJS v.2.0 之前称为 shareDeepLink)生成并显示可复制链接供用户共享。 单击后,如果尚未为应用程序主机安装应用(在链接路径中指定),则系统会提示用户安装该应用。

使用新的 pages.navigateToApp API 在托管应用程序中的应用内导航。

此 API 等效于导航到深层链接(类似于现已弃用的 executeDeepLink),而无需应用构造 URL 或管理不同应用程序主机的不同深层链接格式。

对于从应用到其当前主机的各个区域的深层链接,请使用 TeamsJS SDK 提供的强类型 API。 例如,使用“日历”功能从应用打开计划对话框或日历项目。

对于从应用到同一主机中运行的其他应用的深层链接,请使用 pages.navigateToApp

对于任何其他外部深层链接方案,可以使用 app.openLink,它提供与现已弃用的(从 TeamsJS v.2.0 开始)executeDeepLink API 类似的功能。

对话框

从 TeamsJS 版本 2.0 开始,“任务模块”的 Teams 平台概念已重命名为“对话”,以便更好地与 Microsoft 365 开发人员生态系统中的现有概念保持一致。 因此,tasks 命名空间已被弃用,取而代之于新的 dialog 命名空间。

此新的对话功能将拆分为主要功能 (dialog)(用于支持基于 HTML 的对话)以及子功能 dialog.bot(用于基于机器人的对话开发)。

对话功能尚不支持自适应卡片对话。 仍需使用 tasks.startTask() 调用基于自适应卡片的对话。

dialog.open 函数当前仅适用于打开基于 HTMl 的对话,并返回可用于将消息 (ChildAppWindow.postMessage) 传递到新打开的对话的回调函数 (PostMessageChannel)。 dialog.open 会返回回调(而不是 Promise),因为它不需要应用执行来暂停等待对话关闭(从而为各种用户交互模式提供更大的灵活性)。

TeamsJS 版本 2.x.x 中的新增功能

TeamsJS 1.x.x 版本和 v.2.0.0 及更高版本之间有两个重大更改:

  • 回调函数现在返回 Promise 对象。 TeamsJS v.1.12 中具有回调参数的大多数函数已经过现代化,以返回 JavaScript Promise 对象,以便改进异步操作的处理和代码可读性。

  • API 现在已组织到 功能中。 可以将功能视为提供类似功能的 API 的逻辑分组,例如 authenticationdialogchatcalendar。 每个命名空间都表示一个单独的功能。

提示

可以使用适用于 Microsoft Visual Studio Code 的 Teams 工具包扩展来简化现有 Teams 应用的 TeamsJS 版本 2.x.x 更新过程

向后兼容

从现有 Teams 应用开始引用 @microsoft/teams-js@2.0.0(或更高版本)后,你将看到已更改的任何代码调用 API 的弃用警告。

提供了 API 转换层(将 v.1 SDK 映射到 v.2 SDK API 调用),使现有 Teams 应用能够继续在 Teams 中工作,直到它们能够更新应用程序代码以使用 TeamsJS v.2 API 模式。

仅限 Teams 的应用

即使你希望应用仅在 Teams(而不是 Office 和 Outlook)中运行,最佳做法是尽快开始引用最新的 TeamsJS(v.2.0 或更高版本),以便从最新改进、新功能和支持(甚至对于仅限 Teams 的应用)中获益。 将继续支持 TeamsJS v.1.12,但不会添加任何新功能或改进。

完成后,下一步是使用本文中所述的更改更新现有应用程序代码。 在此期间,v.1 到 v.2 API 转换层提供向后兼容性,确保现有 Teams 应用继续在 TeamsJS 版本 2.0 中工作。

跨 Microsoft 365 运行的 Teams 应用

使现有 Teams 应用能够在 Outlook 和 Office 中运行需要满足以下所有条件:

  1. TeamsJS 版本 2.x.x ( @microsoft/teams-js@2.0.0) 或更高版本的依赖项,

  2. 根据本文中所述的所需更改修改现有应用程序代码,以及

  3. 将应用清单更新到版本 1.13 或更高版本。

有关详细信息,请参阅跨 Microsoft 365 扩展 Teams 应用

转换为 promise 的回调

以前使用回调参数的 Teams API 已更新为返回 JavaScript Promise 对象。 其中包括以下 API:

app.getContext, app.initialize, appInstallDialog.openAppInstallDialog, app.openLink, authentication.authenticate, authentication.getAuthToken, authentication.getUser, authentication.registerAuthenticationHandlers was removed to support using Promises, calendar.openCalendarItem, calendar.composeMeeting, call.startCall, chat.getChatMembers, conversations.openConversation, location.getLocation, location.showLocation, mail.openMailItem, mail.composeMail, pages.backStack.navigateBack, pages.navigateCrossDomain, pages.navigateToTab, pages.tabs.getMruTabInstances, pages.tabs.getTabInstances, pages.getConfig, pages.config.setConfig, pages.backStack.navigateBack, people.selectPeople, teams.fullTrust.getConfigSetting, teams.fullTrust.joinedTeams.getUserJoinedTeams

需要更新代码调用这些 API 的方式才能使用 Promise。 例如,如果代码正调用 Teams API,如下所示:

此代码:

import microsoftTeams from "@microsoft/teams-js";

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

需要更新为:

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

提示

使用 Teams 工具包更新到 TeamsJS v.2.x.x 时,在客户端代码中使用注释为你 TODO 标记所需的更新。

组织为功能的 API

功能是提供类似功能的 API 的逻辑分组(通过命名空间)。 你可以将 Microsoft Teams、Outlook 和 Office 视为选项卡应用的主机。 如果主机支持该功能中定义的所有 API,则它支持给定功能。 主机无法部分实现功能。 功能可以基于特性或内容,例如身份验证对话。 应用程序类型也有一些功能,例如页面和其他分组。

从 TeamsJS v.2.0 开始,API 定义为 JavaScript 命名空间中名称与其所需功能匹配的函数。 例如,如果应用在支持对话功能的主机中运行,则应用可以安全地调用 API,例如 dialog.open(以及命名空间中定义的其他对话相关 API)。 如果应用尝试调用该主机中不支持的 API,则 API 将生成异常。 若要验证运行应用的当前主机是否支持给定功能,请调用其命名空间的 isSupported() 函数。

区分应用体验

可以通过对给定功能(命名空间)调用 isSupported() 函数,在运行时检查主机是否支持该功能。 如果支持,则返回 true;如果不支持,则返回 false,并且可以根据需要调整应用行为。 这样,应用便能在支持它的主机中亮起 UI 和功能,同时继续为不支持的主机运行。

运行应用之主机的名称作为 Context 接口 (app.Context.app.host.name) 上的 hostName 属性公开,可在运行时通过调用 getContext 进行查询。 它还可用作 {hostName}URL 占位符值。 最佳做法是谨慎使用 hostName 机制:

  • 请勿根据 hostName 属性值假设某个功能在主机中可用或不可用。 相反,请检查功能支持 (isSupported)。
  • 请勿使用 hostName 控制 API 调用。 相反,请检查功能支持 (isSupported)。
  • 使用 hostName 根据运行应用程序的主机来区分应用程序的主题。 例如,在 Teams 中运行时,可以使用 Microsoft Teams 紫色作为主要主题色;在 Outlook 中运行时,可以使用 Outlook 蓝色。
  • 使用 hostName 根据运行主机来区分向用户显示的消息。 例如,例如,在 Office 网页版中运行时显示“在 Office 中管理任务”,在 Teams 中运行时显示“在 Teams 中管理任务”。

命名空间

从 TeamsJS v.2.0 开始,API 通过命名空间组织成功能。 一些特别重要的新命名空间包括 apppagesdialogteamsCore

app 命名空间

app 命名空间包含跨 Teams、Office 和 Outlook 的整体应用使用所需的顶级 API。 从 TeamsJS v.2.0 开始,其他各种 TeamsJS 命名空间中的所有 API 都已移动到 app 命名空间:

原始命名空间 global (window) 新命名空间 app
executeDeepLink app.openLink(已重命名)
initialize app.initialize
getContext app.getContext
registerOnThemeChangeHandler app.registerOnThemeChangeHandler
原始命名空间 appInitialization 新命名空间 app
appInitialization.notifyAppLoaded app.notifyAppLoaded
appInitialization.notifySuccess app.notifySuccess
appInitialization.notifyFailure app.notifyFailure
appInitialization.notifyExpectedFailure app.notifyExpectedFailure
appInitialization.FailedReason 枚举 app.FailedReason
appInitialization.ExpectedFailureReason 枚举 app.ExpectedFailureReason
appInitialization.IFailedRequest 枚举 app.IFailedRequest
appInitialization.IExpectedFailureRequest 枚举 app.IExpectedFailureRequest
pages 命名空间

pages 命名空间包括用于在各种 Microsoft 365 主机(包括 Teams、Office 和 Outlook)中运行和导航网页的功能。 它还包括多个子功能,作为子名称空间实现。

原始命名空间 global (window) 新命名空间 pages
setFrameContext pages.setCurrentFrame(已重命名)
initializeWithFrameContext pages.initializeWithFrameContext
registerFocusEnterHandler pages.registerFocusEnterHandler
registerFullScreenHandler pages.registerFullScreenHandler
navigateCrossDomain pages.navigateCrossDomain
returnFocus pages.returnFocus
shareDeepLink pages.shareDeepLink
原始命名空间 settings 新命名空间 pages
settings.getSettings pages.getConfig(已重命名)
pages.tabs
原始命名空间 global (window) 新命名空间 pages.tabs
getTabInstances pages.tabs.getTabInstances
getMruTabInstances pages.tabs.getMruTabInstances
原始命名空间 navigation 新命名空间 pages.tabs
navigation.navigateToTab pages.tabs.navigateToTab
pages.config
原始命名空间 settings 新命名空间 pages.config
settings.setSettings pages.config.setConfig(已重命名)
settings.setValidityState pages.config.setValidityState
settings.initialize pages.config.initialize
settings.registerOnSaveHandler pages.config.registerOnSaveHandler
settings.registerOnRemoveHandler pages.config.registerOnRemoveHandler
settings.Settings 接口 pages.config.Config(已重命名)
settings.SaveEvent 接口 pages.config.SaveEvent(已重命名)
settings.RemoveEvent 接口 pages.config.RemoveEvent(已重命名)
settings.SaveParameters 接口 pages.config.SaveParameters(已重命名)
settings.SaveEventImpl 接口 pages.config.SaveEventImpl(已重命名)
原始命名空间 global (window) 新命名空间 pages.config
registerChangeConfigHandler pages.config.registerChangeConfigHandler(已重命名)
pages.backStack
原始命名空间 navigation 新命名空间 pages.backStack
navigation.navigateBack pages.backStack.navigateBack
原始命名空间 global (window) 新命名空间 pages.backStack
registerBackButtonHandler pages.backStack.registerBackButtonHandler
pages.appButton
原始命名空间 global (window) 新命名空间 pages.appButton
registerAppButtonClickHandler pages.appButton.onClick(已重命名)
registerAppButtonHoverEnterHandler pages.appButton.onHoverEnter(已重命名)
registerAppButtonHoverLeaveEnter pages.appButton.onHoverLeave(已重命名)
FrameContext 接口 pages.appButton.FrameInfo(已重命名)
dialog 命名空间

TeamsJS tasks 命名空间已重命名为 dialog,并且已重命名以下 API:

原始命名空间 tasks 新命名空间 dialog
tasks.startTask dialog.open(已重命名)
tasks.submitTasks dialog.submit(已重命名)
tasks.updateTasks dialog.update.resize(已重命名)
tasks.TaskModuleDimension 枚举 dialog.DialogDimension(已重命名)
tasks.TaskInfo 接口 dialog.DialogInfo(已重命名)

此外,此功能已拆分为主要功能 (dialog)(用于支持基于 HTML 的对话)以及子功能 dialog.bot(用于基于机器人的对话)。

teamsCore 命名空间

若要将 TeamsJS SDK 通用化以运行其他 Microsoft 365 主机(如 Office 和 Outlook),Teams 特定的功能(最初在 global 命名空间中)已移动到 teamsCore 命名空间:

原始命名空间 global (window) 新命名空间 teamsCore
enablePrintCapability teamsCore.enablePrintCapability
print teamsCore.print
registerOnLoadHandler teamsCore.registerOnLoadHandler
registerBeforeUnloadHandler teamsCore.registerBeforeUnloadHandler

Context 接口更新

Context 接口已移动到 app 命名空间并更新为对类似属性进行分组,以便在 Outlook 和 Office 以及 Teams 中运行时获得更好的可扩展性。

添加了一个新属性 app.Context.app.host.name,使选项卡能够根据主机应用程序区分用户体验。

还可以通过查看 transformLegacyContextToAppContextTeamsJS 版本 2.x.x 源 中的函数 (app.ts 文件) 来可视化更改。

接口中的 Context 原始名称 app.Context 中的新位置
appIconPosition app.Context.app.iconPositionVertical
appLaunchId 不在 TeamsJS v.2.0 中
appSessionId app.Context.app.sessionId
channelId app.Context.channel.id
channelName app.Context.channel.displayName
channelRelativeUrl app.Context.channel.relativeUrl
channelType app.Context.channel.membershipType
chatId app.Context.chat.id
defaultOneNoteSectionId app.Context.channel.defaultOneNoteSectionId
entityId app.Context.page.id
frameContext app.Context.page.frameContext
groupId app.Context.team.groupId
hostClientType app.Context.app.host.clientType
hostTeamGroupId app.Context.channel.ownerGroupId
hostTeamTenantId app.Context.channel.ownerTenantId
isCallingAllowed app.Context.user.isCallingAllowed
isFullScreen app.Context.page.isFullScreen
isMultiWindow app.Context.page.isMultiWindow
isPSTNCallingAllowed app.Context.user.isPSTNCallingAllowed
isTeamArchived app.Context.team.isArchived
locale app.Context.app.locale
loginHint app.Context.user.loginHint
meetingId app.Context.meeting.id
osLocaleInfo app.Context.app.osLocaleInfo
parentMessageId app.Context.app.parentMessageId
ringId app.Context.app.host.ringId
sessionId app.Context.app.host.sessionId
sourceOrigin app.Context.page.sourceOrigin
subEntityId app.Context.page.subPageId
teamId app.Context.team.internalId
teamSiteDomain app.Context.sharepointSite.domain
teamSitePath app.Context.sharepointSite.path
teamSiteUrl app.Context.sharepointSite.url
teamTemplateId app.Context.team.templateId
teamType app.Context.team.type
tenantSKU app.Context.user.tenant.teamsSku
tid app.Context.user.tenant.id
upn app.Context.user.userPrincipalName
userClickTime app.Context.app.userClickTime
userFileOpenPreference app.Context.app.userFileOpenPreference
userLicenseType app.Context.user.licenseType
userObjectId app.Context.user.id
userTeamRole app.Context.team.userRole
不适用 app.Context.app.host.name

更新到最新的 Teams 客户端版本

更新 Teams 应用以使用 TeamsJS v.2.x.x 的最简单方法是使用适用于Visual Studio Code的 Teams 工具包扩展。 本部分将指导你完成执行此操作的步骤。 如果希望手动更新代码,请参阅转换为 promise 的回调组织为功能的 API 部分,以获取有关所需 API 更改的更多详细信息。

1. 安装最新的 Teams 工具包 Visual Studio Code 扩展

Visual Studio Code 扩展商城中,搜索“Teams 工具包”并安装版本 2.10.0 或更高版本。

2. 更新 SDK 引用

若要在 Outlook 和 Office 中运行,你的应用需要依赖于 npm 包@microsoft/teams-js@2.0.0 (或更高版本) 。 若要手动执行这些步骤以及有关 API 更改的详细信息,请参阅以下部分转换为 promise 的回调组织为功能的 API

  1. 确保拥有 Teams 工具包v.2.10.0 或更高版本
  2. 打开 命令面板 Ctrl+Shift+P
  3. 运行命令 Teams: Upgrade Teams JS SDK references to support Outlook and Office apps

完成后,实用工具将使用 TeamsJS 版本 2.x.x (或更高版本更新package.json文件) 依赖项,并且你的 *.js/.ts*.jsx/.tsx 文件将更新@microsoft/teams-js@2.0.0为:

重要

升级工具不支持 html 文件中的代码,需要手动更改。

3. 更新清单(可选)

如果要更新 Teams 应用以在 Office 和 Outlook 中运行,则还需要将应用清单更新为版本 1.13 或更高版本。 可以使用 Teams 工具包轻松执行此操作,也可以手动执行此操作。

  1. 打开命令面板Ctrl+Shift+P
  2. 运行“Teams:升级 Teams 清单以支持 Outlook 和 Office 应用”命令并选择应用清单文件。 将进行更改。

如果使用 Teams 工具包创建了个人应用,则还可以使用它来验证清单文件的更改并识别任何错误。 打开命令面板 Ctrl+Shift+P 并找到“Teams:验证清单文件”,或者从 Teams 工具包的“部署”菜单中选择选项(查找 Visual Studio Code 左侧的 Teams 图标)。

 Teams 工具包“部署”菜单下的“验证清单文件”选项

后续步骤

  • 使用 TeamsJS 引用开始使用 Microsoft Teams JavaScript 客户端 SDK。
  • 查看 更改日志 ,了解 TeamsJS 的最新更新。