Адаптивні картки в Teams: як використовувати конструктор, з прикладами
By Mirko Peters ·
Як створити адаптивну картку для Microsoft Teams за допомогою конструктора Adaptive Card Designer, які версії схеми та дії підтримує Teams, правила верстки для мобільних пристроїв і мінімальний приклад JSON.
Automatically translated with AI from the original post. Read the English original
Адаптивна картка в Teams — це опис JSON для невеликого фрагмента інтерфейсу, який Teams відображає як картку повідомлення. Найшвидший спосіб створити її — Adaptive Card Designer у браузері: додайте елементи, скопіюйте JSON і надішліть його зі свого бота або застосунку. Цей посібник охоплює робочий процес у конструкторі, що підтримує Teams, правила верстки, які запобігають обрізаним карткам, і мінімальний приклад.
Головне
- Браузерний конструктор Adaptive Card Designer розміщено за адресою adaptivecards.microsoft.com/designer.html. Додайте елементи візуально, скопіюйте корисне навантаження JSON і використайте його у своєму застосунку.
- Боти Teams і розширення повідомлень підтримують версію схеми адаптивних карток 1.6 або ранішу, а мобільний Teams підтримує до 1.6 включно.
- Вхідні веб-хуки підтримують усі нативні елементи карток, крім Action.Submit. Серед підтримуваних дій там є Action.OpenURL, Action.ShowCard, Action.ToggleVisibility і Action.Execute.
- Спочатку проєктуйте для вузьких екранів, встановлюйте wrap у значення true для текстових полів і наборів вибору та використовуйте від однієї до трьох основних дій, максимум шість.
- Картки в Teams не підтримують завантаження файлів або зображень, а властивість isEnabled для Action.Submit не підтримується.
Примітка щодо джерел: сторінки Microsoft Learn, на які спирався цей матеріал, не описують селектор хост-застосунку конструктора чи його редактор зразків даних для Teams. Наведені нижче кроки ґрунтуються лише на тому, що зазначено на цих сторінках.
Відкрийте конструктор
Документація з адаптивних карток вказує на браузерний конструктор за адресою adaptivecards.microsoft.com/designer.html. Його також можна вбудувати у власний веб-застосунок за допомогою npm-пакета adaptivecards-designer. У посібнику Microsoft з Teams SDK описано трикрокову послідовність:
- Додавайте елементи візуально, доки картка не виглядатиме належно.
- Скопіюйте корисне навантаження JSON з панелі редактора.
- Вставте JSON у свій проєкт або перетворіть його на виклики конструктора.
Якщо ви віддаєте перевагу редактору, на сторінці інструментів для адаптивних карток є розширення Visual Studio Code під назвою Adaptive Card Viewer, яке показує попередній перегляд картки під час редагування файлу .json із властивістю $schema. Там також згадано AdaptiveCards Studio, який дозволяє редагувати шаблони карток і зразки даних у VS Code.
Що підтримує Teams
У довіднику карток для Teams наведено такі обмеження:
| Область | Задокументована підтримка |
|---|---|
| Версія схеми | Версія 1.6 або раніша для карток бота, розширень повідомлень, розгортання посилань і діалогів |
| Teams mobile | До версії 1.6; новіші версії можуть відображатися некоректно |
| Вхідні веб-хуки | Усі нативні елементи, крім Action.Submit |
| Action.Submit | Властивість isEnabled не підтримується |
| Стилі дій | Позитивне або деструктивне оформлення не підтримується |
| Завантаження | Завантаження файлів або зображень не підтримується |
| Розміщення | Боти, розширення повідомлень і Bot Framework позначені як підтримувані. Вкладки і конектори позначені як непідтримувані. Вхідні веб-хуки підтримують Adaptive Cards лише для типу конектора Microsoft 365 groups. |
SDK-документація додає, що її пакети карток містять схему Adaptive Card v1.5 як строгі типи. Це в межах обмеження версії 1.6.
Мінімальний приклад
Так виглядає структура, яку бот надсилає як вкладення. Її адаптовано з формату зі сторінки довідки щодо карток Teams. Картка розміщується в content, а 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" } ] } } ``
Властивість wrap є доповненням на основі наведених нижче рекомендацій щодо дизайну. Сторінка також показує динамічні значення з шаблонізацією, наприклад текстовий блок, у якого text має значення ${titleText}.
Надсилання картки
Довідка щодо карток не містить повного покрокового опису надсилання. Вона посилається на зразки Bot Framework для .NET і Node.js. Посібник Teams SDK показує патерн builder з пакетами для C# (Microsoft.Teams.Cards), Python (microsoft-teams-cards) і TypeScript (@microsoft/teams.cards). Короткий приклад на Python з посібника створює картку з текстовим блоком і надсилає її через MessageActivityInput(text="Hello text!").add_card(card). Builder перевіряє кожну властивість за схемою, тож помилки виявляються ще на етапі побудови.
Правила компонування для Teams
Рекомендації Microsoft щодо дизайну містять такі правила:
- Спочатку вузький екран. Проєктуйте насамперед для вузьких екранів. Картки добре масштабуються вгору, але не вниз.
- Перенесення тексту. Встановіть
"wrap": trueдляTextBlock,ColumnSetіInput.ChoiceSet. - Колонки. Використовуйте менше колонок для кращого відображення на мобільних пристроях. Рекомендації не містять числового обмеження кількості колонок.
- Значення ширини колонок.
autoпідлаштовує ширину під вміст і підходить для колонок з кнопками, які мають залишатися повністю видимими.stretchрівномірно ділить доступну ширину, просте число є часткою, а<number>pxозначає фіксовану ширину, яка не повинна перевищувати ширину пристрою. Не встановлюйтеautoдля всіх колонок. - Зображення. Використовуйте прозорий фон, щоб зображення адаптувалися до будь-якої теми Teams. Зображення 100 на 100 пікселів, показане розміром 50 на 50, залишиться чітким, а навпаки — пікселізується. Використовуйте
widthіheight, щоб контролювати точний розмір. - Картки на всю ширину. Перевіряйте їх у вузьких макетах, наприклад на мобільних пристроях і в бічних панелях нарад, щоб вміст не обрізався.
- Дії. Використовуйте одну-три основні дії, але не більше шести.
- Контейнери. Використовуйте
styleдля акцентів,selectAction, щоб прикріпити дію, іAction.ToggleVisibilityдля згортуваних груп. Не використовуйте контейнери для інших цілей.
Microsoft також класифікує типи карток за призначенням: Hero для статей, Thumbnail для простого повідомлення з дією, List для вибору з переліку і ChoiceSet для збору кількох вхідних даних. На сторінці дизайну зазначено, що її рекомендації належать до застарілого посібника Teams, а актуальним джерелом найкращих практик дизайну вказано центр документації Adaptive Cards.
Типові помилки
- Створення широкої картки і виявлення на мобільному пристрої, що текст обрізано.
- Використання версії схеми вище 1.6.
- Використання Action.Submit у вхідній картці веб-хука
- Надмірна кількість кнопок
- Використання фіксованої ширини в пікселях для кількох стовпців
Стартові матеріали
На сторінці дизайну є посилання на репозиторій стартових шаблонів Microsoft-Teams-Adaptive-Card-Samples на GitHub і на UI-кіт Teams у Figma, який охоплює теми оформлення, доступність і адаптивні розміри.
Пов’язане
Джерела
- Microsoft Learn: інструменти Adaptive Cards
- Microsoft Learn: створення та перегляд типів карток у Teams
- Microsoft Learn: проєктування Adaptive Cards для вашого застосунку
- Microsoft Learn: створення Adaptive Cards (Teams SDK)
FAQ
Де знайти Adaptive Card Designer?
Microsoft Learn вказує на браузерний конструктор за адресою adaptivecards.microsoft.com/designer.html. У документації до Teams SDK описано робочий процес: додайте елементи візуально, доки картка не виглядатиме належно, скопіюйте корисне навантаження JSON з панелі редактора, а потім вставте його у свій проєкт або перетворіть на виклики конструктора.
Яку версію адаптивних карток підтримує Teams?
Згідно з документацією платформи Teams на Microsoft Learn, картки, які надсилають боти, розширення повідомлень на основі дій, розширення повідомлень на основі пошуку, розгортання посилань і діалоги підтримують версію схеми 1.6 або ранішу. Мобільний застосунок Teams підтримує версії до 1.6включно, а новіші версії можуть відображатися некоректно.
Чому текст моєї картки обрізається на мобільних пристроях?
Microsoft Learn радить встановити wrap у значення true для TextBlock, ColumnSet і Input.ChoiceSet. Без цього текст на мобільних пристроях обрізається. Також рекомендовано спочатку проєктувати для вузьких екранів і використовувати менше колонок, які на мобільних відображаються краще.
Чи можна використовувати Action.Submit у картці вхідного веб-хука?
Ні. У довіднику карток Microsoft Learn зазначено, що вхідні веб-хуки підтримують усі нативні елементи адаптивних карток, крім Action.Submit. Натомість використовуйте Action.OpenURL, Action.ShowCard, Action.ToggleVisibility або Action.Execute.
Скільки кнопок має містити картка?
Microsoft Learn рекомендує від однієї до трьох основних дій і дозволяє максимум шість, наголошуючи, що менше означає краще. Також сказано, що картки мають бути стислими, адже вони втрачають корисність, щойно прокручуються поза межі видимості, особливо в каналах.