Biblioteca de clientes JavaScript do Teams
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-js
ou 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:
As funções de retorno de chamada agora retornam objetos Promise. A maioria das funções com parâmetros de retorno de chamada no TeamsJS v.1.12 são modernizadas para retornar um objeto JavaScript Promise para melhor manipulação de operações assíncronas e legibilidade de código.
As APIs agora estão organizadas em recursos. Você pode pensar em recursos como agrupamentos lógicos de APIs que fornecem funcionalidades semelhantes, como
authentication
,dialog
,chat
ecalendar
. Cada namespace representa uma funcionalidade separada.
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:
Dependência do TeamsJS versão 2.x.x (
@microsoft/teams-js@2.0.0
) ou posterior.Modifique o código do aplicativo existente de acordo com as alterações necessárias descritas neste artigo.
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.alert
APIs , window.confirm
e 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.0
npm (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.
- Verifique se você tem o kit de ferramentas mais recente do Teams (versão 2.10.0 ou posterior)
- Abra a paleta de comandos:
Ctrl+Shift+P
- 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:
package.json
referências ao TeamsJS versão 2.x.x- Importar instruções para o TeamsJS versão 2.x.x
- Chamadas de função, Enum e Interface para o TeamsJS versão 2.x.x
TODO
lembretes de comentário para examinar áreas que podem ser afetadas por alterações de contextoTODO
lembretes de comentário para converter funções de retorno de chamada em promessas
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.
- Abra a paleta de comandos:
Ctrl+Shift+P
- 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).
Próximas etapas
- Use a referência da biblioteca do TeamsJS para começar a usar a biblioteca do TeamsJS.
- Examine o changelog para obter atualizações mais recentes no TeamsJS.
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de