M365Con 2027 – gratis online conferentie · 11–22 Jan 2027 · 120 sessions m365con.net

Blog · Mirko Peters

Adaptive Cards in Teams: zo gebruik je de Designer, met voorbeelden

By ·

Hoe je een Adaptive Card voor Microsoft Teams ontwerpt met de Adaptive Card Designer, welke schemaversie en acties Teams ondersteunt, layoutregels voor mobiel en een minimaal JSON-voorbeeld.

Automatically translated with AI from the original post. Read the English original

Een Adaptive Card in Teams is een JSON-beschrijving van een klein stuk interface dat Teams weergeeft als berichtkaart. De snelste manier om er een te bouwen is de Adaptive Card Designer in de browser: voeg elementen toe, kopieer de JSON en verstuur die vanuit je bot of app. Deze gids behandelt de werkwijze in de designer, wat Teams ondersteunt, layoutregels om afgekapte kaarten te voorkomen en een minimaal voorbeeld.

Belangrijkste punten

  • De browsergebaseerde Adaptive Card Designer vind je op adaptivecards.microsoft.com/designer.html. Voeg elementen visueel toe, kopieer de JSON-payload en gebruik die in je app.
  • Teams-bots en berichtextensies ondersteunen Adaptive Card-schemaversie 1.6 of eerder, en de Teams-mobiele app ondersteunt tot en met 1.6.
  • Inkomende webhooks ondersteunen alle native kaartelementen behalve Action.Submit. Ondersteunde acties zijn daar onder meer Action.OpenURL, Action.ShowCard, Action.ToggleVisibility en Action.Execute.
  • Ontwerp eerst voor smalle schermen, stel wrap in op true bij tekst en keuzesets, en gebruik één tot drie primaire acties, met een maximum van zes.
  • Kaarten in Teams ondersteunen geen bestands- of afbeeldingsuploads, en de eigenschap isEnabled van Action.Submit wordt niet ondersteund.

Een opmerking over de bronnen: de Microsoft Learn-pagina's waarop dit artikel is gebaseerd, beschrijven de hostapp-selector van de designer of de editor voor voorbeeldgegevens voor Teams niet. De onderstaande stappen blijven bij wat die pagina's wel vermelden.

De designer openen

De Adaptive Cards-documentatie verwijst naar een browsergebaseerde designer op adaptivecards.microsoft.com/designer.html. Je kunt hem ook insluiten in je eigen webapp met het npm-pakket adaptivecards-designer. De handleiding van de Teams SDK van Microsoft beschrijft een werkwijze in drie stappen:

  1. Voeg elementen visueel toe tot de kaart goed eruitziet.
  2. Kopieer de JSON-payload uit het editorvenster.
  3. Plak de JSON in je project, of converteer hem naar builder-aanroepen.

Als je liever een editor gebruikt, staat op de pagina met Adaptive Cards-tools een Visual Studio Code-extensie genaamd Adaptive Card Viewer. Die toont een voorbeeld van de kaart terwijl je een .json-bestand met een $schema-eigenschap bewerkt. Daarnaast wordt AdaptiveCards Studio genoemd, waarmee je kaartsjablonen en voorbeeldgegevens in VS Code kunt bewerken.

Wat Teams ondersteunt

De referentie voor Teams-kaarten noemt de volgende beperkingen:

| Gebied | Gedocumenteerde ondersteuning | |---|---| | Schemaversie | Versie 1.6 of eerder voor botkaarten, berichtextensies, link-previews en dialogen | | Teams mobiel | Tot en met versie 1.6; latere versies kunnen onregelmatig worden weergegeven | | Inkomende webhooks | Alle native elementen behalve Action.Submit | | Action.Submit | De eigenschap isEnabled wordt niet ondersteund | | Actiestijlen | Positieve of destructieve opmaak wordt niet ondersteund | | Uploads | Het uploaden van bestanden of afbeeldingen wordt niet ondersteund | | Oppervlakken | Bots, berichtextensies en Bot Framework staan als ondersteund aangegeven. Tabbladen en connectors staan als niet ondersteund aangegeven. Inkomende webhooks ondersteunen Adaptive Cards alleen voor het connectortype Microsoft 365-groepen. |

De SDK-documentatie voegt toe dat de kaartpakketten het Adaptive Card v1.5-schema bundelen als strikte types. Dat valt binnen de limiet van versie 1.6.

Een minimaal voorbeeld

Dit is de structuur die een bot als bijlage verstuurt. Ze is aangepast op basis van het formaat op de referentiepagina voor Teams-kaarten. De kaart staat in content, en contentType is 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" } ] } } ``

De eigenschap wrap is een toevoeging op basis van de ontwerprichtlijnen hieronder. De pagina toont ook dynamische waarden met templating, bijvoorbeeld een tekstblok waarvan text gelijk is aan ${titleText}.

De kaart verzenden

De kaartreferentie bevat geen volledige uitleg over het verzenden. Er wordt verwezen naar Bot Framework-voorbeelden voor .NET en Node.js. De Teams SDK-gids laat een builderpatroon zien met pakketten voor C# (Microsoft.Teams.Cards), Python (microsoft-teams-cards) en TypeScript (@microsoft/teams.cards). Een kort Python-voorbeeld uit de gids bouwt een kaart met een tekstblok en verstuurt die met MessageActivityInput(text="Hello text!").add_card(card). Builders valideren elke eigenschap tegen het schema, waardoor fouten al bij het bouwen worden opgemerkt.

