Biblioteca cliente de JavaScript de Teams

La biblioteca cliente JavaScript de Microsoft Teams (TeamsJS) puede ayudarle a crear experiencias hospedadas en Teams, la aplicación de Microsoft 365 y Outlook, donde el contenido de la aplicación se hospeda en un iFrame. La biblioteca es útil para desarrollar aplicaciones con las siguientes funcionalidades de Teams:

• Pestañas
• Cuadros de diálogo (denominados módulos de tareas en TeamsJS v1.x)

A partir de la versión 2.0.0, la biblioteca teamsJS existente (@microsoft/teams-jso simplemente TeamsJS) se refactoriza para permitir que las aplicaciones de Teams se ejecuten en Outlook y aplicaciones de Microsoft 365, además de Microsoft Teams. Desde una perspectiva funcional, la versión más reciente de TeamsJS admite todas las funciones de aplicaciones de Teams existentes (v.1.x.x) al tiempo que agrega la capacidad opcional de hospedar aplicaciones de Teams en Outlook y aplicaciones de Microsoft 365.

Esta es la guía de control de versiones para varios escenarios de aplicación:

* Use la versión más reciente de TeamsJS (v.2.19.0 o posterior) siempre que sea posible, para aprovechar las mejoras más recientes y la compatibilidad con nuevas características, incluidas las aplicaciones solo de Teams. TeamsJS v.1.12 sigue siendo compatible, pero no se agregan nuevas características ni mejoras. De lo contrario, los esquemas 1.12 y 1.13 son los mismos. Para obtener más información, consulte Biblioteca teamsJS.

El resto de este artículo le guiará por la estructura y las actualizaciones más recientes de la biblioteca TeamsJS.

Compatibilidad con Microsoft 365 (ejecución de aplicaciones de Teams en Microsoft 365 y Outlook)

TeamsJS v.2.0 presenta la capacidad de que determinados tipos de aplicaciones de Teams se ejecuten en el ecosistema de Microsoft 365. Los demás hosts de aplicaciones de Microsoft 365 (incluida la aplicación de Microsoft 365 y Outlook) para las aplicaciones de Teams admiten un subconjunto de los tipos de aplicación y las funcionalidades que puede crear para la plataforma teams. Esta compatibilidad se expande con el tiempo. Para obtener un resumen de la compatibilidad del host con las aplicaciones de Teams, consulte Compatibilidad con la funcionalidad de TeamsJS en Microsoft 365.

Novedades de TeamsJS versión 2.x.x

Hay dos cambios significativos entre las versiones de TeamsJS 1.x.x y v.2.0.0 y posteriores:

• Las funciones de devolución de llamada ahora devuelven objetos Promise. La mayoría de las funciones con parámetros de devolución de llamada en TeamsJS v.1.12 se modernizan para devolver un objeto Promise de JavaScript para mejorar el control de las operaciones asincrónicas y la legibilidad del código.

• Las API ahora están organizadas en funcionalidades. Puede considerar las funcionalidades como agrupaciones lógicas de API que proporcionan funciones similares, como authentication, dialog, chaty calendar. Cada espacio de nombres representa una funcionalidad independiente.

Compatibilidad con versiones anteriores

Una vez que empiece a hacer referencia @microsoft/teams-js@2.0.0 (o posterior) desde una aplicación de Teams existente, verá advertencias de desuso para cualquier API de llamada de código que se cambie.

Se proporciona una capa de traducción de API (asignación de v.1 a llamadas API de TeamsJS v.2) para permitir que las aplicaciones de Teams existentes sigan funcionando en Teams hasta que puedan actualizar el código de la aplicación para usar los patrones de API de TeamsJS v.2.

Autenticación

En TeamsJS la versión 2.11.0 o posterior, las aplicaciones deben proporcionar un tercer parámetro url, hostRedirectUrl, en la API de autenticación, para redirigir a los usuarios al cliente correcto después de la finalización de la autenticación. El hostRedirectUrl parámetro de autenticación es necesario para permitir que el cliente se admita en las aplicaciones host de Microsoft 365. Las aplicaciones implementadas en versiones anteriores solo admiten Teams después de TeamsJS esta actualización, ya que los oauthRedirectmethod parámetros de consulta y authId se pasan al servidor de aplicaciones de terceros.

Para obtener más información sobre el parámetro de autenticación, consulte Uso de proveedores de OAuth externos.

Aplicaciones de Teams que se ejecutan en Microsoft 365

Estos son los requisitos para permitir que una aplicación de Teams existente se ejecute en Outlook y Microsoft 365:

