Bibliothèque de client JavaScript Teams

La bibliothèque de client JavaScript Microsoft Teams (TeamsJS) peut vous aider à créer des expériences hébergées dans Teams, l’application Microsoft 365 et Outlook, où le contenu de votre application est hébergé dans un iFrame. La bibliothèque est utile pour développer des applications avec les fonctionnalités Teams suivantes :

• Onglets
• Boîtes de dialogue (appelées modules de tâche dans TeamsJS v1.x)

À compter de la version 2.0.0, la bibliothèque TeamsJS existante (@microsoft/teams-jsou simplement TeamsJS) est refactorisée pour permettre aux applications Teams de s’exécuter dans Outlook et l’application Microsoft 365, en plus de Microsoft Teams. D’un point de vue fonctionnel, la dernière version de TeamsJS prend en charge toutes les fonctionnalités d’application Teams existantes (v.1.x.x) tout en ajoutant la possibilité facultative d’héberger des applications Teams dans Outlook et l’application Microsoft 365.

Voici les conseils de gestion de version pour différents scénarios d’application :

* Utilisez la dernière version de TeamsJS (v.2.19.0 ou ultérieure) chaque fois que possible, pour tirer parti des dernières améliorations et de la prise en charge des nouvelles fonctionnalités, y compris les applications Teams uniquement. TeamsJS v.1.12 continue d’être pris en charge, mais aucune nouvelle fonctionnalité ou amélioration n’est ajoutée. Les schémas 1.12 et 1.13 sont sinon les mêmes. Pour plus d’informations, consultez Bibliothèque TeamsJS.

Le reste de cet article vous guide tout au long de la structure et des dernières mises à jour de la bibliothèque TeamsJS.

Prise en charge de Microsoft 365 (exécution d’applications Teams dans Microsoft 365 et Outlook)

TeamsJS v.2.0 introduit la possibilité pour certains types d’applications Teams de s’exécuter dans l’écosystème Microsoft 365. Les autres hôtes d’application Microsoft 365 (y compris l’application Microsoft 365 et Outlook) pour les applications Teams prennent en charge un sous-ensemble des types d’applications et des fonctionnalités que vous pouvez créer pour la plateforme Teams. Cette prise en charge s’étend au fil du temps. Pour obtenir un résumé de la prise en charge des hôtes pour les applications Teams, consultez Prise en charge des fonctionnalités TeamsJS dans Microsoft 365.

Améliorer les performances au moment du chargement avec la secousse de l’arborescence JavaScript

À partir de la version 2.31.0 et des versions ultérieures, la bibliothèque TeamsJS est entièrement chassable. L’ébranlement d’arborescence est une optimisation JavaScript qui élimine le code inutilisé. En utilisant la secousse d’arborescence lorsqu’une application est groupée pour le déploiement, vous pouvez réduire la taille du package, ce qui accélère le téléchargement et améliore le temps de chargement.

Comment utiliser la secousse d’arborescence avec TeamsJS

Pour tirer parti du tremblement d’arborescence lorsque vous regroupez votre package d’application, utilisez un bundler qui prend en charge le tremblement d’arborescence, tel que webpack ou Rollup. Lorsque la secousse d’arborescence est activée, tout le code TeamsJS inutilisé est automatiquement supprimé dans l’offre groupée finale. Par exemple, considérez le code suivant :

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
}

Supposons que le module barCode dans TeamsJS contient les quatre fonctions hasPermission(), isSupported(), requestPermission()et scanBarCode(BarCodeConfig). Si une application utilise uniquement la hasPermission() fonction , les trois autres fonctions sont exclues de l’offre groupée d’applications après avoir secoué l’arborescence. Cela garantit que les applications restent aussi légères que possible et incluent uniquement le code dont elles ont besoin.

Nouveautés de TeamsJS version 2.x.x

Il existe deux changements significatifs entre les versions TeamsJS 1.x.x et v.2.0.0 et ultérieures :

