Biblioteca de clientes JavaScript do Teams

  • Artigo

A biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS) pode ajudá-lo a criar experiências hospedadas no Teams, aplicativo Microsoft 365 e Outlook, onde o conteúdo do aplicativo está hospedado em um iFrame. A biblioteca é útil para desenvolver aplicativos com os seguintes recursos do Teams:

A partir da versão 2.0.0, a biblioteca do TeamsJS existente (@microsoft/teams-jsou simplesmente TeamsJS) é refatorada para permitir que os aplicativos do Teams sejam executados no Outlook e no aplicativo Microsoft 365, além do Microsoft Teams. De uma perspectiva funcional, a versão mais recente do TeamsJS dá suporte a todas as funcionalidades de aplicativo do Teams existentes (v.1.x.x), ao mesmo tempo em que adiciona a capacidade opcional de hospedar aplicativos do Teams no Outlook e no aplicativo Microsoft 365.

Aqui estão as diretrizes de controle de versão atuais para vários cenários de aplicativo:

Tipo de aplicativo Versão do TeamsJS Versão do Manifesto do aplicativo Próximas etapas
Aplicativos do Teams estendidos entre Outlook e Microsoft 365 TeamsJS v.2.19.0 ou posterior v.1.13 ou posterior Estender um aplicativo do Teams para ser executado no Microsoft 365 ou Criar um novo aplicativo do Microsoft 365
Aplicativos apenas Teams existentes Atualizar para TeamsJS v.2.19.0 quando possível (v.1.12 ainda tem suporte*) 1.12 Entender a compatibilidade com versões anteriores do TeamsJSe Atualizar para o TeamsJS v.2.0
Novos aplicativos apenas Teams TeamsJS v.2.19.0 ou posterior 1.12 Criar um novo aplicativo Teams usando o Kit de Ferramentas do Teams

*Use o TeamsJS mais recente (v.2.19.0 ou posterior) sempre que possível, para aproveitar as melhorias mais recentes e o suporte a novos recursos, incluindo aplicativos somente do Teams. O TeamsJS v.1.12 continua com suporte, no entanto, nenhum novo recurso ou melhorias será adicionado. Os esquemas 1.12 e 1.13 são os mesmos. Para obter mais informações, confira Biblioteca do TeamsJS.

O restante deste artigo orienta você sobre a estrutura e as atualizações mais recentes para a biblioteca do TeamsJS.

Suporte ao Microsoft 365 (executando aplicativos do Teams no Microsoft 365 e Outlook)

O TeamsJS v.2.0 introduz a capacidade de determinados tipos de aplicativos do Teams serem executados em todo o ecossistema do Microsoft 365. Atualmente, outros hosts de aplicativos do Microsoft 365 (incluindo o aplicativo Microsoft 365 e o Outlook) para aplicativos do Teams dão suporte a um subconjunto dos tipos de aplicativo e recursos que você pode criar para a plataforma do Teams. Esse suporte se expande ao longo do tempo. Para obter um resumo do suporte de host para aplicativos do Teams, consulte Suporte à funcionalidade do TeamsJS em todo o Microsoft 365.

Novidades no TeamsJS versão 2.x.x

Há duas alterações significativas entre as versões do TeamsJS 1.x.x e a v.2.0.0 e posterior:

Dica

Você pode usar a extensão Kit de ferramentas do Teams para Microsoft Visual Studio Code para simplificar o TeamsJS v.2.0 para um aplicativo do Teams existente.

Compatibilidade com versões anteriores

Depois de começar a fazer referência @microsoft/teams-js@2.0.0 (ou posterior) a partir de um aplicativo do Teams existente, você verá avisos de depreciação para qualquer APIs de chamada de código que sejam alteradas.

Uma camada de tradução de API (mapeamento v.1 para chamadas de API do TeamsJS v.2) é fornecida para permitir que os aplicativos do Teams existentes continuem trabalhando no Teams até que eles possam atualizar o código do aplicativo para usar os padrões de API do TeamsJS v.2.

Autenticação

Na TeamsJS versão 2.11.0 ou posterior, os aplicativos devem fornecer um terceiro parâmetro de url, hostRedirectUrl, na API de autenticação, para redirecionar os usuários para o cliente correto após a conclusão da autenticação. O hostRedirectUrl parâmetro de autenticação é necessário para permitir que seu cliente tenha suporte em aplicativos host do Microsoft 365. Os aplicativos implementados em versões mais antigas TeamsJS só dão suporte ao Teams após essa atualização, pois os oauthRedirectmethod parâmetros de consulta e authId são passados para o servidor de aplicativo de terceiros.

Para obter mais informações sobre o parâmetro de autenticação, consulte usar provedores OAuth externos.