1. Dependencia de TeamsJS versión 2.x.x ( @microsoft/teams-js@2.0.0) o posterior.

2. Modifique el código de aplicación existente según los cambios necesarios descritos en este artículo.

3. Actualice el manifiesto de la aplicación (anteriormente denominado manifiesto de aplicación de Teams) a la versión 1.13 o posterior.

Para obtener más información, consulte Extensión de aplicaciones de Teams en Microsoft 365.

Callbacks convertidas a promises

Las API de Teams que anteriormente tomaron un parámetro de devolución de llamada se actualizan para devolver un objeto Promise de JavaScript. Entre ellas se incluyen las siguientes 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.navigateToTab, pages.tabs.getMruTabInstances, pages.tabs.getTabInstances, pages.getConfig, pages.config.setConfig, pages.backStack.navigateBack, people.selectPeople, teams.fullTrust.getConfigSetting, teams.fullTrust.joinedTeams.getUserJoinedTeams

Debe actualizar la forma en que el código llama a cualquiera de estas API para usar Promises. Por ejemplo, si el código llama a una API de 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();
            /*...*/
          }

La comunicación entre nubes a través del SDK está restringida por motivos de seguridad; Por lo tanto, Teams operado por el dominio 21Vianet no está incluido en validOrigins. Para permitir que una aplicación funcione en Teams operado por 21Vianet, especifique el dominio Teams operado por 21Vianet durante la inicialización del SDK en la implementación de la aplicación, mediante el parámetro validMessageOrigins .

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

API organizadas en funcionalidades

Una funcionalidad es una agrupación lógica de API (mediante el espacio de nombres) que proporciona una funcionalidad similar. Puede pensar en la aplicación Microsoft Teams, Outlook y Microsoft 365 como hosts de la aplicación de pestaña. Un host admite una funcionalidad determinada si admite todas las API definidas dentro de esa funcionalidad. Un host no puede implementar parcialmente una funcionalidad. Las funcionalidades pueden basarse en características o contenido, como diálogo o autenticación. También hay funcionalidades para los tipos de aplicación, como pestañas y otras agrupaciones.

A partir de TeamsJS v.2.0, las API se definen como funciones en un espacio de nombres de JavaScript cuyo nombre coincide con su funcionalidad necesaria. Si una aplicación se ejecuta en un host que admite la funcionalidad de diálogo, la aplicación puede llamar de forma segura a las API como dialog.open (además de otras API relacionadas con cuadros diálogo definidas en el espacio de nombres). Si una aplicación intenta llamar a una API que no se admite en ese host, la API genera una excepción.

Diferenciar la experiencia de la aplicación

Puede comprobar la compatibilidad del host de una funcionalidad determinada en tiempo de ejecución llamando a la función isSupported() en esa funcionalidad (espacio de nombres). Devuelve true si se admite y false , si no, y puede ajustar el comportamiento de la aplicación según corresponda. Esto permite a la aplicación iluminar la interfaz de usuario y la funcionalidad en los hosts que la admiten, mientras continúa ejecutándose en los hosts que no la admiten.

El nombre de host donde funciona la aplicación se muestra como un valor de enumeración HostName de la Context interfaz (app.Context.app.host.name). Puede consultarlo en tiempo de ejecución invocando getContext. Para el cliente de Teams clásico, este valor podría devolverse como desconocido o indefinido. En este caso, asigne estos valores a Teams clásicos.

El valor del {hostName}marcador de posición de dirección URL también está disponible. Sin embargo, se recomienda usar el mecanismo hostName con discreción.

• No asuma que cierta funcionalidad está o no está disponible en un host basándose en el valor de propiedad hostName. En su lugar, compruebe la compatibilidad con la funcionalidad (isSupported).
• No use hostName para realizar llamadas a la API. En su lugar, compruebe la compatibilidad con la funcionalidad (isSupported).
• Use el hostName para diferenciar el tema de la aplicación en función del host en el que se ejecuta. Por ejemplo, puede usar el color púrpura de Microsoft Teams como color de énfasis principal cuando se ejecuta en Teams y el azul de Outlook cuando se ejecuta en Outlook.
• UsehostName para diferenciar los mensajes que se muestran al usuario en función del host en el que se ejecuta. Por ejemplo, muestra Administrar las tareas en Microsoft 365 cuando se ejecuta en Microsoft 365 en la web y Administrar las tareas en Teams cuando se ejecuta en Teams.

Espacios de nombres

