M365Con 2027 – conferenza online gratuita · 11–22 Jan 2027 · 120 sessions m365con.net

Blog · Mirko Peters

Adaptive Card in Teams: come usare il Designer, con esempi

Di ·

Come progettare una Adaptive Card per Microsoft Teams con l'Adaptive Card Designer, quali versioni dello schema e quali azioni supporta Teams, le regole di layout per il mobile e un esempio JSON minimo.

Tradotto automaticamente con l'IA dal post originale. Leggi l'originale in inglese

Un'Adaptive Card in Teams è una descrizione in JSON di una piccola porzione di interfaccia che Teams visualizza come scheda di messaggio. Il modo più rapido per crearne una è l'Adaptive Card Designer nel browser: aggiungi gli elementi, copia il JSON e invialo dal tuo bot o dalla tua app. Questa guida copre il flusso di lavoro del designer, ciò che Teams supporta, le regole di layout che evitano le card troncate e un esempio minimo.

Punti chiave

  • Il designer di Adaptive Card basato su browser si trova all'indirizzo adaptivecards.microsoft.com/designer.html. Aggiungi gli elementi in modo visivo, copia il payload JSON e usalo nella tua app.
  • I bot di Teams e le estensioni dei messaggi supportano la versione 1.6 o precedenti dello schema delle Adaptive Card, e il mobile di Teams supporta fino alla 1.6.
  • I webhook in ingresso supportano tutti gli elementi nativi delle card tranne Action.Submit. Le azioni supportate includono Action.OpenURL, Action.ShowCard, Action.ToggleVisibility e Action.Execute.
  • Progetta prima per schermi stretti, imposta wrap su true per testo e set di scelte, e usa da una a tre azioni principali, con un massimo di sei.
  • Le card in Teams non supportano il caricamento di file o immagini, e la proprietà isEnabled di Action.Submit non è supportata.

Una nota sulle fonti: le pagine di Microsoft Learn consultate per questo articolo non descrivono il selettore dell'app host del designer né il suo editor dei dati di esempio per Teams. I passaggi seguenti si attengono a quanto riportato in quelle pagine.

Apri il designer

La documentazione delle Adaptive Card indica un designer basato su browser all'indirizzo adaptivecards.microsoft.com/designer.html. Può anche essere incorporato in una tua web app con il pacchetto npm adaptivecards-designer. La guida all'SDK di Teams di Microsoft descrive un flusso in tre passaggi:

  1. Aggiungi gli elementi in modo visivo finché la card non ha l'aspetto giusto.
  2. Copia il payload JSON dal riquadro dell'editor.
  3. Incolla il JSON nel tuo progetto, oppure convertilo in chiamate al builder.

Se preferisci un editor, la pagina degli strumenti per Adaptive Card elenca un'estensione per Visual Studio Code chiamata Adaptive Card Viewer, che mostra l'anteprima della card mentre modifichi un file .json con una proprietà $schema. Elenca anche AdaptiveCards Studio, che permette di modificare i modelli di card e i dati di esempio in VS Code.

Cosa supporta Teams

Il riferimento alle card di Teams indica questi limiti:

| Area | Supporto documentato | |---|---| | Versione dello schema | Versione 1.6 o precedente per bot card, estensioni di messaggi, link unfurling e finestre di dialogo | | Teams mobile | Fino alla versione 1.6; le versioni successive potrebbero visualizzarsi in modo incoerente | | Webhook in entrata | Tutti gli elementi nativi tranne Action.Submit | | Action.Submit | La proprietà isEnabled non è supportata | | Stili delle azioni | Gli stili positivo o distruttivo non sono supportati | | Caricamenti | Il caricamento di file o immagini non è supportato | | Superfici | Bot, estensioni di messaggi e Bot Framework sono indicati come supportati. Schede e connettori sono indicati come non supportati. I webhook in entrata supportano le Adaptive Card solo per il tipo di connettore dei gruppi di Microsoft 365. |

La documentazione dell'SDK aggiunge che i suoi pacchetti di card includono lo schema Adaptive Card v1.5 come tipi strict. Questo rientra nel limite della versione 1.6.

Un esempio minimo

Questa è la struttura che un bot invia come allegato. È adattata dal formato della pagina di riferimento delle card di Teams. La card va in content, e contentType è 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 proprietà wrap è un'aggiunta basata sulle linee guida di design riportate sotto. La pagina mostra anche i valori dinamici con il templating, per esempio un blocco di testo il cui text è ${titleText}.

Invio della card

La pagina di riferimento delle card non include una guida completa all'invio. Rimanda agli esempi di Bot Framework per .NET e Node.js. La guida dell'SDK di Teams mostra un pattern builder con pacchetti per C# (Microsoft.Teams.Cards), Python (microsoft-teams-cards) e TypeScript (@microsoft/teams.cards). Un breve esempio in Python tratto dalla guida crea una card con un blocco di testo e la invia con MessageActivityInput(text="Hello text!").add_card(card). I builder convalidano ogni proprietà rispetto allo schema, intercettando gli errori già in fase di build.