• Les fonctions de rappel retournent désormais des objets Promise. La plupart des fonctions avec des paramètres de rappel dans TeamsJS v.1.12 sont modernisées pour retourner un objet Promise JavaScript afin d’améliorer la gestion des opérations asynchrones et la lisibilité du code.

• Les API sont désormais organisées en fonctionnalités. Vous pouvez considérer les fonctionnalités comme des regroupements logiques d’API qui fournissent des fonctionnalités similaires, telles que authentication, dialog, chatet calendar. Chaque espace de noms représente une fonctionnalité distincte.

Compatibilité descendante

Une fois que vous commencez à référencer @microsoft/teams-js@2.0.0 (ou ultérieurement) à partir d’une application Teams existante, vous voyez des avertissements de dépréciation pour tout code appelant des API qui sont modifiées.

Une couche de traduction d’API (mappage de v.1 à v.2 appels d’API TeamsJS) est fournie pour permettre aux applications Teams existantes de continuer à fonctionner dans Teams jusqu’à ce qu’elles soient en mesure de mettre à jour le code de l’application pour utiliser les modèles d’API TeamsJS v.2.

Authentification

Dans TeamsJS la version 2.11.0 ou ultérieure, les applications doivent fournir un troisième paramètre d’URL, hostRedirectUrl, dans l’API d’authentification, pour rediriger les utilisateurs vers le client approprié une fois l’authentification terminée. Le hostRedirectUrl paramètre d’authentification est nécessaire pour permettre à votre client d’être pris en charge dans les applications hôtes Microsoft 365. Les applications implémentées sur des versions antérieures de TeamsJS prennent uniquement en charge Teams après cette mise à jour, car les oauthRedirectmethod paramètres de requête et authId sont transmis au serveur d’applications tiers.

Pour plus d’informations sur le paramètre d’authentification, consultez Utiliser des fournisseurs OAuth externes.

Applications Teams s’exécutant sur Microsoft 365

Voici les conditions requises pour permettre l’exécution d’une application Teams existante dans Outlook et Microsoft 365 :

1. Dépendance vis-à-vis de TeamsJS version 2.x.x ( @microsoft/teams-js@2.0.0) ou ultérieure.

2. Modifiez le code d’application existant en fonction des modifications requises décrites dans cet article.

3. Mettez à jour votre manifeste d’application (précédemment appelé manifeste d’application Teams) vers la version 1.13 ou ultérieure.

Pour plus d’informations, consultez Étendre des applications Teams dans Microsoft 365.

Rappels convertis en promesses

Les API Teams qui prenaient précédemment un paramètre de rappel sont mises à jour pour retourner un objet JavaScript Promise . Il s’agit notamment des API suivantes :

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

Vous devez mettre à jour la façon dont votre code appelle l’une de ces API pour utiliser Promises. Par exemple, si votre code appelle une API Teams comme suit :

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 communication intercloud via le KIT de développement logiciel (SDK) est limitée pour des raisons de sécurité ; Par conséquent, Teams géré par le domaine 21Vianet n’est pas inclus dans validOrigins. Pour permettre à une application de fonctionner dans Teams géré par 21Vianet, spécifiez le domaine Teams géré par 21Vianet lors de l’initialisation du SDK dans le déploiement de votre application, à l’aide du paramètre validMessageOrigins .

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

API organisées en fonctionnalités

Une fonctionnalité est un regroupement logique (via un espace de noms) d’API qui fournissent des fonctionnalités similaires. Vous pouvez considérer Microsoft Teams, Outlook et l’application Microsoft 365 comme des hôtes de votre application d’onglet. Un hôte prend en charge une fonctionnalité donnée s’il prend en charge toutes les API définies dans cette fonctionnalité. Un hôte ne peut pas implémenter partiellement une fonctionnalité. Les fonctionnalités peuvent être basées sur des fonctionnalités ou du contenu, telles que l’authentification ou la boîte de dialogue. Il existe également des fonctionnalités pour les types d’application tels que les pages et d’autres regroupements.

