M365Con 2027 – безкоштовна онлайн-конференція · 11–22 Jan 2027 · 120 sessions m365con.net

Блог · Mirko Peters

Адаптивні картки в Teams: як використовувати конструктор, з прикладами

By ·

Як створити адаптивну картку для 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 описано трикрокову послідовність:

  1. Додавайте елементи візуально, доки картка не виглядатиме належно.
  2. Скопіюйте корисне навантаження JSON з панелі редактора.
  3. Вставте 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. Створення широкої картки і виявлення на мобільному пристрої, що текст обрізано.
  2. Використання версії схеми вище 1.6.
  3. Використання Action.Submit у вхідній картці веб-хука
  4. Надмірна кількість кнопок
  5. Використання фіксованої ширини в пікселях для кількох стовпців

Стартові матеріали

На сторінці дизайну є посилання на репозиторій стартових шаблонів Microsoft-Teams-Adaptive-Card-Samples на GitHub і на UI-кіт Teams у Figma, який охоплює теми оформлення, доступність і адаптивні розміри.

Пов’язане

Джерела

Підписатися на подкастApple PodcastsSpotify

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 рекомендує від однієї до трьох основних дій і дозволяє максимум шість, наголошуючи, що менше означає краще. Також сказано, що картки мають бути стислими, адже вони втрачають корисність, щойно прокручуються поза межі видимості, особливо в каналах.

Entities in this article

Теми цієї статті:

Adaptive Cards – Продукт Adaptive Cards Designer – Частина Adaptive Cards Microsoft Teams – Інструмент для спільної роботи від Microsoft

Related articles

Інші статті на тему Adaptive Cards:

RSS