Biblioteca de cliente JavaScript do Teams

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

• Guias
• Caixas de diálogo (chamadas de módulos de tarefas no TeamsJS v1.x)

A partir da versão 2.0.0, a biblioteca 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 existentes do aplicativo Teams (v.1.x.x), adicionando 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 para vários cenários de aplicativo:

* Use o TeamsJS mais recente para aproveitar as melhorias mais recentes e o suporte a novos recursos, incluindo aplicativos somente do Teams. Nenhum novo recurso ou melhoria será adicionado ao TeamsJS v1.13.0. Novos envios e atualizações de aplicativos agora exigem o TeamsJS v2.19.0 ou posterior. Para obter mais informações, consulte Biblioteca TeamsJS.

** Ao atualizar sua guia pessoal do Teams ou aplicativo de extensão de mensagem para o manifesto versão 1.13 ou posterior, ele se torna disponível em hosts Microsoft 365 por padrão. Para evitar o carregamento parcial em hosts sem suporte e garantir uma experiência de usuário consistente, defina os requisitos de tempo de execução no manifesto para controlar onde e como seu aplicativo aparece. Para obter mais informações, consulte Especificar requisitos de tempo de execução de host do Microsoft 365 no manifesto do aplicativo.

O restante deste artigo orienta você pela estrutura e pelas atualizações mais recentes da biblioteca TeamsJS.

Suporte do Microsoft 365 (execução de 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. Os outros hosts de aplicativo 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 Teams. Esse suporte se expande ao longo do tempo. Para obter um resumo do suporte do host para aplicativos do Teams, consulte Suporte de recursos do TeamsJS no Microsoft 365.

Melhorar o desempenho do tempo de carregamento com a trepidação da árvore JavaScript

A partir da versão 2.31.0 e posterior, a biblioteca TeamsJS pode ser totalmente abalada em árvore. A agitação da árvore é uma otimização JavaScript que elimina o código não utilizado. Usando a trepidação de árvore quando um aplicativo é empacotado para implantação, você pode reduzir o tamanho do pacote, o que resulta em download mais rápido e melhor tempo de carregamento.

Como usar a trepidação de árvore com o TeamsJS

Para aproveitar a agitação da árvore ao agrupar o pacote do aplicativo, use um empacotador que dê suporte à vibração da árvore, como webpack ou Rollup. Quando a trepidação de árvore está habilitada, todo o código TeamsJS não utilizado é removido automaticamente no pacote final. Por exemplo, considere o seguinte código:

export function scanBarCode(barCodeConfig: BarCodeConfig): Promise<string> {
   //implementation omitted
}

export function hasPermission(): Promise<boolean>{
   //implementation omitted
}

export function requestPermission(): Promise<boolean>{
   //implementation omitted
}

export function isSupported(): boolean {
   //implementation omitted
}

Suponha que o módulo barCode no TeamsJS contenha as quatro funções hasPermission(), isSupported(), requestPermission(), e scanBarCode(BarCodeConfig). Se um aplicativo usar apenas a função, após a hasPermission() agitação da árvore, as outras três funções serão excluídas do pacote do aplicativo. Isso garante que os aplicativos permaneçam o mais leves possível e incluam apenas o código de que precisam.

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 melhorar o manuseio de operações assíncronas e a legibilidade do código.

• As APIs agora estão organizadas em recursos. Você pode pensar em recursos como agrupamentos lógicos de APIs que fornecem funcionalidade semelhante, como authentication, dialog, chat, e calendar. Cada namespace representa uma funcionalidade separada.

Compatibilidade com versões anteriores

Depois de começar a referenciar @microsoft/teams-js@2.0.0 (ou posteriormente) de um aplicativo do Teams existente, você verá avisos de substituição para todas as APIs de chamada de código que forem alteradas.

Uma camada de conversão de API (mapeando chamadas de API TeamsJS v.1 a v.2) é fornecida para permitir que os aplicativos existentes do Teams continuem funcionando no Teams até que 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 oferecem suporte apenas ao Teams após essa atualização, pois os parâmetros de TeamsJS consulta e authId são passados oauthRedirectmethod para o servidor de aplicativos 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 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 do 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

As APIs do Teams que anteriormente recebiam 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 Promises. Por exemplo, se o código estiver chamando uma API Teams como esta:

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

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

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

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

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

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

import * as microsoftTeams from "@microsoft/teams-js";
microsoftTeams.app.getContext().then((context:  microsoftTeams.app.Context) => { 
/* ... */ 
});

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

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

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

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

A comunicação entre nuvens por meio do SDK é restrita por motivos de segurança; portanto, o Teams operado pelo domínio 21Vianet não está incluído no validOrigins. Para permitir que um aplicativo funcione no Teams operado pela 21Vianet, especifique o domínio Teams operado pela 21Vianet durante a inicialização do SDK na implantação do aplicativo, usando o parâmetro validMessageOrigins .

import { app } from '@microsoft/teams-js';
app.initialize(["https://teams.microsoftonline.cn"]);

APIs organizadas em funcionalidades

Uma funcionalidade é um agrupamento lógico de APIs que fornecem funcionalidade semelhante. Você pode pensar no Microsoft Teams, no Outlook e no aplicativo Microsoft 365 como hosts do seu aplicativo de guia. 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 tem suporte nesse host, a API gerará uma exceção.

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 retorna true se é compatível e false se não, e você pode 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 ContextHostName da interface (app.Context.app.host.name). Você pode consultar isso em tempo de execução invocando getContext. Para o cliente do Teams Clássico, esse valor pode retornar como desconhecido ou indefinido. Nesse caso, mapeie esses valores para o Teams Clássico.

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, no Teams, no aplicativo Microsoft 365 e no Outlook. Todas as APIs de vários outros namespaces do TeamsJS são movidas para o app namespace a partir do TeamsJS v.2.0:

namespace de páginas

O pages namespace inclui funcionalidade para executar e navegar em 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.

pages.tabs

pages.config

pages.backStack

pages.appButton

namespace da caixa de diálogo

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

Além disso, esse recurso é dividido em dois sub-recursos principais, 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 outros subnamespaces para caixas de diálogo baseadas em bot.

namespace do teamsCore

Para generalizar a biblioteca 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 ) foi movida para um namespace teamsCore :