Aplicativos do Teams em execução no Microsoft 365

A seguir estão os requisitos para permitir que um aplicativo do Teams existente seja executado no Outlook e no Microsoft 365:

  1. Dependência do TeamsJS versão 2.x.x ( @microsoft/teams-js@2.0.0) ou posterior.

  2. Modifique o código do aplicativo existente de acordo com as alterações necessárias descritas neste artigo.

  3. Atualize o manifesto do aplicativo (anteriormente chamado de manifesto do aplicativo teams) para a versão 1.13 ou posterior.

Para obter mais informações, consulte Estender aplicativos do Teams no Microsoft 365.

Retornos de chamada convertidos em promessas

Observação

A getTabInstances API não é implementada no Teams mobile.

As APIs do Teams que anteriormente pegaram um parâmetro de retorno de chamada são atualizadas para retornar um objeto JavaScript Promise . Elas incluem as seguintes APIs:

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.navigateToTab, pages.tabs.getMruTabInstances, pages.tabs.getTabInstances, pages.getConfig, pages.config.setConfig, pages.backStack.navigateBack, people.selectPeople, teams.fullTrust.getConfigSetting, teams.fullTrust.joinedTeams.getUserJoinedTeams

Você precisa atualizar a maneira como seu código chama qualquer uma dessas APIs para usar Promessas. Por exemplo, se o código estiver chamando uma API Teams como esta:

Este código:

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

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

Precisa ser atualizado para:

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

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

... ou o padrão async/await equivalente:

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

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

Dica

Quando você usa o Kit de ferramentas do Teams para atualizar para o TeamsJS v.2.0, as atualizações necessárias são sinalizadas para você com TODO comentários no código do cliente.

APIs organizadas em funcionalidades

Uma funcionalidade é um agrupamento lógico de APIs que fornecem funcionalidade semelhante. Você pode pensar no aplicativo Microsoft Teams, Outlook e Microsoft 365, como hosts para seu aplicativo de guias. Um host dá suporte a uma determinada funcionalidade se ele dá suporte a todas as APIs definidas dentro dessa funcionalidade. Um host não pode implementar parcialmente uma funcionalidade. Os recursos podem ser baseados em recursos ou conteúdo, como diálogo autenticação ou caixa de diálogo. Também há recursos para tipos de aplicativo, como páginas e outros agrupamentos.

Na Versão Prévia do SDK do TeamsJS v2.0, as APIs são definidas como funções em um namespace JavaScript cujo nome corresponde à funcionalidade necessária. Se um aplicativo estiver em execução em um host que dê suporte à funcionalidade caixa de diálogo, o aplicativo poderá chamar APIs com segurança, como dialog.open (além de outras APIs relacionadas à caixa de diálogo definidas no namespace). Se um aplicativo tentar chamar uma API que não tenha suporte nesse host, a API gerará uma exceção.

Dica

Você pode verificar o suporte de host de uma determinada funcionalidade em runtime chamando a função isSupported() nessa funcionalidade (namespace).

Diferenciar sua experiência de aplicativo

Você pode verificar o suporte de host de uma determinada funcionalidade em runtime chamando a função isSupported() nessa funcionalidade (namespace). Ele retornará true se tiver suporte e false , se não, e você poderá ajustar o comportamento do aplicativo conforme apropriado. Isso permite que seu aplicativo ilumine a interface do usuário e a funcionalidade em hosts que dão suporte a ele, enquanto continua a ser executado para hosts que não têm.

O nome do host em que seu aplicativo opera é exibido como um valor de enumeração HostName da Context interface (app.Context.app.host.name). Você pode consultar isso em runtime invocando getContext. Para o cliente Do Teams Clássico, esse valor pode retornar como desconhecido ou indefinido. Nesse caso, mapeie esses valores para o Classic Teams.

O {hostName}valor do espaço reservado da URL também está disponível. No entanto, recomendamos usar o mecanismo hostName com discrição.

  • Não suponha que determinada funcionalidade esteja ou não esteja disponível em um host com base no valor da propriedade hostName. Em vez disso, verifique se há suporte para funcionalidades (isSupported).
  • Não use hostName para enviar chamadas à API. Em vez disso, verifique se há suporte para funcionalidades (isSupported).
  • UsehostName para diferenciar o tema do seu aplicativo com base no host em que ele está sendo executado. Por exemplo, você pode usar Microsoft Teams púrpura como a cor de destaque principal ao executar em Teams e Outlook azul ao executar em Outlook.
  • UsehostNamepara diferenciar as mensagens mostradas para o usuário com base no host em que ele está sendo executado. Por exemplo, mostre Gerenciar suas tarefas no Microsoft 365 ao executar no Microsoft 365 na Web e Gerenciar suas tarefas no Teams ao executar no Teams.