A partir de TeamsJS v.2.0, las API se organizan en funcionalidades por medio de los espacios de nombres. Varios espacios de nombres nuevos de importancia particular son app, pages, dialogy teamsCore.

espacio de nombres app

El app espacio de nombres contiene las API de nivel superior necesarias para el uso general de la aplicación en Teams, la aplicación de Microsoft 365 y Outlook. Todas las API de varios otros espacios de nombres TeamsJS se mueven al espacio de nombres a app partir de TeamsJS v.2.0:

espacio de nombres pages

El pages espacio de nombres incluye funcionalidad para ejecutar y navegar por páginas web dentro de varios hosts de Microsoft 365, incluidos Teams, la aplicación de Microsoft 365 y Outlook. También incluye varias subfuncionalidades, implementadas como sub-espacios de nombres.

pages.tabs

pages.config

pages.backStack

pages.appButton

espacio de nombres dialog

Se cambia el nombre del espacio de nombres de tareas de TeamsJS a dialog y se cambia el nombre de las siguientes API:

Además, esta funcionalidad se divide en dos sub funcionalidades principales, dialog.url para diálogos basados en HTML y dialog.adaptiveCard para diálogos basados en tarjeta adaptable, con subnombres adicionales para diálogos basados en bots.

espacio de nombres teamsCore

Para generalizar la biblioteca TeamsJS para ejecutar otros hosts de Microsoft 365, como la aplicación Microsoft 365 y Outlook, la funcionalidad específica de Teams (originalmente en el espacio de nombres global ) se mueve a un espacio de nombres teamsCore :

Actualizaciones de la interfaz Context

La Context interfaz se mueve al app espacio de nombres y se actualiza para agrupar propiedades similares para mejorar la escalabilidad a medida que se ejecuta en outlook y aplicación de Microsoft 365, además de Teams.

Se agrega una nueva propiedad app.Context.app.host.name para habilitar pestañas para diferenciar la experiencia del usuario en función de la aplicación host.

También puede visualizar los cambios revisando la transformLegacyContextToAppContext función en el origen teamsJS versión 2.x.x (archivo app.ts ).

Actualización a la versión 2.0 de TeamsJS

La manera más fácil de actualizar la aplicación de Teams con TeamsJS versión 2.0.x es usar la extensión Teams Toolkit para Visual Studio Code. Esta sección le guiará por los pasos para hacerlo. Si prefiere actualizar manualmente el código, consulte las secciones Devoluciones de llamada convertidas en promesas y API organizadas en funcionalidades para obtener más información sobre los cambios de API necesarios.

1. Instalar la extensión Kit de herramientas de Teams de Visual Studio Code más reciente

En marketplace de extensiones de Visual Studio Code, busque Teams Toolkit e instale la versión más reciente.

2. Actualizar referencias de TeamsJS

Para ejecutarse en outlook y la aplicación de Microsoft 365, la aplicación debe depender del paquete@microsoft/teams-js@2.0.0 npm (o posterior). Para realizar estos pasos manualmente y obtener más información sobre los cambios en la API, vea las secciones siguientes sobre Callbacks convertidas en promises y API organizados en funcionalidades.

1. Asegúrese de que tiene el kit de herramientas de Teams más reciente (versión 2.10.0 o posterior)
2. Abra la Paleta de comandos: Ctrl+Shift+P
3. Ejecute el comando Teams: Upgrade Teams JS SDK references to support Outlook and Microsoft 365 apps

Después de la finalización, la utilidad actualiza package.json el archivo con la dependencia TeamsJS versión 2.x.x (@microsoft/teams-js@2.0.0 o posterior) y *.js/.ts*.jsx/.tsx se actualiza con:

3. Actualizar el manifiesto de aplicación (opcional)

Si va a actualizar una aplicación de Teams para que se ejecute en la aplicación de Microsoft 365 y Outlook, también debe actualizar el manifiesto de la aplicación a la versión 1.13 o posterior. Puede hacerlo fácilmente con el Kit de herramientas de Teams o manualmente.

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

Si usó Teams Toolkit para crear la aplicación personal, también puede usarla para validar los cambios en el archivo de manifiesto de la aplicación e identificar los errores. Abra la paleta de comandos Ctrl+Shift+P y busque Teams: validar el archivo de manifiesto o seleccione la opción en el menú Implementación del Kit de herramientas de Teams (busque el icono de Teams en el lado izquierdo de Visual Studio Code).

Pasos siguientes

• Use la referencia de la biblioteca TeamsJS para empezar a trabajar con la biblioteca TeamsJS.
• Revise el registro de cambios para ver las actualizaciones más recientes de TeamsJS.