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 поддерживают схему Adaptive Card версии 1.6 или более ранней, а мобильное приложение Teams поддерживает версии до 1.6 включительно.
  • Входящие вебхуки поддерживают все встроенные элементы карточек, кроме Action.Submit. Поддерживаемые действия включают Action.OpenURL, Action.ShowCard, Action.ToggleVisibility и Action.Execute.
  • Сначала проектируйте для узких экранов, задавайте wrap со значением true для текста и наборов выбора, используйте одно–три основных действия, но не более шести.
  • Карточки в Teams не поддерживают загрузку файлов и изображений, а свойство isEnabled для Action.Submit не поддерживается.

Примечание об источниках: страницы Microsoft Learn, на которых основана эта статья, не описывают переключатель host-приложения в конструкторе и редактор примеров данных для Teams. Далее приведены только те шаги, которые описаны в этих страницах.

Открытие конструктора

Документация по Adaptive Cards указывает на браузерный конструктор по адресу adaptivecards.microsoft.com/designer.html. Его также можно встроить в собственное веб-приложение с помощью npm-пакета adaptivecards-designer. В руководстве Microsoft по Teams SDK описан трёхшаговый процесс:

  1. Добавляйте элементы визуально, пока карточка не будет выглядеть нужным образом.
  2. Скопируйте полезную нагрузку JSON из панели редактора.
  3. Вставьте JSON в свой проект или преобразуйте его в вызовы конструктора.

Если вы предпочитаете редактор, на странице инструментов Adaptive Cards перечислено расширение для Visual Studio Code под названием Adaptive Card Viewer, которое показывает предпросмотр карточки во время редактирования файла .json со свойством $schema. Там же упоминается AdaptiveCards Studio, с помощью которого можно редактировать шаблоны карточек и примеры данных в VS Code.

Что поддерживает Teams

В справочнике карточек Teams приведены следующие ограничения:

| Область | Документально подтверждённая поддержка | |---|---| | Версия схемы | Версия 1.6 или более ранняя для карточек ботов, расширений сообщений, предпросмотра ссылок и диалогов | | Teams на мобильных устройствах | До версии 1.6; более поздние версии могут отображаться некорректно | | Входящие вебхуки | Все нативные элементы, кроме Action.Submit | | Action.Submit | Свойство isEnabled не поддерживается | | Стили действий | Позитивное и деструктивное оформление не поддерживается | | Загрузки | Загрузка файлов или изображений не поддерживается | | Поверхности | Боты, расширения сообщений и Bot Framework отмечены как поддерживаемые. Вкладки и коннекторы отмечены как не поддерживаемые. Входящие вебхуки поддерживают адаптивные карточки только для типа коннектора «Группы Microsoft 365». |

Документация 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 показан шаблон построителя с пакетами для C# (Microsoft.Teams.Cards), Python (microsoft-teams-cards) и TypeScript (@microsoft/teams.cards). Короткий пример на Python из руководства создаёт карточку с текстовым блоком и отправляет её с помощью MessageActivityInput(text="Hello text!").add_card(card). Построители проверяют каждое свойство по схеме, что позволяет обнаруживать ошибки на этапе сборки.

Правила компоновки для 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 во входящей веб-карточке (incoming webhook).
  4. Слишком много кнопок.
  5. Фиксированная ширина в пикселях для нескольких колонок.

Исходные материалы

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

Связанное

Источники

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

FAQ

Где находится конструктор Adaptive Card Designer?

В документации Microsoft Learn указан браузерный конструктор по адресу adaptivecards.microsoft.com/designer.html. В документации Teams SDK описан порядок работы: добавляйте элементы визуально, пока карточка не будет выглядеть нужным образом, скопируйте полезную нагрузку JSON из панели редактора, а затем вставьте её в проект или преобразуйте в вызовы конструктора.

Какую версию Adaptive Card поддерживает Teams?

Согласно документации платформы Teams на Microsoft Learn, карточки, отправляемые ботами, расширения сообщений на основе действий, расширения сообщений на основе поиска, разворачивание ссылок и диалоги поддерживают схему версии 1.6 или более ранней. Мобильное приложение Teams поддерживает версии до 1.6включительно, более поздние версии могут отображаться некорректно.

Почему текст моей карточки обрезается на мобильных устройствах?

Microsoft Learn рекомендует задавать для TextBlock, ColumnSet и Input.ChoiceSet свойство wrap со значением true. Без него текст на мобильных устройствах обрезается. Там же советуют сначала проектировать для узких экранов и использовать меньше колонок, которые на мобильных устройствах отображаются лучше.

Можно ли использовать Action.Submit во входящей карточке вебхука?

Нет. В справочнике карточек Microsoft Learn указано, что входящие вебхуки поддерживают все встроенные элементы Adaptive Card, кроме 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