Atualizações para a interface de Contexto

A Context interface foi movida para o app namespace e atualizada para agrupar propriedades semelhantes para 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 revisando a transformLegacyContextToAppContext função na fonte do TeamsJS versão 2.x.x (arquivo app.ts ).

Atualizando 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 Agents Toolkit para o Visual Studio Code. Esta seção orienta você pelas etapas para fazer isso. Se você preferir atualizar manualmente seu código, consulte as seções Retornos de chamada convertidos em promessas e APIs organizadas em recursos para obter mais informações sobre as alterações necessárias da API.

1. Instale a extensão mais recente do Kit de Ferramentas de Agentes do Visual Studio Code

No Marketplace de Extensões do Visual Studio Code, pesquise Microsoft 365 Agents 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 Agents Toolkit mais recente (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 atualiza o package.json arquivo com a dependência do TeamsJS versão 2.x.x (@microsoft/teams-js@2.0.0 ou posterior) e *.js/.ts o e *.jsx/.tsx são atualizados com:

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 Agents Toolkit ou manualmente.

{
    "$schema" : "https://developer.microsoft.com/json-schemas/teams/v1.13/MicrosoftTeams.schema.json",
    "manifestVersion" : "1.13"
}

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

Próximas etapas

• Use a referência da biblioteca TeamsJS para começar a usar a biblioteca TeamsJS.
• Revise o changelog para obter as atualizações mais recentes do TeamsJS.