À compter de TeamsJS v.2.0, les API sont définies en tant que fonctions dans un espace de noms JavaScript dont le nom correspond à la fonctionnalité requise. Par exemple, si une application s’exécute dans un hôte qui prend en charge la fonctionnalité de boîte de dialogue , l’application peut appeler en toute sécurité des API telles que dialog.open (en plus d’autres API liées au dialogue définies dans l’espace de noms). Si une application tente d’appeler une API qui n’est pas prise en charge dans cet hôte, l’API génère une exception.

Différencier votre expérience d’application

Vous pouvez vérifier la prise en charge par l’hôte d’une fonctionnalité donnée au moment de l’exécution en appelant la fonctionisSupported() sur cette fonctionnalité (espace de noms). Elle retourne true si elle est prise en charge et false si ce n’est pas le cas, et vous pouvez ajuster le comportement de l’application comme il convient. Cela permet à votre application d’activer l’interface utilisateur et les fonctionnalités des hôtes qui la prennent en charge, tout en continuant à s’exécuter pour les ordinateurs hôtes qui ne le prennent pas en charge.

Le nom d’hôte dans lequel votre application fonctionne s’affiche sous la forme d’une valeur d’énumération HostName de l’interface Context (app.Context.app.host.name). Vous pouvez l’interroger au moment de l’exécution en appelant getContext. Pour le client Teams classique, cette valeur peut être retournée comme inconnue ou non définie. Dans ce cas, mappez ces valeurs à Teams classiques.

La {hostName}valeur de l’espace réservé d’URL est également disponible. Toutefois, nous vous recommandons d’utiliser le mécanisme hostName avec discrétion.

• Ne partez pas du principe que certaines fonctionnalités sont ou ne sont pas disponibles dans un hôte en fonction de la valeur de la propriété hostName . Au lieu de cela, recherchez la prise en charge des fonctionnalités (isSupported).
• N’utilisez pas hostName pour contrôler les appels d’API. Au lieu de cela, recherchez la prise en charge des fonctionnalités (isSupported).
• UtilisezhostName pour différencier le thème de votre application en fonction de l’hôte dans lequel elle s’exécute. Par exemple, vous pouvez utiliser Microsoft Teams violet comme couleur d’accentuation principale lors de l’exécution dans Teams, et Outlook bleu lors de l’exécution dans Outlook.
• UtilisezhostName pour différencier les messages affichés à l’utilisateur en fonction de l’hôte dans lequel il s’exécute. Par exemple, affichez Gérer vos tâches dans Microsoft 365 lors de l’exécution dans Microsoft 365 sur le web et Gérer vos tâches dans Teams lors de l’exécution dans Teams.

Espaces de noms

À compter de TeamsJS v.2.0, les API sont organisées en fonctionnalités par le biais d’espaces de noms. Plusieurs nouveaux espaces de noms d’une importance particulière sont l’application, les pages, la boîte de dialogue et teamsCore.

Espace de noms d’application

L’espace app de noms contient les API de niveau supérieur requises pour l’utilisation globale des applications, dans Teams, l’application Microsoft 365 et Outlook. Toutes les API de différents autres espaces de noms TeamsJS sont déplacées vers l’espace app de noms à partir de TeamsJS v.2.0 :

espace de noms pages

L’espace pages de noms inclut des fonctionnalités permettant d’exécuter et de parcourir des pages web au sein de différents hôtes Microsoft 365, notamment Teams, l’application Microsoft 365 et Outlook. Il inclut également plusieurs sous-éléments, implémentés en tant que sous-espaces.

pages.tabs

pages.config

pages.backStack

pages.appButton

espace de noms de boîte de dialogue

L’espace de noms des tâches TeamsJS est renommé boîte de dialogue, et les API suivantes sont renommées :

