Adaptive Cards no Teams: como usar o Designer, com exemplos
By Mirko Peters ·
Como criar um Adaptive Card para o Microsoft Teams com o Adaptive Card Designer, qual versão de schema e quais ações o Teams suporta, regras de layout para celular e um exemplo mínimo em JSON.
Automatically translated with AI from the original post. Read the English original
Um Adaptive Card no Teams é uma descrição em JSON de um pequeno trecho de interface que o Teams renderiza como um cartão de mensagem. A forma mais rápida de criar um é o Adaptive Card Designer no navegador: adicione elementos, copie o JSON e envie-o pelo seu bot ou aplicativo. Este guia aborda o fluxo de trabalho do designer, o que o Teams suporta, regras de layout que evitam cartões truncados e um exemplo mínimo.
Pontos-chave
- O Adaptive Card Designer no navegador está em adaptivecards.microsoft.com/designer.html. Adicione elementos visualmente, copie o payload JSON e use-o no seu aplicativo.
- Bots e extensões de mensagem do Teams suportam a versão de schema 1.6 do Adaptive Card ou anterior, e o Teams para celular suporta até a 1.6.
- Webhooks de entrada suportam todos os elementos nativos de cartão, exceto Action.Submit. As ações suportadas nesse caso incluem Action.OpenURL, Action.ShowCard, Action.ToggleVisibility e Action.Execute.
- Projete primeiro para telas estreitas, defina wrap como true em textos e conjuntos de escolha, e use de uma a três ações principais, com no máximo seis.
- Cartões no Teams não suportam upload de arquivos ou imagens, e a propriedade isEnabled de Action.Submit não é suportada.
Uma observação sobre as fontes: as páginas da Microsoft Learn consultadas para este artigo não descrevem o seletor de aplicativo host do designer nem o editor de dados de exemplo para o Teams. Os passos a seguir se limitam ao que essas páginas afirmam.
Abra o designer
A documentação de Adaptive Cards aponta para um designer no navegador, em adaptivecards.microsoft.com/designer.html. Ele também pode ser incorporado à sua própria aplicação web com o pacote npm adaptivecards-designer. O guia do Teams SDK da Microsoft descreve um fluxo em três etapas:
- Adicione elementos visualmente até o cartão ficar como você quer.
- Copie o payload JSON do painel do editor.
- Cole o JSON no seu projeto ou converta-o em chamadas do builder.
Se você preferir um editor, a página de ferramentas de Adaptive Cards lista uma extensão do Visual Studio Code chamada Adaptive Card Viewer, que mostra a prévia do cartão enquanto você edita um arquivo .json com a propriedade $schema. Ela também cita o AdaptiveCards Studio, que permite editar templates de cartões e dados de exemplo no VS Code.
O que o Teams suporta
A referência de cartões do Teams apresenta estes limites:
| Área | Suporte documentado | |---|---| | Versão do esquema | Versão 1.6 ou anterior para cartões de bot, extensões de mensagem, pré-visualização de links e caixas de diálogo | | Teams para dispositivos móveis | Até a versão 1.6; versões posteriores podem ser exibidas de forma inconsistente | | Webhooks de entrada | Todos os elementos nativos, exceto Action.Submit | | Action.Submit | A propriedade isEnabled não é compatível | | Estilos de ação | Estilos positivo ou destrutivo não são compatíveis | | Envios | Envio de arquivos ou imagens não é compatível | | Superfícies | Bots, extensões de mensagem e Bot Framework são marcados como compatíveis. Guias e conectores são marcados como não compatíveis. Webhooks de entrada oferecem suporte a Adaptive Cards apenas para o tipo de conector de grupos do Microsoft 365. |
A documentação do SDK acrescenta que seus pacotes de cartões incluem o esquema Adaptive Card v1.5 como tipos estritos. Isso está dentro do limite da versão 1.6.
Um exemplo mínimo
Esta é a estrutura que um bot envia como anexo. Ela foi adaptada do formato da página de referência de cartões do Teams. O cartão vai em 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" } ] } } ``
A propriedade wrap é um acréscimo baseado nas diretrizes de design abaixo. A página também mostra valores dinâmicos com templates, por exemplo um bloco de texto cujo text é ${titleText}.
Enviando o cartão
A referência de cartões não inclui um passo a passo completo para envio. Ela aponta para exemplos do Bot Framework em .NET e Node.js. O guia do SDK do Teams mostra um padrão builder, com pacotes para C# (Microsoft.Teams.Cards), Python (microsoft-teams-cards) e TypeScript (@microsoft/teams.cards). Um exemplo curto em Python do guia cria um cartão com um bloco de texto e o envia com MessageActivityInput(text="Hello text!").add_card(card). Os builders validam cada propriedade contra o esquema, o que captura erros já na hora da compilação.
Regras de layout para o Teams
As diretrizes de design da Microsoft incluem estas regras:
- Comece pelo estreito. Projete primeiro para telas estreitas. Os cartões aumentam bem de tamanho, mas não diminuem bem.
- Quebre o texto. Defina
"wrap": trueemTextBlock,ColumnSeteInput.ChoiceSet. - Colunas. Use menos colunas para uma melhor exibição em dispositivos móveis. As diretrizes não apresentam um limite numérico de colunas.
- Valores de largura de coluna.
autoajusta a largura ao conteúdo e é adequado para colunas com botões que devem permanecer totalmente visíveis;stretchdivide a largura disponível igualmente; um número simples é uma proporção; e<number>pxé uma largura fixa que não deve exceder a largura do dispositivo. Não definaautoem todas as colunas. - Imagens. Use fundos transparentes para que as imagens se adaptem a qualquer tema do Teams. Uma imagem de 100 por 100 pixels exibida em 50 por 50 continua nítida, mas o inverso gera pixelização. Use
widtheheightpara controlar o tamanho exato. - Cartões de largura total. Teste-os em layouts estreitos, como dispositivos móveis e painéis laterais de reunião, para que o conteúdo não seja cortado.
- Ações. Use de uma a três ações principais, com no máximo seis.
- Contêineres. Use
stylepara dar ênfase,selectActionpara associar uma ação eAction.ToggleVisibilitypara grupos recolhíveis. Não use contêineres para outras finalidades.
A Microsoft também lista os tipos de cartão por uso, como Hero para artigos, Thumbnail para uma mensagem simples com ação, List para escolher entre itens e ChoiceSet para coletar várias entradas. A página de design observa que suas diretrizes são um guia legado do Teams e aponta para o hub de documentação de Adaptive Cards como fonte atual de boas práticas de design.
Erros comuns
- Projetar um cartão largo e descobrir no celular que o texto está cortado.
- Usar um esquema de versão acima de 1.6.
- Usando Action.Submit em um cartão de webhook de entrada.
- Adicionando botões demais.
- Usando larguras fixas em pixels em várias colunas.
Material inicial
A página de design traz links para um repositório de modelos iniciais, o Microsoft-Teams-Adaptive-Card-Samples no GitHub, e para um UI Kit do Teams no Figma, que cobre temas, acessibilidade e dimensionamento responsivo.
Relacionados
Fontes
- Microsoft Learn: ferramentas do Adaptive Cards
- Microsoft Learn: Criar e explorar tipos de cartão no Teams
- Microsoft Learn: Como projetar Adaptive Cards para o seu aplicativo
- Microsoft Learn: Como criar Adaptive Cards (SDK do Teams)
Perguntas frequentes
Onde fica o Adaptive Card Designer?
A Microsoft Learn aponta para o designer no navegador, em adaptivecards.microsoft.com/designer.html. A documentação do Teams SDK descreve o fluxo de trabalho: adicione elementos visualmente até o cartão ficar como você quer, copie o payload JSON do painel do editor e cole no seu projeto ou converta-o em chamadas do builder.
Qual versão de Adaptive Card o Teams suporta?
De acordo com a documentação da plataforma Teams na Microsoft Learn, cartões enviados por bots, extensões de mensagem baseadas em ação, extensões de mensagem baseadas em pesquisa, link unfurling e diálogos suportam a versão de schema 1.6 ou anterior. O aplicativo móvel do Teams suporta até a 1.6, e versões posteriores podem não ser exibidas corretamente nele.
Por que o texto do meu cartão é cortado no celular?
A Microsoft Learn recomenda definir wrap como true em TextBlock, ColumnSet e Input.ChoiceSet. Sem isso, o texto é truncado no celular. A documentação também orienta projetar primeiro para telas estreitas e usar menos colunas, que são exibidas melhor no celular.
Posso usar Action.Submit em um cartão de webhook de entrada?
Não. A referência de cartões da Microsoft Learn informa que os webhooks de entrada suportam todos os elementos nativos de Adaptive Card, exceto Action.Submit. Use Action.OpenURL, Action.ShowCard, Action.ToggleVisibility ou Action.Execute no lugar.
Quantos botões um cartão deve ter?
A Microsoft Learn recomenda de uma a três ações principais e permite no máximo seis, observando que menos é mais. A documentação também diz que os cartões devem ser concisos, pois perdem utilidade quando saem da área visível com a rolagem, especialmente em canais.