Opmaakregels voor Teams

De ontwerprichtlijnen van Microsoft bevatten deze regels:

  • Eerst smal. Ontwerp eerst voor smalle schermen. Kaarten schalen goed omhoog, maar niet goed omlaag.
  • Tekst laten afbreken. Zet "wrap": true op TextBlock, ColumnSet en Input.ChoiceSet.
  • Kolommen. Gebruik minder kolommen voor een betere weergave op mobiel. De richtlijnen geven geen numeriek maximum voor het aantal kolommen.
  • Waarden voor kolombreedte. auto past de breedte aan de inhoud aan en is geschikt voor kolommen met knoppen die volledig zichtbaar moeten blijven, stretch verdeelt de beschikbare breedte gelijkmatig, een los getal is een verhouding, en <number>px is een vaste breedte die de breedte van het apparaat niet mag overschrijden. Stel auto niet in op elke kolom.
  • Afbeeldingen. Gebruik transparante achtergronden, zodat afbeeldingen zich aanpassen aan elk Teams-thema. Een afbeelding van 100 bij 100 pixels die op 50 bij 50 wordt getoond, blijft scherp, maar andersom pixelt het. Gebruik width en height om de exacte grootte te bepalen.
  • Kaarten op volle breedte. Test ze in smalle weergaven, zoals mobiel en zijpanelen bij vergaderingen, zodat inhoud niet wordt afgekapt.
  • Acties. Gebruik één tot drie primaire acties, met een maximum van zes.
  • Containers. Gebruik style voor nadruk, selectAction om een actie te koppelen, en Action.ToggleVisibility voor samenvouwbare groepen. Gebruik containers niet voor andere doeleinden.

Microsoft somt ook kaarttypen op naar gebruik, zoals Hero voor artikelen, Thumbnail voor een eenvoudig bericht met één actie, List om uit items te kiezen, en ChoiceSet om meerdere invoerwaarden te verzamelen. De ontwerppagina vermeldt dat de richtlijnen afkomstig zijn uit een verouderde Teams-gids en verwijst naar het Adaptive Cards-documentatiecentrum als actuele bron voor ontwerpbest practices.

Veelgemaakte fouten

  1. Een brede kaart ontwerpen en op mobiel ontdekken dat tekst wordt afgesneden.
  2. Een schemaversie hoger dan 1.6 gebruiken.
  3. Action.Submit gebruiken in een card voor een inkomende webhook.
  4. Te veel knoppen toevoegen.
  5. Vaste pixelbreedtes gebruiken voor meerdere kolommen.

Startmateriaal

De designpagina verwijst naar een repository met startsjablonen, Microsoft-Teams-Adaptive-Card-Samples op GitHub, en naar een Teams UI Kit in Figma. Die behandelt theming, toegankelijkheid en responsieve afmetingen.

Gerelateerd

Bronnen

Volg de podcastApple PodcastsSpotify

Veelgestelde vragen

Waar vind ik de Adaptive Card Designer?

Microsoft Learn verwijst naar de browsergebaseerde designer op adaptivecards.microsoft.com/designer.html. De documentatie van de Teams SDK beschrijft de werkwijze: voeg elementen visueel toe tot de kaart goed eruitziet, kopieer de JSON-payload uit het editorvenster en plak die in je project, of converteer hem naar builder-aanroepen.

Welke versie van Adaptive Card ondersteunt Teams?

Volgens de Teams-platformdocumentatie op Microsoft Learn ondersteunen kaarten die door bots worden verstuurd, op acties gebaseerde berichtextensies, op zoeken gebaseerde berichtextensies, link unfurling en dialogen schemaversie 1.6 of eerder. De Teams-mobiele app ondersteunt tot en met 1.6; latere versies worden daar mogelijk niet correct weergegeven.

Waarom wordt mijn kaarttekst op mobiel afgekapt?

Microsoft Learn adviseert om wrap in te stellen op true bij TextBlock, ColumnSet en Input.ChoiceSet. Zonder die instelling wordt tekst op mobiel afgekapt. Ook raadt de documentatie aan om eerst voor smalle schermen te ontwerpen en minder kolommen te gebruiken, want die worden op mobiel beter weergegeven.

Kan ik Action.Submit gebruiken in een kaart van een inkomende webhook?

Nee. De referentie voor Microsoft Learn-kaarten vermeldt dat inkomende webhooks alle native Adaptive Card-elementen ondersteunen, behalve Action.Submit. Gebruik in plaats daarvan Action.OpenURL, Action.ShowCard, Action.ToggleVisibility of Action.Execute.

Hoeveel knoppen moet een kaart hebben?

Microsoft Learn adviseert één tot drie primaire acties en staat maximaal zes toe, met de kanttekening dat minder meer is. Verder staat er dat kaarten beknopt moeten blijven, omdat ze minder nuttig worden zodra ze uit beeld scrollen, vooral in kanalen.

Entities in this article

Onderwerpen van dit artikel:

Adaptive Cards – Product Adaptive Cards Designer – Onderdeel van Adaptive Cards Microsoft Teams – Samenwerkingstool van Microsoft

Related articles

Meer artikelen over Adaptive Cards:

RSS