Tarjetas adaptativas en Teams: cómo usar el diseñador, con ejemplos
Por Mirko Peters ·
Cómo diseñar una tarjeta adaptativa para Microsoft Teams con el diseñador de tarjetas adaptativas, qué versión del esquema y qué acciones admite Teams, reglas de diseño para móvil y un ejemplo mínimo en JSON.
Traducido automáticamente con IA a partir de la publicación original. Lee el original en inglés
Una tarjeta adaptativa en Teams es una descripción en JSON de un pequeño fragmento de interfaz que Teams muestra como tarjeta de mensaje. La forma más rápida de crear una es el diseñador de tarjetas adaptativas en el navegador: añade elementos, copia el JSON y envíalo desde tu bot o aplicación. Esta guía cubre el flujo de trabajo del diseñador, lo que admite Teams, las reglas de diseño que evitan tarjetas truncadas y un ejemplo mínimo.
Puntos clave
- El diseñador de tarjetas adaptativas en navegador está en adaptivecards.microsoft.com/designer.html. Añade elementos visualmente, copia la carga útil JSON y úsala en tu aplicación.
- Los bots y las extensiones de mensajes de Teams admiten la versión 1.6 del esquema de tarjetas adaptativas o anteriores, y Teams móvil admite hasta la 1.6.
- Los webhooks entrantes admiten todos los elementos nativos de tarjeta excepto Action.Submit. Las acciones compatibles incluyen Action.OpenURL, Action.ShowCard, Action.ToggleVisibility y Action.Execute.
- Diseña primero para pantallas estrechas, establece wrap en true en el texto y en los conjuntos de opciones, y usa entre una y tres acciones principales, con un máximo de seis.
- Las tarjetas de Teams no admiten la carga de archivos ni de imágenes, y la propiedad isEnabled de Action.Submit no está soportada.
Una nota sobre las fuentes: las páginas de Microsoft Learn consultadas para este artículo no describen el selector de aplicación host del diseñador ni su editor de datos de ejemplo para Teams. Los pasos siguientes se ciñen a lo que indican las páginas.
Abre el diseñador
La documentación de tarjetas adaptativas apunta a un diseñador basado en navegador en adaptivecards.microsoft.com/designer.html. También puede incrustarse en tu propia aplicación web con el paquete npm adaptivecards-designer. La guía del SDK de Teams de Microsoft describe un flujo de tres pasos:
- Añade elementos visualmente hasta que la tarjeta tenga el aspecto correcto.
- Copia la carga útil JSON del panel del editor.
- Pega el JSON en tu proyecto o conviértelo en llamadas del generador.
Si prefieres un editor, la página de herramientas de tarjetas adaptativas enumera una extensión de Visual Studio Code llamada Adaptive Card Viewer, que muestra una vista previa de la tarjeta mientras editas un archivo .json con una propiedad $schema. También menciona AdaptiveCards Studio, que permite editar plantillas de tarjetas y datos de ejemplo en VS Code.
Lo que admite Teams
La referencia de tarjetas de Teams establece estos límites:
| Área | Compatibilidad documentada |
|---|---|
| Versión del esquema | Versión 1.6 o anterior para tarjetas de bot, extensiones de mensaje, vista previa de enlaces y diálogos |
| Teams móvil | Hasta la versión 1.6; las versiones posteriores podrían mostrarse de forma incoherente |
| Webhooks entrantes | Todos los elementos nativos excepto Action.Submit |
| Action.Submit | La propiedad isEnabled no es compatible |
| Estilos de acción | Los estilos positivo o destructivo no son compatibles |
| Cargas | No se admiten cargas de archivos ni de imágenes |
| Superficies | Los bots, las extensiones de mensaje y Bot Framework figuran como compatibles. Las pestañas y los conectores figuran como no compatibles. Los webhooks entrantes solo admiten Adaptive Cards para el tipo de conector de grupos de Microsoft 365. |
La documentación del SDK añade que sus paquetes de tarjetas incluyen el esquema de Adaptive Card v1.5 como tipos estrictos. Eso está dentro del límite de la versión 1.6.
Un ejemplo mínimo
Esta es la estructura que un bot envía como datos adjuntos. Está adaptada del formato de la página de referencia de tarjetas de Teams. La tarjeta va en content, y contentType es 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 propiedad wrap es una adición basada en las recomendaciones de diseño que se indican a continuación. La página también muestra valores dinámicos con plantillas; por ejemplo, un bloque de texto cuyo text es ${titleText}.
Envío de la tarjeta
La referencia de tarjetas no incluye un recorrido completo para el envío. Remite a los ejemplos de Bot Framework para .NET y Node.js. La guía del SDK de Teams muestra un patrón de creación (builder) con paquetes para C# (Microsoft.Teams.Cards), Python (microsoft-teams-cards) y TypeScript (@microsoft/teams.cards). Un breve ejemplo en Python de la guía crea una tarjeta con un bloque de texto y la envía con MessageActivityInput(text="Hello text!").add_card(card). Los builders validan cada propiedad frente al esquema, lo que detecta errores en el momento de la compilación.
Reglas de diseño para Teams
Las recomendaciones de diseño de Microsoft incluyen estas reglas:
- Primero, estrecho. Diseña primero para pantallas estrechas. Las tarjetas se escalan bien hacia arriba, pero no hacia abajo.
- Ajusta el texto. Establece
"wrap": trueenTextBlock,ColumnSeteInput.ChoiceSet. - Columnas. Usa menos columnas para mejorar la visualización en móviles. La guía no indica un límite numérico de columnas.
- Valores de ancho de columna.
autoajusta el ancho al contenido y es adecuado para columnas con botones que deben verse completos;stretchreparte el ancho disponible por igual; un número sin unidad es una proporción, y<number>pxes un ancho fijo que no debería superar el ancho del dispositivo. No establezcasautoen todas las columnas. - Imágenes. Usa fondos transparentes para que las imágenes se adapten a cualquier tema de Teams. Una imagen de 100 por 100 píxeles mostrada a 50 por 50 se ve nítida, pero lo contrario provoca pixelado. Usa
widthyheightpara controlar el tamaño exacto. - Tarjetas de ancho completo. Pruébalas en diseños estrechos, como los de móvil y los paneles laterales de reuniones, para que el contenido no se trunque.
- Acciones. Usa de una a tres acciones principales, con un máximo de seis.
- Contenedores. Usa
stylepara destacar,selectActionpara asociar una acción yAction.ToggleVisibilitypara grupos plegables. No uses contenedores para otros fines.
Microsoft también clasifica los tipos de tarjeta por uso, como Hero para artículos, Thumbnail para un mensaje simple con acción, List para elegir entre elementos y ChoiceSet para recopilar varias entradas. La página de diseño indica que su guía es una guía heredada de Teams y señala el centro de documentación de Adaptive Cards como la fuente actual de buenas prácticas de diseño.
Errores comunes
- Diseñar una tarjeta ancha y descubrir en móvil que el texto aparece cortado.
- Usar un esquema de versión superior a 1.6.
- Usar Action.Submit en una tarjeta de webhook entrante.
- Añadir demasiados botones.
- Usar anchos fijos en píxeles en varias columnas.
Material inicial
La página de diseño enlaza a un repositorio de plantillas de inicio, Microsoft-Teams-Adaptive-Card-Samples en GitHub, y a un Teams UI Kit en Figma que cubre temas, accesibilidad y dimensionado adaptable.
Relacionado
Fuentes
- Microsoft Learn: herramientas de Adaptive Cards
- Microsoft Learn: Crear y explorar tipos de tarjetas en Teams
- Microsoft Learn: Diseño de Adaptive Cards para tu aplicación
- Microsoft Learn: Creación de Adaptive Cards (SDK de Teams)
Preguntas frecuentes
¿Dónde está el diseñador de tarjetas adaptativas?
Microsoft Learn apunta al diseñador basado en navegador en adaptivecards.microsoft.com/designer.html. La documentación del SDK de Teams describe el flujo de trabajo: añade elementos visualmente hasta que la tarjeta tenga el aspecto correcto, copia la carga útil JSON del panel del editor y pégala en tu proyecto o conviértela en llamadas del generador.
¿Qué versión de tarjetas adaptativas admite Teams?
Según la documentación de la plataforma Teams en Microsoft Learn, las tarjetas enviadas por bots, las extensiones de mensajes basadas en acciones, las extensiones de mensajes basadas en búsqueda, la expansión de enlaces y los diálogos admiten la versión 1.6 del esquema o anteriores. La aplicación móvil de Teams admite hasta la 1.6, y las versiones posteriores podrían no mostrarse correctamente allí.
¿Por qué se corta el texto de mi tarjeta en el móvil?
Microsoft Learn indica que hay que establecer wrap en true en TextBlock, ColumnSet e Input.ChoiceSet. Sin ello, el texto se trunca en el móvil. También recomienda diseñar primero para pantallas estrechas y usar menos columnas, que se muestran mejor en el móvil.
¿Puedo usar Action.Submit en una tarjeta de webhook entrante?
No. La referencia de tarjetas de Microsoft Learn indica que los webhooks entrantes admiten todos los elementos nativos de tarjetas adaptativas excepto Action.Submit. Usa en su lugar Action.OpenURL, Action.ShowCard, Action.ToggleVisibility o Action.Execute.
¿Cuántos botones debe tener una tarjeta?
Microsoft Learn recomienda entre una y tres acciones principales y permite un máximo de seis, señalando que menos es más. También indica que las tarjetas deben ser concisas, porque pierden utilidad cuando quedan fuera de la vista al desplazarse, sobre todo en los canales.