En outre, cette fonctionnalité est divisée en deux sous-main, dialog.url pour les dialogues HTML et dialog.adaptiveCard pour les dialogues basés sur carte adaptative, avec d’autres sous-espaces de nom pour les dialogues basés sur un bot.

espace de noms teamsCore

Pour généraliser la bibliothèque TeamsJS afin d’exécuter d’autres hôtes Microsoft 365 tels que l’application Microsoft 365 et Outlook, les fonctionnalités propres à Teams (à l’origine dans l’espace de noms global ) sont déplacées vers un espace de noms teamsCore :

Mises à jour de l’interface contextuel

L’interface Context est déplacée vers l’espace app de noms et mise à jour pour regrouper des propriétés similaires pour une meilleure scalabilité, car elle s’exécute dans Outlook et l’application Microsoft 365, en plus de Teams.

Une nouvelle propriété app.Context.app.host.name est ajoutée pour permettre aux onglets de différencier l’expérience utilisateur en fonction de l’application hôte.

Vous pouvez également visualiser les modifications en examinant la transformLegacyContextToAppContext fonction dans la source TeamsJS version 2.x.x (fichier app.ts ).

Mise à jour vers TeamsJS version 2.0

Le moyen le plus simple de mettre à jour votre application Teams avec TeamsJS version 2.0.x consiste à utiliser l’extension Teams Toolkit pour Visual Studio Code. Cette section vous guide tout au long des étapes à suivre. Si vous préférez mettre à jour manuellement votre code, consultez les sections Rappels convertis en promesses et API organisées en fonctionnalités pour plus d’informations sur les modifications d’API requises.

1. Installer la dernière extension Visual Studio Code du Kit de ressources Teams

Dans la Place de marché Visual Studio Code Extensions, recherchez Teams Toolkit et installez la dernière version.

2. Mettre à jour les références TeamsJS

Pour s’exécuter dans Outlook et l’application Microsoft 365, votre application doit dépendre du package @microsoft/teams-js@2.0.0npm (ou version ultérieure). Pour effectuer ces étapes manuellement et pour plus d’informations sur les modifications apportées à l’API, consultez les sections suivantes sur les rappels convertis en promesses et API organisées en fonctionnalités.

1. Vérifiez que vous disposez de la dernière version de Teams Toolkit (version 2.10.0 ou ultérieure)
2. Ouvrez la palette de commandes : Ctrl+Shift+P
3. Exécutez la commande Teams: Upgrade Teams JS SDK references to support Outlook and Microsoft 365 apps

Une fois terminé, l’utilitaire met à jour votre package.json fichier avec la dépendance TeamsJS version 2.x.x (@microsoft/teams-js@2.0.0 ou ultérieure), et vos *.js/.ts et *.jsx/.tsx sont mis à jour avec :

3. Mettre à jour le manifeste de l’application (facultatif)

Si vous mettez à jour une application Teams pour qu’elle s’exécute dans l’application Microsoft 365 et Outlook, vous devez également mettre à jour le manifeste de l’application vers la version 1.13 ou ultérieure. Vous pouvez le faire facilement avec le Kit de ressources Teams ou manuellement.

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

Si vous avez utilisé Teams Toolkit pour créer votre application personnelle, vous pouvez également l’utiliser pour valider les modifications apportées au fichier manifeste de votre application et identifier les erreurs éventuelles. Ouvrez la palette de commandes Ctrl+Shift+Pet recherchez Teams : Valider le fichier manifeste ou sélectionnez l’option dans le menu Déploiement du Teams Toolkit (recherchez l’icône Teams sur le côté gauche de Visual Studio Code).

Étapes suivantes

• Utilisez la référence de la bibliothèque TeamsJS pour commencer à utiliser la bibliothèque TeamsJS.
• Passez en revue le journal des modifications pour connaître les dernières mises à jour de TeamsJS.