Namespaces

A partir do TeamsJS v.2.0, as APIs são organizadas em funcionalidades por meio de namespaces. Vários novos namespaces de importância específica são aplicativo, páginas, caixa de diálogo e teamsCore.

namespace do aplicativo

O app namespace contém APIs de nível superior necessárias para o uso geral do aplicativo, entre o Teams, o aplicativo Microsoft 365 e o Outlook. Todas as APIs de vários outros namespaces do TeamsJS são movidas para o namespace a app partir de TeamsJS v.2.0:

Namespace original global (window) Novo namespace app
executeDeepLink app.openLink (renomeado)
initialize app.initialize
getContext app.getContext
registerOnThemeChangeHandler app.registerOnThemeChangeHandler
Namespace original appInitialization Novo namespace app
appInitialization.notifyAppLoaded app.notifyAppLoaded
appInitialization.notifySuccess app.notifySuccess
appInitialization.notifyFailure app.notifyFailure
appInitialization.notifyExpectedFailure app.notifyExpectedFailure
appInitialization.FailedReason enumeração app.FailedReason
appInitialization.ExpectedFailureReason enumeração app.ExpectedFailureReason
appInitialization.IFailedRequest enumeração app.IFailedRequest
appInitialization.IExpectedFailureRequest enumeração app.IExpectedFailureRequest
namespace de páginas

O pages namespace inclui funcionalidade para executar e navegar páginas da Web em vários hosts do Microsoft 365, incluindo Teams, aplicativo Microsoft 365 e Outlook. Ele também inclui vários sub-recursos, implementados como sub-namespaces.

Namespace original global (window) Novo namespace pages
setFrameContext pages.setCurrentFrame (renomeado)
initializeWithFrameContext pages.initializeWithFrameContext
registerFocusEnterHandler pages.registerFocusEnterHandler
registerFullScreenHandler pages.registerFullScreenHandler
returnFocus pages.returnFocus
shareDeepLink pages.shareDeepLink
Namespace original settings Novo namespace pages
settings.getSettings pages.getConfig (renomeado)
pages.tabs
Namespace original global (window) Novo namespace pages.tabs
getTabInstances pages.tabs.getTabInstances
getMruTabInstances pages.tabs.getMruTabInstances
Namespace original navigation Novo namespace pages.tabs
navigation.navigateToTab pages.tabs.navigateToTab
pages.config
Namespace original settings Novo namespace pages.config
settings.setSettings pages.config.setConfig (renomeado)
settings.setValidityState pages.config.setValidityState
settings.initialize pages.config.initialize
settings.registerOnSaveHandler pages.config.registerOnSaveHandler
settings.registerOnRemoveHandler pages.config.registerOnRemoveHandler
settings.Settings interface pages.config.Config (renomeado)
settings.SaveEvent interface pages.config.SaveEvent (renomeado)
settings.RemoveEvent interface pages.config.RemoveEvent (renomeado)
settings.SaveParameters interface pages.config.SaveParameters (renomeado)
settings.SaveEventImpl interface pages.config.SaveEventImpl (renomeado)
Namespace original global (window) Novo namespace pages.config
registerChangeConfigHandler pages.config.registerChangeConfigHandler (renomeado)
pages.backStack
Namespace original navigation Novo namespace pages.backStack
navigation.navigateBack pages.backStack.navigateBack
Namespace original global (window) Novo namespace pages.backStack
registerBackButtonHandler pages.backStack.registerBackButtonHandler
pages.appButton
Namespace original global (window) Novo namespace pages.appButton
registerAppButtonClickHandler pages.appButton.onClick (renomeado)
registerAppButtonHoverEnterHandler pages.appButton.onHoverEnter (renomeado)
registerAppButtonHoverLeaveEnter pages.appButton.onHoverLeave (renomeado)
FrameContext interface pages.appButton.FrameInfo (renomeado)
namespace da caixa de diálogo

Observação

As window.alertAPIs , window.confirme window.prompt usadas para exibir uma caixa de diálogo não têm suporte no novo Cliente do Teams. Recomendamos que você renderize uma caixa de diálogo dentro de seu próprio quadro, por exemplo, usando a caixa de diálogo Fluent V9 ou use a biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS) para exibir uma caixa de diálogo do Teams usando Cartão Adaptável ou um aninhado <iframe>.

O namespace de tarefas do TeamsJS é renomeado para caixa de diálogo e as seguintes APIs são renomeadas:

