Teams のアダプティブカード: デザイナーの使い方と例
By Mirko Peters ·
Adaptive Card Designer を使って Microsoft Teams 向けのアダプティブカードを設計する方法を解説します。Teams がサポートするスキーマ バージョンとアクション、モバイル向けのレイアウト ルール、最小限の JSON 例を紹介します。
Automatically translated with AI from the original post. Read the English original
Teams のアダプティブカードは、Teams がメッセージ カードとして表示する小さなインターフェイスを記述した JSON です。作成がもっとも早いのは、ブラウザーの Adaptive Card Designer を使う方法です。要素を追加し、JSON をコピーして、ボットやアプリから送信します。本記事では、デザイナーの作業の流れ、Teams がサポートする内容、カードの途切れを防ぐレイアウト ルール、最小限の例を取り上げます。
重要なポイント
- ブラウザーで使える Adaptive Card Designer は adaptivecards.microsoft.com/designer.html にあります。要素を視覚的に追加し、JSON ペイロードをコピーして、アプリで使用します。
- Teams のボットとメッセージ拡張機能は、アダプティブカードのスキーマ バージョン 1.6 以前をサポートします。Teams モバイルは 1.6 までサポートします。
- 受信 Webhook は、Action.Submit を除くすべてのネイティブ カード要素をサポートします。サポートされるアクションは、Action.OpenURL、Action.ShowCard、Action.ToggleVisibility、Action.Execute です。
- まず狭い画面を前提に設計し、テキストと選択肢のセットで wrap を true に設定してください。主要なアクションは 1 つから 3 つにし、最大 6 つまでにします。
- Teams のカードでは、ファイルや画像のアップロードはサポートされていません。また、Action.Submit の isEnabled プロパティもサポートされていません。
出典についての注記: 本記事で参照した Microsoft Learn のページには、Teams 向けデザイナーのホスト アプリ セレクターやサンプル データ エディターについての記載はありません。以下の手順は、ページに明記されている内容に限定しています。
デザイナーを開く
アダプティブカードのドキュメントでは、ブラウザーで使えるデザイナーとして adaptivecards.microsoft.com/designer.html が案内されています。また、adaptivecards-designer npm パッケージを使って、独自の Web アプリに組み込むこともできます。Microsoft の Teams SDK ガイドでは、次の 3 ステップの流れが説明されています。
- カードの見た目が整うまで、要素を視覚的に追加します。
- エディター ウィンドウから JSON ペイロードをコピーします。
- JSON をプロジェクトに貼り付けるか、ビルダーの呼び出しに変換します。
エディターを使いたい場合は、アダプティブカードのツール ページに、Visual Studio Code 拡張機能「Adaptive Card Viewer」が掲載されています。これは、$schema プロパティを持つ .json ファイルを編集しながらカードをプレビューするものです。同ページには、VS Code でカード テンプレートとサンプル データを編集できる AdaptiveCards Studio も掲載されています。
Teams がサポートする内容
Teams のカード リファレンスには、次の制限が記載されています。
| 項目 | ドキュメントで確認できるサポート内容 |
|---|---|
| スキーマ バージョン | ボット カード、メッセージ拡張機能、リンク プレビュー、ダイアログではバージョン 1.6 以前 |
| Teams モバイル | バージョン 1.6 まで。それ以降のバージョンでは表示が不安定になる可能性があります |
| 受信 Webhook | Action.Submit を除くすべてのネイティブ要素 |
| Action.Submit | isEnabled プロパティはサポートされていません |
| アクションのスタイル | 肯定的 (positive) または破壊的 (destructive) なスタイルはサポートされていません |
| アップロード | ファイルや画像のアップロードはサポートされていません |
| サーフェス | ボット、メッセージ拡張機能、Bot Framework はサポート対象とされています。タブとコネクタはサポート対象外とされています。受信 Webhook が Adaptive Cards をサポートするのは、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} になっているテキスト ブロックなどです。
カードの送信
カード リファレンスには、送信方法の完全な解説は含まれていません。代わりに、.NET と Node.js 向けの Bot Framework サンプルが紹介されています。Teams SDK のガイドでは、ビルダー パターンが示されており、C# (Microsoft.Teams.Cards)、Python (microsoft-teams-cards)、TypeScript (@microsoft/teams.cards) のパッケージが用意されています。ガイドの短い Python の例では、テキスト ブロックを含むカードを作成し、MessageActivityInput(text="Hello text!").add_card(card) を使って送信しています。ビルダーはすべてのプロパティをスキーマに照らして検証するため、エラーはビルド時点で検出されます。
Teams のレイアウト ルール
Microsoft のデザイン ガイダンスには、次のルールが含まれています。
- まず狭い画面を前提に設計する。 最初に狭い画面向けに設計します。カードは拡大には対応しやすい一方、縮小には対応しにくいためです。
- テキストを折り返す。
TextBlock、ColumnSet、Input.ChoiceSetに"wrap": trueを設定します。 - 列。 モバイルでの表示を良くするため、列数は少なくします。ガイダンスには列数の数値的な上限は示されていません。
- 列幅の値。
autoはコンテンツに合わせてサイズを決めるため、完全に表示される必要があるボタンを含む列に適しています。stretchは利用可能な幅を均等に分け合います。数値だけを指定した場合は比率になります。<number>pxは固定幅で、デバイスの幅を超えないようにします。すべての列にautoを設定しないでください。 - 画像。 画像がどの Teams テーマにも馴染むように、背景は透過にします。100 x 100 ピクセルの画像を 50 x 50 で表示すればくっきり見えますが、逆の場合は粗くなります。正確なサイズを指定するには
widthとheightを使います。 - 全幅のカード。 モバイルや会議のサイド パネルなど、狭いレイアウトでテストし、コンテンツが切り捨てられないことを確認します。
- アクション。 主要なアクションは 1~3 個にとどめ、最大でも 6 個までにします。
- コンテナー。 強調には
style、アクションの割り当てにはselectAction、折りたたみ可能なグループにはAction.ToggleVisibilityを使います。ほかの目的でコンテナーを使わないでください。
Microsoft では、用途別のカードの種類も挙げています。記事向けの Hero、シンプルな操作可能なメッセージ向けの Thumbnail、項目から選択するための List、複数の入力を収集するための ChoiceSet などです。デザイン ページには、このガイダンスは従来の Teams ガイドであると注記されており、現在のデザインのベスト プラクティスの情報源として Adaptive Cards のドキュメント ハブが案内されています。
よくある間違い
- 幅の広いカードを設計したあとで、モバイルではテキストが切れていることに気づく。
- スキーマ バージョン 1.6 を超えるバージョンを使用する。
- incoming webhook カードで Action.Submit を使用する
- ボタンを詰め込みすぎる
- 複数の列で固定ピクセル幅を使用する
スターター素材
デザインのページには、スターターテンプレートのリポジトリ(GitHub 上の Microsoft-Teams-Adaptive-Card-Samples)と、テーマ設定、アクセシビリティ、レスポンシブなサイズ調整を扱う Figma の Teams UI Kit へのリンクがあります。
関連情報
データソース
- 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 はどのバージョンのアダプティブカードをサポートしていますか?
Microsoft Learn の Teams プラットフォーム ドキュメントによると、ボットから送信されるカード、アクション ベースのメッセージ拡張機能、検索ベースのメッセージ拡張機能、リンクのアンファール、ダイアログは、スキーマ バージョン 1.6 以前をサポートしています。Teams モバイル アプリは 1.6 までをサポートし、それより新しいバージョンは正しく表示されない可能性があります。
モバイルでカードのテキストが途切れるのはなぜですか?
Microsoft Learn では、TextBlock、ColumnSet、Input.ChoiceSet で wrap を true に設定するよう案内しています。設定しないと、モバイルではテキストが切り詰められます。また、狭い画面を前提に最初に設計し、列数を減らすことも勧めています。列数が少ないほうがモバイルでは見やすく表示されるためです。
受信 Webhook のカードで Action.Submit は使えますか?
いいえ、使えません。Microsoft Learn のカード リファレンスでは、受信 Webhook は Action.Submit を除くすべてのネイティブ アダプティブカード要素をサポートすると明記されています。代わりに Action.OpenURL、Action.ShowCard、Action.ToggleVisibility、Action.Execute を使用してください。
カードのボタンはいくつ配置するのがよいですか?
Microsoft Learn では、主要なアクションは 1 つから 3 つにすることを推奨し、最大 6 つまで許容しています。また、少ないほうがよいとしています。特にチャネルでは、カードが表示領域からスクロールして外れると役に立たなくなるため、カードは簡潔に保つべきだと説明されています。