M365Con 2027 – die kostenlose Online-Konferenz · 11–22 Jan 2027 · 120 sessions m365con.net

Blog · Mirko Peters

Adaptive Cards in Teams: So nutzen Sie den Designer, mit Beispielen

Von ·

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:

  1. Elemente visuell hinzufügen, bis die Karte passt.
  2. Die JSON-Nutzlast aus dem Editorbereich kopieren.
  3. 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": true bei TextBlock, ColumnSet und Input.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. auto passt sich an den Inhalt an und eignet sich für Spalten mit Schaltflächen, die vollständig sichtbar bleiben müssen. stretch verteilt die verfügbare Breite gleichmäßig. Eine reine Zahl ist ein Anteil, und <number>px ist eine feste Breite, die die Gerätebreite nicht überschreiten sollte. Setzen Sie auto nicht 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 width und height.
  • 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 style zur Hervorhebung, selectAction, um eine Aktion anzuhängen, und Action.ToggleVisibility fü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

  1. Eine breite Karte entwerfen und auf dem Smartphone feststellen, dass der Text abgeschnitten wird.
  2. Eine Schemaversion über 1.6 verwenden.
  3. Verwendung von Action.Submit in einer Karte für eingehende Webhooks.
  4. Zu viele Schaltflächen hinzufügen.
  5. 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

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.

Entitäten in diesem Artikel

Themen dieses Artikels:

Adaptive Cards – Produkt Adaptive Cards Designer – Teil von Adaptive Cards Microsoft Teams – Werkzeug für die Zusammenarbeit von Microsoft

Verwandte Artikel

Weitere Artikel zu Adaptive Cards:

RSS