Namespace original tasks Novo namespace dialog
tasks.startTask dialog.url.open, dialog.url.bot.open, dialog.adaptiveCard.open, dialog.adaptiveCard.bot.open
tasks.submitTask dialog.url.submit (renomeado)
tasks.updateTask dialog.update (renomeado)
tasks.TaskModuleDimension enumeração dialog.DialogDimension (renomeado)
tasks.TaskInfo interface dialog.DialogInfo (renomeado)

Além disso, essa funcionalidade é dividida em duas subcapabilidades main, dialog.url para caixas de diálogo baseadas em HTML e dialog.adaptiveCard para caixas de diálogo baseadas em cartão adaptável, com subpaspaços adicionais para caixas de diálogo baseadas em bot.

namespace do teamsCore

Para generalizar a biblioteca do TeamsJS para executar outros hosts do Microsoft 365, como o aplicativo Microsoft 365 e o Outlook, a funcionalidade específica do Teams (originalmente no namespace global ) é movida para um namespace teamsCore :

Namespace original global (window) Novo namespace teamsCore
enablePrintCapability teamsCore.enablePrintCapability
print teamsCore.print
registerOnLoadHandler teamsCore.registerOnLoadHandler
registerBeforeUnloadHandler teamsCore.registerBeforeUnloadHandler

Atualizações para a interface de Contexto

A Context interface é movida para o app namespace e atualizada para agrupar propriedades semelhantes para uma melhor escalabilidade à medida que é executada no Outlook e no aplicativo Microsoft 365, além do Teams.

Uma nova propriedade app.Context.app.host.name é adicionada para habilitar guias para diferenciar a experiência do usuário, dependendo do aplicativo host.

Você também pode visualizar as alterações examinando a transformLegacyContextToAppContext função na origem do TeamsJS versão 2.x.x (app.ts arquivo).

Nome original na interface Context Novo local em app.Context
appIconPosition app.Context.app.iconPositionVertical
appLaunchId NÃO EXISTE NO 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
NA app.Context.app.host.name

Atualização para o TeamsJS versão 2.0

A maneira mais fácil de atualizar seu aplicativo teams com o TeamsJS versão 2.0.x é usar a extensão do Teams Toolkit para Visual Studio Code. Esta seção orienta você pelas etapas para fazer isso. Se preferir atualizar manualmente seu código, consulte os Retornos de chamada convertidos em promessas e APIs organizadas em seções de recursos para obter mais informações sobre as alterações necessárias na API.

1. Instale a extensão mais recente do kit de ferramentas do Teams Visual Studio Code

No Visual Studio Code Extensions Marketplace, pesquise o Teams Toolkit e instale a versão mais recente.

2. Atualizar referências do TeamsJS

Para ser executado no Outlook e no aplicativo Microsoft 365, seu aplicativo precisa depender do pacote @microsoft/teams-js@2.0.0npm (ou posterior). Para executar essas etapas manualmente e para obter mais informações sobre as alterações de API, consulte as seções a seguir sobre retornos de chamada convertidos em promessas e APIs organizadas em funcionalidades.

  1. Verifique se você tem o kit de ferramentas mais recente do Teams (versão 2.10.0 ou posterior)
  2. Abra a paleta de comandos: Ctrl+Shift+P
  3. Execute o comando Teams: Upgrade Teams JS SDK references to support Outlook and Microsoft 365 apps.

Após a conclusão, o utilitário terá atualizado seu package.json arquivo com a dependência do TeamsJS versão 2.x.x (@microsoft/teams-js@2.0.0 ou posterior) e seus *.js/.ts arquivos e *.jsx/.tsx serão atualizados com:

Importante

O código dentro de arquivos html não é suportado pelas ferramentas de atualização e exigirá alterações manuais.

3. Atualizar o manifesto do aplicativo (opcional)

Se você estiver atualizando um aplicativo do Teams para ser executado no aplicativo Microsoft 365 e no Outlook, também precisará atualizar o manifesto do aplicativo para a versão 1.13 ou posterior. Você pode fazer isso facilmente com o Kit de ferramentas do Teams ou manualmente.

  1. Abra a paleta de comandos: Ctrl+Shift+P
  2. Executar o Teams: atualize o manifesto do Teams para dar suporte ao comando de aplicativos do Outlook e do Microsoft 365 e selecione o arquivo de manifesto do aplicativo. Alterações são feitas em vigor.

Se você usou o Teams Toolkit para criar seu aplicativo pessoal, também poderá usá-lo para validar as alterações no arquivo de manifesto do aplicativo e identificar quaisquer erros. Abra a paleta de comandos Ctrl+Shift+P e localize o Teams: valide o arquivo de manifesto ou selecione a opção no menu Implantação do Kit de Ferramentas do Teams (procure o ícone do Teams no lado esquerdo do Visual Studio Code).

Opção

Próximas etapas