Adaptive Cards in Teams: So nutzen Sie den Designer, mit Beispielen
Von Mirko Peters ·
So gestalten Sie eine Adaptive Card für Microsoft Teams mit dem Adaptive Card Designer: welche Schemaversion und welche Aktionen Teams unterstützt, Layoutregeln für mobile Geräte und ein minimales JSON-Beispiel.
Automatisch mit KI aus dem Originalbeitrag übersetzt. Englisches Original lesen
Eine Adaptive Card in Teams ist eine JSON-Beschreibung eines kleinen Oberflächenelements, das Teams als Nachrichtenkarte darstellt. Am schnellsten erstellen Sie eine solche Karte im Adaptive Card Designer im Browser: Elemente hinzufügen, JSON kopieren und aus Ihrem Bot oder Ihrer App senden. Dieser Leitfaden behandelt den Ablauf im Designer, was Teams unterstützt, Layoutregeln, die abgeschnittene Karten vermeiden, und ein minimales Beispiel.
Das Wichtigste in Kürze
- Der browserbasierte Adaptive Card Designer ist unter adaptivecards.microsoft.com/designer.html erreichbar. Fügen Sie Elemente visuell hinzu, kopieren Sie die JSON-Nutzlast und verwenden Sie sie in Ihrer App.
- Teams-Bots und Nachrichtenerweiterungen unterstützen die Adaptive-Card-Schemaversion 1.6 oder früher, die mobile Teams-App bis einschließlich 1.6.
- Eingehende Webhooks unterstützen alle nativen Kartenelemente außer Action.Submit. Unterstützte Aktionen sind dort Action.OpenURL, Action.ShowCard, Action.ToggleVisibility und Action.Execute.
- Gestalten Sie zuerst für schmale Bildschirme, setzen Sie wrap auf true bei Text und Auswahlsätzen, und verwenden Sie ein bis drei primäre Aktionen, maximal sechs.
- Karten in Teams unterstützen keine Datei- oder Bild-Uploads, und die Eigenschaft isEnabled von Action.Submit wird nicht unterstützt.
Hinweis zu den Quellen: Die für diesen Artikel gelesenen Microsoft-Learn-Seiten beschreiben weder die Auswahl der Host-App im Designer noch dessen Editor für Beispieldaten für Teams. Die folgenden Schritte halten sich an das, was die Seiten belegen.
Den Designer öffnen
Die Adaptive-Cards-Dokumentation verweist auf den browserbasierten Designer unter adaptivecards.microsoft.com/designer.html. Er lässt sich auch mit dem npm-Paket adaptivecards-designer in eine eigene Web-App einbetten. Der Leitfaden des Teams SDK von Microsoft beschreibt einen dreistufigen Ablauf:
- Elemente visuell hinzufügen, bis die Karte passt.
- Die JSON-Nutzlast aus dem Editorbereich kopieren.
- Das JSON in Ihr Projekt einfügen oder in Builder-Aufrufe umwandeln.
Wenn Sie lieber einen Editor verwenden, listet die Seite der Adaptive-Cards-Werkzeuge eine Visual-Studio-Code-Erweiterung namens Adaptive Card Viewer auf. Sie zeigt die Karte in der Vorschau an, während Sie eine .json-Datei mit einer $schema-Eigenschaft bearbeiten. Ebenfalls genannt wird AdaptiveCards Studio, mit dem Sie Kartenvorlagen und Beispieldaten in VS Code bearbeiten können.
Was Teams unterstützt
Die Kartenreferenz für Teams nennt folgende Einschränkungen:
| Bereich | Dokumentierte Unterstützung | |---|---| | Schemaversion | Version 1.6 oder früher für Bot-Karten, Nachrichtenerweiterungen, Link-Vorschauen und Dialoge | | Teams mobil | Bis Version 1.6, neuere Versionen werden möglicherweise uneinheitlich dargestellt | | Eingehende Webhooks | Alle nativen Elemente außer Action.Submit | | Action.Submit | Die Eigenschaft isEnabled wird nicht unterstützt | | Aktionsformatierung | Positive oder destruktive Formatierung wird nicht unterstützt | | Uploads | Datei- oder Bild-Uploads werden nicht unterstützt | | Einsatzbereiche | Bots, Nachrichtenerweiterungen und Bot Framework sind als unterstützt gekennzeichnet. Registerkarten und Connectors sind als nicht unterstützt gekennzeichnet. Eingehende Webhooks unterstützen Adaptive Cards nur für den Connector-Typ Microsoft 365-Gruppen. |
Die SDK-Dokumentation ergänzt, dass ihre Kartenpakete das Adaptive Card-Schema v1.5 als strikte Typen bündeln. Das liegt innerhalb der Grenze von Version 1.6.
Ein minimales Beispiel
Dies ist die Struktur, die ein Bot als Anlage sendet. Sie ist an das Format auf der Kartenreferenzseite für Teams angelehnt. Die Karte steht in content, und contentType lautet 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" } ] } } ``
Die Eigenschaft wrap ist eine Ergänzung auf Basis der nachfolgenden Gestaltungsempfehlungen. Die Seite zeigt außerdem dynamische Werte mit Templating, etwa einen Textblock, dessen text ${titleText} ist.
Senden der Karte
Die Kartenreferenz enthält keine vollständige Schritt-für-Schritt-Anleitung zum Senden. Sie verweist auf Bot-Framework-Beispiele für .NET und Node.js. Der Teams-SDK-Leitfaden zeigt ein Builder-Muster mit Paketen für C# (Microsoft.Teams.Cards), Python (microsoft-teams-cards) und TypeScript (@microsoft/teams.cards). Ein kurzes Python-Beispiel aus dem Leitfaden erstellt eine Karte mit einem Textblock und sendet sie mit MessageActivityInput(text="Hello text!").add_card(card). Builder prüfen jede Eigenschaft gegen das Schema und fangen so Fehler bereits zur Build-Zeit ab.
Layoutregeln für Teams
Die Gestaltungsempfehlungen von Microsoft umfassen folgende Regeln:
- Schmal zuerst. Gestalten Sie zuerst für schmale Bildschirme. Karten skalieren gut nach oben, aber nicht nach unten.
- Text umbrechen. Setzen Sie
"wrap": truebeiTextBlock,ColumnSetundInput.ChoiceSet. - Spalten. Verwenden Sie weniger Spalten für eine bessere Darstellung auf dem Smartphone. Die Empfehlungen nennen keine numerische Obergrenze für Spalten.
- Werte für die Spaltenbreite.
autopasst sich an den Inhalt an und eignet sich für Spalten mit Schaltflächen, die vollständig sichtbar bleiben müssen.stretchverteilt die verfügbare Breite gleichmäßig. Eine reine Zahl ist ein Anteil, und<number>pxist eine feste Breite, die die Gerätebreite nicht überschreiten sollte. Setzen Sieautonicht für jede Spalte. - Bilder. Verwenden Sie transparente Hintergründe, damit sich Bilder an jedes Teams-Design anpassen. Ein Bild mit 100 x 100 Pixeln, das mit 50 x 50 angezeigt wird, bleibt scharf, umgekehrt entstehen Pixelfehler. Steuern Sie die exakte Größe über
widthundheight. - Karten in voller Breite. Testen Sie sie in schmalen Layouts wie auf dem Smartphone und in seitlichen Bereichen von Besprechungen, damit Inhalte nicht abgeschnitten werden.
- Aktionen. Verwenden Sie eine bis drei primäre Aktionen, maximal sechs.
- Container. Verwenden Sie
stylezur Hervorhebung,selectAction, um eine Aktion anzuhängen, undAction.ToggleVisibilityfür einklappbare Gruppen. Verwenden Sie Container nicht für andere Zwecke.
Microsoft führt Kartentypen außerdem nach Verwendungszweck auf, etwa Hero für Artikel, Thumbnail für eine einfache handlungsorientierte Nachricht, List zur Auswahl aus Elementen und ChoiceSet zum Erfassen mehrerer Eingaben. Die Designseite weist darauf hin, dass ihre Empfehlungen aus einem älteren Teams-Leitfaden stammen, und verweist für aktuelle Best Practices auf die Dokumentationsübersicht zu Adaptive Cards.
Häufige Fehler
- Eine breite Karte entwerfen und auf dem Smartphone feststellen, dass der Text abgeschnitten wird.
- Eine Schemaversion über 1.6 verwenden.
- Verwendung von Action.Submit in einer Karte für eingehende Webhooks.
- Zu viele Schaltflächen hinzufügen.
- Feste Pixelbreiten für mehrere Spalten verwenden.
Startmaterial
Die Designseite verlinkt auf ein Repository mit Vorlagen als Ausgangspunkt, Microsoft-Teams-Adaptive-Card-Samples auf GitHub, sowie auf ein Teams UI Kit in Figma, das Theming, Barrierefreiheit und responsive Größenanpassung abdeckt.
Verwandte Themen
Quellen
- Microsoft Learn: Tools für Adaptive Cards
- Microsoft Learn: Kartentypen in Teams erstellen und erkunden
- Microsoft Learn: Adaptive Cards für Ihre App gestalten
- Microsoft Learn: Adaptive Cards erstellen (Teams SDK)
FAQ
Wo finde ich den Adaptive Card Designer?
Microsoft Learn verweist auf den browserbasierten Designer unter adaptivecards.microsoft.com/designer.html. In der Dokumentation des Teams SDK wird der Ablauf beschrieben: Elemente visuell hinzufügen, bis die Karte passt, die JSON-Nutzlast aus dem Editorbereich kopieren und anschließend in Ihr Projekt einfügen oder in Builder-Aufrufe umwandeln.
Welche Adaptive-Card-Version unterstützt Teams?
Laut der Teams-Plattformdokumentation auf Microsoft Learn unterstützen von Bots gesendete Karten, aktionsbasierte Nachrichtenerweiterungen, suchbasierte Nachrichtenerweiterungen, Link-Vorschauen (Unfurling) und Dialoge die Schemaversion 1.6 oder früher. Die mobile Teams-App unterstützt bis einschließlich 1.6. Spätere Versionen werden dort unter Umständen nicht korrekt dargestellt.
Warum wird mein Kartentext auf dem Smartphone abgeschnitten?
Microsoft Learn empfiehlt, bei TextBlock, ColumnSet und Input.ChoiceSet wrap auf true zu setzen. Ohne diese Einstellung wird Text auf mobilen Geräten gekürzt. Außerdem rät Microsoft dazu, zuerst für schmale Bildschirme zu gestalten und weniger Spalten zu verwenden, da diese auf dem Smartphone besser dargestellt werden.
Kann ich Action.Submit in einer eingehenden Webhook-Karte verwenden?
Nein. Laut der Kartenreferenz auf Microsoft Learn unterstützen eingehende Webhooks alle nativen Adaptive-Card-Elemente außer Action.Submit. Verwenden Sie stattdessen Action.OpenURL, Action.ShowCard, Action.ToggleVisibility oder Action.Execute.
Wie viele Schaltflächen sollte eine Karte haben?
Microsoft Learn empfiehlt ein bis drei primäre Aktionen und erlaubt maximal sechs. Weniger ist mehr. Karten sollten außerdem knapp gehalten werden, denn sie verlieren an Nutzen, sobald sie aus dem Sichtfeld scrollen, besonders in Kanälen.