Regole di layout per Teams

Le linee guida di design di Microsoft includono queste regole:

  • Prima gli schermi stretti. Progetta prima per gli schermi stretti. Le card si adattano bene a schermi più grandi, ma non viceversa.
  • Testo a capo. Imposta "wrap": true su TextBlock, ColumnSet e Input.ChoiceSet.
  • Colonne. Usa meno colonne per una migliore visualizzazione su mobile. Le linee guida non indicano un limite numerico di colonne.
  • Valori della larghezza delle colonne. auto adatta la larghezza al contenuto ed è indicato per le colonne con pulsanti che devono restare completamente visibili, stretch divide equamente la larghezza disponibile, un numero semplice è una proporzione e <number>px è una larghezza fissa che non dovrebbe superare la larghezza del dispositivo. Non impostare auto su tutte le colonne.
  • Immagini. Usa sfondi trasparenti, così le immagini si adattano a qualsiasi tema di Teams. Un'immagine di 100 x 100 pixel mostrata a 50 x 50 resta nitida, ma il contrario la pixelerebbe. Usa width e height per controllare la dimensione esatta.
  • Card a larghezza piena. Testale in layout stretti, come quelli mobile e i pannelli laterali delle riunioni, così il contenuto non viene troncato.
  • Azioni. Usa da una a tre azioni principali, con un massimo di sei.
  • Contenitori. Usa style per dare enfasi, selectAction per associare un'azione e Action.ToggleVisibility per i gruppi comprimibili. Non usare i contenitori per altri scopi.

Microsoft elenca anche i tipi di card in base all'uso, come Hero per gli articoli, Thumbnail per un messaggio semplice con azione, List per scegliere tra più elementi e ChoiceSet per raccogliere più input. La pagina di design precisa che le sue indicazioni provengono da una guida Teams obsoleta e indica l'hub della documentazione di Adaptive Cards come fonte attuale per le best practice di design.

Errori comuni

  1. Progettare una card larga e scoprire su mobile che il testo viene tagliato.
  2. Usare una versione dello schema superiore alla 1.6.
  3. Uso di Action.Submit in una scheda per webhook in ingresso.
  4. Troppi pulsanti.
  5. Uso di larghezze fisse in pixel su più colonne.

Materiale di partenza

La pagina di progettazione rimanda a un repository di modelli di partenza, Microsoft-Teams-Adaptive-Card-Samples su GitHub, e a un kit UI di Teams in Figma che copre temi, accessibilità e dimensionamento reattivo.

Correlati

Fonti

Segui il podcastApple PodcastsSpotify

FAQ

Dov'è l'Adaptive Card Designer?

Microsoft Learn rimanda al designer basato su browser all'indirizzo adaptivecards.microsoft.com/designer.html. La documentazione dell'SDK di Teams descrive il flusso di lavoro: aggiungi gli elementi in modo visivo finché la card non ha l'aspetto giusto, copia il payload JSON dal riquadro dell'editor, poi incollalo nel tuo progetto o convertilo in chiamate al builder.

Quale versione di Adaptive Card supporta Teams?

Secondo la documentazione della piattaforma Teams su Microsoft Learn, le card inviate dai bot, le estensioni dei messaggi basate su azioni, le estensioni dei messaggi basate sulla ricerca, l'unfurling dei link e le finestre di dialogo supportano la versione dello schema 1.6 o precedenti. L'app mobile di Teams supporta fino alla 1.6; versioni successive potrebbero non essere visualizzate correttamente.

Perché il testo della mia card viene troncato su mobile?

Microsoft Learn indica di impostare wrap su true per TextBlock, ColumnSet e Input.ChoiceSet. Senza questa impostazione, il testo viene troncato su mobile. Suggerisce inoltre di progettare prima per schermi stretti e di usare meno colonne, che si visualizzano meglio su mobile.

Posso usare Action.Submit in una card di un webhook in ingresso?

No. Il riferimento alle card di Microsoft Learn indica che i webhook in ingresso supportano tutti gli elementi nativi delle Adaptive Card tranne Action.Submit. Usa invece Action.OpenURL, Action.ShowCard, Action.ToggleVisibility o Action.Execute.

Quanti pulsanti dovrebbe avere una card?

Microsoft Learn consiglia da una a tre azioni principali e ne consente al massimo sei, ricordando che meno è meglio. Sottolinea inoltre che le card devono restare concise, perché perdono utilità quando scorrono fuori dalla vista, soprattutto nei canali.

Entità in questo articolo

Temi di questo articolo:

Adaptive Cards – Prodotto Adaptive Cards Designer – Parte di Adaptive Cards Microsoft Teams – Strumento di collaborazione di Microsoft

Articoli correlati

Altri articoli su Adaptive Cards:

RSS