Cartes adaptatives dans Teams : comment utiliser le concepteur, avec des exemples
Par Mirko Peters ·
Comment concevoir une carte adaptative pour Microsoft Teams avec le concepteur de cartes adaptatives, quelle version de schéma et quelles actions Teams prend en charge, les règles de mise en page pour mobile, et un exemple JSON minimal.
Traduit automatiquement par IA à partir de l'article original. Lire l'original en anglais
Une carte adaptative dans Teams est une description JSON d’une petite partie d’interface que Teams affiche sous forme de carte de message. Le moyen le plus rapide d’en créer une est le concepteur de cartes adaptatives dans le navigateur : ajoutez des éléments, copiez le JSON et envoyez-le depuis votre bot ou votre application. Ce guide présente le fonctionnement du concepteur, ce que Teams prend en charge, les règles de mise en page qui évitent les cartes tronquées, et un exemple minimal.
Points clés
- Le concepteur de cartes adaptatives en ligne se trouve à l’adresse adaptivecards.microsoft.com/designer.html. Ajoutez visuellement les éléments, copiez la charge utile JSON et utilisez-la dans votre application.
- Les bots et extensions de messages Teams prennent en charge la version 1.6 du schéma des cartes adaptatives ou une version antérieure, et l’application mobile Teams prend en charge jusqu’à la version 1.6.
- Les webhooks entrants prennent en charge tous les éléments natifs des cartes, à l’exception d’Action.Submit. Les actions prises en charge sont notamment Action.OpenURL, Action.ShowCard, Action.ToggleVisibility et Action.Execute.
- Concevez d’abord pour les écrans étroits, définissez wrap à true sur le texte et les ensembles de choix, et utilisez une à trois actions principales, avec un maximum de six.
- Les cartes dans Teams ne prennent pas en charge l’envoi de fichiers ou d’images, et la propriété isEnabled d’Action.Submit n’est pas prise en charge.
Note sur les sources : les pages Microsoft Learn consultées pour cet article ne décrivent ni le sélecteur d’application hôte du concepteur, ni son éditeur de données d’exemple pour Teams. Les étapes ci-dessous s’en tiennent donc à ce que ces pages indiquent.
Ouvrir le concepteur
La documentation des cartes adaptatives renvoie vers le concepteur en ligne accessible à l’adresse adaptivecards.microsoft.com/designer.html. Il peut aussi être intégré à votre propre application web avec le package npm adaptivecards-designer. Le guide du SDK Teams de Microsoft décrit un processus en trois étapes :
- Ajoutez visuellement les éléments jusqu’à ce que la carte vous convienne.
- Copiez la charge utile JSON depuis le volet de l’éditeur.
- Collez le JSON dans votre projet, ou convertissez-le en appels au générateur.
Si vous préférez un éditeur, la page des outils pour cartes adaptatives répertorie une extension Visual Studio Code appelée Adaptive Card Viewer, qui affiche un aperçu de la carte pendant que vous modifiez un fichier .json doté d’une propriété $schema. Elle mentionne également AdaptiveCards Studio, qui permet de modifier les modèles de cartes et les données d’exemple dans VS Code.
Ce que prend en charge Teams
La référence des cartes Teams indique les limites suivantes :
| Domaine | Prise en charge documentée | |---|---| | Version du schéma | Version 1.6 ou antérieure pour les cartes de bot, les extensions de message, l’aperçu de liens et les boîtes de dialogue | | Teams mobile | Jusqu’à la version 1.6 ; les versions ultérieures peuvent s’afficher de manière incohérente | | Webhooks entrants | Tous les éléments natifs, sauf Action.Submit | | Action.Submit | La propriété isEnabled n’est pas prise en charge | | Styles d’action | Les styles positif ou destructif ne sont pas pris en charge | | Envois | Le transfert de fichiers ou d’images n’est pas pris en charge | | Surfaces | Les bots, les extensions de message et Bot Framework sont marqués comme pris en charge. Les onglets et les connecteurs sont marqués comme non pris en charge. Les webhooks entrants ne prennent en charge les Adaptive Cards que pour le type de connecteur Microsoft 365 groups. |
Le guide du SDK précise que ses packages de cartes intègrent le schéma Adaptive Card v1.5 sous forme de types stricts. Cela reste dans la limite de la version 1.6.
Un exemple minimal
Voici la structure qu’un bot envoie en pièce jointe. Elle est adaptée du format présenté sur la page de référence des cartes Teams. La carte se place dans content, et contentType vaut application/vnd.microsoft.card.adaptive.
``json { "contentType": "application/vnd.microsoft.card.adaptive", "content": { "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.0", "body": [ { "type": "TextBlock", "text": "Publish Adaptive Card schema", "weight": "bolder", "size": "medium", "wrap": true } ], "actions": [ { "type": "Action.Submit", "title": "OK" } ] } } ``
La propriété wrap est un ajout fondé sur les recommandations de conception ci-dessous. La page montre aussi des valeurs dynamiques avec des modèles, par exemple un bloc de texte dont text vaut ${titleText}.
Envoi de la carte
La page de référence des cartes ne contient pas de procédure complète d’envoi. Elle renvoie vers les exemples Bot Framework pour .NET et Node.js. Le guide du SDK Teams présente un modèle de création (builder) avec des packages pour C# (Microsoft.Teams.Cards), Python (microsoft-teams-cards) et TypeScript (@microsoft/teams.cards). Un court exemple Python du guide crée une carte avec un bloc de texte et l’envoie avec MessageActivityInput(text="Hello text!").add_card(card). Ces builders valident chaque propriété par rapport au schéma, ce qui détecte les erreurs dès la compilation.
Règles de mise en page pour Teams
Les recommandations de conception de Microsoft comprennent les règles suivantes :
- Commencer par l’étroit. Concevez d’abord pour les écrans étroits. Les cartes s’adaptent bien à un agrandissement, mais pas à une réduction.
- Retour à la ligne. Définissez
"wrap": truesurTextBlock,ColumnSetetInput.ChoiceSet. - Colonnes. Utilisez moins de colonnes pour un meilleur affichage sur mobile. Les recommandations ne donnent pas de limite numérique de colonnes.
- Valeurs de largeur des colonnes.
autoajuste la largeur au contenu et convient aux colonnes contenant des boutons qui doivent rester entièrement visibles,stretchrépartit également la largeur disponible, un nombre simple représente une proportion, et<number>pxdésigne une largeur fixe qui ne devrait pas dépasser la largeur de l’appareil. Ne définissez pasautosur toutes les colonnes. - Images. Utilisez des arrière-plans transparents pour que les images s’adaptent à tous les thèmes de Teams. Une image de 100 × 100 pixels affichée à 50 × 50 reste nette, mais l’inverse provoque une pixellisation. Utilisez
widthetheightpour contrôler la taille exacte. - Cartes pleine largeur. Testez-les dans des mises en page étroites, comme sur mobile ou dans les volets latéraux des réunions, pour éviter que le contenu soit tronqué.
- Actions. Utilisez une à trois actions principales, avec un maximum de six.
- Conteneurs. Utilisez
stylepour mettre en valeur,selectActionpour associer une action etAction.ToggleVisibilitypour les groupes repliables. N’utilisez pas les conteneurs à d’autres fins.
Microsoft classe aussi les types de cartes selon leur usage, par exemple Hero pour les articles, Thumbnail pour un message simple avec action, List pour choisir parmi des éléments, et ChoiceSet pour recueillir plusieurs saisies. La page de conception précise que ses recommandations proviennent d’un guide Teams historique et renvoie vers le hub de documentation des Adaptive Cards comme source actuelle des bonnes pratiques de conception.
Erreurs courantes
- Concevoir une carte large, puis constater sur mobile que le texte est coupé.
- Utiliser une version de schéma supérieure à 1.6.
- Utiliser Action.Submit dans une carte de webhook entrant.
- Ajouter trop de boutons.
- Utiliser des largeurs fixes en pixels sur plusieurs colonnes.
Matériel de démarrage
La page de conception renvoie vers un dépôt de modèles de démarrage, Microsoft-Teams-Adaptive-Card-Samples sur GitHub, ainsi que vers un Teams UI Kit dans Figma qui couvre le thème, l’accessibilité et le dimensionnement adaptatif.
Articles connexes
Sources
- Microsoft Learn : outils Adaptive Cards
- Microsoft Learn : créer et explorer les types de cartes dans Teams
- Microsoft Learn : concevoir des cartes Adaptive Cards pour votre application
- Microsoft Learn : créer des cartes Adaptive Cards (Teams SDK)
FAQ
Où se trouve le concepteur de cartes adaptatives ?
Microsoft Learn renvoie vers le concepteur en ligne accessible à l’adresse adaptivecards.microsoft.com/designer.html. La documentation du SDK Teams décrit la démarche : ajoutez visuellement les éléments jusqu’à ce que la carte vous convienne, copiez la charge utile JSON depuis le volet de l’éditeur, puis collez-la dans votre projet ou convertissez-la en appels au générateur.
Quelle version de carte adaptative Teams prend-il en charge ?
Selon la documentation de la plateforme Teams sur Microsoft Learn, les cartes envoyées par les bots, les extensions de messages basées sur une action, les extensions de messages basées sur une recherche, l’aperçu de liens (unfurling) et les boîtes de dialogue prennent en charge la version 1.6 du schéma ou une version antérieure. L’application mobile Teams prend en charge jusqu’à la version 1.6, et les versions ultérieures risquent de ne pas s’afficher correctement sur mobile.
Pourquoi le texte de ma carte est-il tronqué sur mobile ?
Microsoft Learn indique de définir wrap à true sur TextBlock, ColumnSet et Input.ChoiceSet. Sans cela, le texte est tronqué sur mobile. La documentation recommande également de concevoir d’abord pour les écrans étroits et d’utiliser moins de colonnes, qui s’affichent mieux sur mobile.
Puis-je utiliser Action.Submit dans une carte de webhook entrant ?
Non. La référence des cartes sur Microsoft Learn précise que les webhooks entrants prennent en charge tous les éléments natifs des cartes adaptatives, à l’exception d’Action.Submit. Utilisez plutôt Action.OpenURL, Action.ShowCard, Action.ToggleVisibility ou Action.Execute.
Combien de boutons une carte doit-elle comporter ?
Microsoft Learn recommande une à trois actions principales et autorise un maximum de six, en rappelant que moins c’est mieux. Il précise également que les cartes doivent rester concises, car elles perdent de leur utilité dès qu’elles sortent du champ de vision, en particulier dans les canaux.