Bibliothèque cliente JavaScript Teams

La bibliothèque cliente 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)

À partir 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 de l’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 instructions de contrôle de version pour différents scénarios d’application :

* Utilisez la dernière version de TeamsJS pour tirer parti des dernières améliorations et de la prise en charge des nouvelles fonctionnalités, y compris les applications Teams uniquement. Aucune nouvelle fonctionnalité ou amélioration ne sera ajoutée à TeamsJS v1.13.0. Les nouvelles soumissions et mises à jour d’applications nécessitent désormais TeamsJS version 2.19.0 ou ultérieure. Pour plus d’informations, voir la bibliothèque TeamsJS.

** Lors de la mise à niveau de votre application d’extension de message ou d’onglet personnel Teams vers la version 1.13 ou ultérieure, elle devient disponible par défaut sur les hôtes Microsoft 365. Pour éviter une charge partielle dans les hôtes non pris en charge et garantir une expérience utilisateur cohérente, définissez les exigences d’exécution dans le manifeste pour contrôler où et comment votre application apparaît. Pour plus d’informations, consultez Spécifier les exigences d’exécution de l’hôte Microsoft 365 dans le manifeste de l’application.

Le reste de cet article vous guide à travers la structure et les dernières mises à jour de la bibliothèque TeamsJS.

Support 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’applications 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 fonctionnalités que vous pouvez créer pour la plateforme Teams. Cette prise en charge s’élargit au fil du temps. Pour obtenir un résumé de la prise en charge de l’hôte pour les applications Teams, consultez Prise en charge de la fonctionnalité TeamsJS dans Microsoft 365.

Améliorer les performances de temps de chargement avec JavaScript tree shaking

À partir de la version 2.31.0 et des versions ultérieures, la bibliothèque TeamsJS est entièrement arborescente. Le tree shaking est une optimisation JavaScript qui élimine le code inutilisé. En utilisant l’arborescence lorsqu’une application est regroupée pour le déploiement, vous pouvez réduire la taille du package, ce qui se traduit par un téléchargement plus rapide et un temps de chargement amélioré.

Comment utiliser le tremblement des arbres avec TeamsJS

Pour tirer parti des tremblements d’arbres lorsque vous groupez votre package d’application, utilisez un bundler qui prend en charge les tremblements d’arbres, tel que webpack ou Rollup. Lorsque le tree shaking est activé, tout le code TeamsJS inutilisé est automatiquement supprimé de l’ensemble final. 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 code-barres dans TeamsJS contienne 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’arbre. Cela garantit que les applications restent aussi légères que possible et n’incluent que 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 renvoient 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 Promesse 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 offrent 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 plus tard) à partir d’une application Teams existante, vous voyez des avertissements de dépréciation pour toutes les API d’appel de code qui sont modifiées.

Une couche de traduction d’API (mappage des versions 1 à 2 des 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 les anciennes versions de TeamsJS prennent uniquement en charge Teams après cette mise à jour, car les paramètres et authId la oauthRedirectmethod requête 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 sur TeamsJS version 2.x.x ( @microsoft/teams-js@2.0.0) ou ultérieure.

2. Modifiez le code d’application existant en fonction des changements requis décrits dans cet article.

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

Pour plus d’informations, voir Étendre les applications Teams à 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 Promesse JavaScript. 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 des promesses. 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 SDK est restreinte pour des raisons de sécurité ; par conséquent, les équipes gérées par le domaine 21Vianet ne sont pas incluses dans .validOrigins Pour activer le fonctionnement d’une application dans les équipes gérées par 21Vianet, spécifiez les équipes gérées par le domaine 21Vianet lors de l’initialisation du kit de développement logiciel (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 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). Il retourne true s’il est pris en charge et false si ce n’est pas le cas, et vous pouvez ajuster le comportement de l’application le cas échéant. 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 est affiché sous la forme d’une valeur d’énumération HostName de l’interface Context (app.Context.app.host.name). Vous pouvez effectuer une requête au moment de l’exécution en invoquant getContext. Pour le client Teams classique, cette valeur peut être renvoyée comme inconnue ou indéfinie. Dans ce cas, mappez ces valeurs à Teams classique.

La {hostName}valeur d’espace réservé à l’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 lorsque vous exécutez Microsoft 365 sur le web et Gérer vos tâches dans Teams lorsque vous exécutez 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 de l’application dans Teams, l’application Microsoft 365 et Outlook. Toutes les API de divers 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 dans 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é en dialog, et les API suivantes sont renommées :

De plus, cette fonctionnalité est divisée en deux sous-fonctionnalités principales, dialog.url pour les boîtes de dialogue basées sur HTML et dialog.adaptiveCard pour les boîtes de dialogue basées sur une carte adaptative, avec d’autres sous-espaces de noms pour les boîtes de dialogue basées sur des bots.

espace de noms teamsCore

Pour généraliser la bibliothèque TeamsJS à d’autres hôtes Microsoft 365 tels que l’application Microsoft 365 et Outlook, les fonctionnalités spécifiques à 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 de app noms et mise à jour pour regrouper des propriétés similaires pour une meilleure évolutivité lorsqu’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 fonction dans la transformLegacyContextToAppContextsource 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 Agents Toolkit pour Visual Studio Code. Cette section vous guide tout au long des étapes pour ce faire. Si vous préférez mettre à jour manuellement votre code, consultez les rappels convertis en promesses et API organisés en sections fonctionnalités pour plus d’informations sur les modifications d’API requises.

1. Installer la dernière extension Agents Toolkit Visual Studio Code

Dans la Place de marché des extensions de Visual Studio Code, recherchez Microsoft 365 Agents 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 d’Agents 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 l’opération terminée, 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 l’exécuter 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 Agents Toolkit, ou manuellement.

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

Si vous avez utilisé Agents Toolkit pour créer votre application personnelle, vous pouvez également l’utiliser pour valider les modifications apportées à votre fichier manifeste d’application et identifier les erreurs éventuelles. Ouvrez la palette Ctrl+Shift+P de commandes et recherchez Teams : Validez le fichier manifeste ou sélectionnez l’option dans le menu Déploiement de la boîte à outils des agents (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.
• Consultez le journal des modifications pour connaître les dernières mises à jour de TeamsJS.