アダプティブカードのテンプレート

[アーティクル]
08/28/2023

アダプティブカードの作成、再利用、共有に役立つ新しいツールのプレビューをご紹介します。

重要

2020 年 5 月リリース候補での破壊的変更

テンプレートリリース候補には、古いパッケージを使用している場合に注意する必要がある破壊的変更がいくつか含まれています。詳細については、以下参照してください。

2020 年 5 月時点での破壊的変更

バインディング構文が {...} から ${...} に変更されました。
- たとえば、"text": "Hello {name}" が "text": "Hello ${name}" になります。
JavaScript API に EvaluationContext オブジェクトが含まれなくなりました。単にデータを expand 関数に渡すだけです。詳細については、SDK ページを参照してください。
.NET API は、JavaScript API により近づくように再設計されました。詳細については、SDK ページを参照してください。

テンプレートの利用方法

テンプレートを使用すると、アダプティブカードのレイアウトからデータを分離することができます。

カードを 1 回デザインしてから実際のデータを設定するのに役立つ

現在、アダプティブカードデザイナーを使用してカードを作成し、その JSON を使用してペイロードに動的なコンテンツを設定することはできません。これを実現するには、JSON 文字列を作成するためのカスタムコードを記述するか、オブジェクトモデル SDK を使用してカードを表す OM を作成し、それを JSON にシリアル化する必要があります。どちらの場合も、デザイナーは 1 回限りの一方向の操作であり、コードに変換した後はカードのデザインを簡単に調整できません。

ネットワーク経由での転送サイズが小さくなる

テンプレートとデータをクライアント上で直接結合できる環境があると想像してください。つまり、同じテンプレートを複数回使用する場合、または新しいデータで更新する場合は、新しいデータをデバイスに送信することだけ必要で、同じテンプレートを何度も再利用することができます。

入力したデータだけから優れた外観のカードを作成するのに役立つ

アダプティブカードは優れたものと思われますが、ユーザーに表示するものすべてに対してアダプティブカードを作成しなくてもよかったらどうでしょうか。テンプレートサービス (以下で説明) を使用すると、すべてのユーザーが任意の種類のデータに対してテンプレートの投稿、検出、共有を行うことができる環境を作成できます。

ご自身のプロジェクト内、ご自身の組織内、またはインターネット全体で共有します。

AI やその他のサービスにより、ユーザーエクスペリエンスが向上する可能性がある

コンテンツからデータを分離することによって、表示されるカード内のデータを "推論" するためのドアを AI やその他のサービスに開き、ユーザーの生産性を向上させたり、マイクロソフトが情報を見つけやすくしたりします。

アダプティブカードテンプレートとは

これは、3 つの主要なコンポーネントで構成されています。

テンプレート言語 は、テンプレートの作成に使用される構文です。デザイナーでは、"サンプルデータ" を含めることによって、デザイン時にテンプレートのプレビューを表示することもできます。
テンプレート SDK は、サポートされているすべてのアダプティブカードプラットフォーム上に存在します。これらの SDK を使用すると、テンプレートに実際のデータをバックエンドで、またはクライアント上で直接設定できます。
テンプレートサービス は、一連の既知のテンプレートをだれでも検索、投稿、共有できるようにする概念実証サービスです。

テンプレート言語

テンプレート言語は、アダプティブカードテンプレートを作成するために使用される構文です。

注意

新しいタブを開いて次の例に追従する

https://adaptivecards.io/designer

デザインモードとプレビューモード間を切り替えるには、 [プレビューモード] ボタンをクリックします。

Designer screenshot

新しく更新されたデザイナーでは、テンプレートの作成と、デザイン時にカードのプレビューを表示するためのサンプルデータの提供のサポートが追加されます。

次の例を [Card Payload Editor]$カードペイロードエディター$ ウィンドウに貼り付けます。

EmployeeCardTemplate.json

{
    "type": "AdaptiveCard",
    "version": "1.0",
    "body": [
        {
            "type": "ColumnSet",
            "style": "accent",
            "bleed": true,
            "columns": [
                {
                    "type": "Column",
                    "width": "auto",
                    "items": [
                        {
                            "type": "Image",
                            "url": "${photo}",
                            "altText": "Profile picture",
                            "size": "Small",
                            "style": "Person"
                        }
                    ]
                },
                {
                    "type": "Column",
                    "width": "stretch",
                    "items": [
                        {
                            "type": "TextBlock",
                            "text": "Hi ${name}!",
                            "size": "Medium"
                        },
                        {
                            "type": "TextBlock",
                            "text": "Here's a bit about your org...",
                            "spacing": "None"
                        }
                    ]
                }
            ]
        },
        {
            "type": "TextBlock",
            "text": "Your manager is: **${manager.name}**"
        },
        {
            "type": "TextBlock",
            "text": "Your peers are:"
        },
        {
            "type": "FactSet",
            "facts": [
                {
                    "$data": "${peers}",
                    "title": "${name}",
                    "value": "${title}"
                }
            ]
        }
    ]
}

次に、以下の JSON データをサンプルデータエディターに貼り付けます。

サンプルデータを使用すると、実行時に実際のデータが渡されたときにカードがどのように表示されるかを正確に確認できます。

EmployeeData

{
    "name": "Matt",
    "photo": "https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg",
    "manager": {
        "name": "Thomas",
        "title": "PM Lead"
    },
    "peers": [
        {
            "name": "Lei",
            "title": "Sr Program Manager"
        },
        {
            "name": "Andrew",
            "title": "Program Manager II"
        },
        {
            "name": "Mary Anne",
            "title": "Program Manager"
        }
    ]
}

[プレビューモード] ボタンをクリックします。上記のサンプルデータに従って、カードのレンダリングが表示されます。サンプルデータを自由に調整し、カードの更新をリアルタイムで確認できます。

これで終了です。初めてのアダプティブカードテンプレートを作成しました。次に、テンプレートに実際のデータを設定する方法について説明します。

テンプレート言語に関する詳細情報

SDK サポート

テンプレート SDK を使用すると、テンプレートに実際のデータを設定できるようになります。

注意

現時点では、テンプレート SDK は .NET と NodeJS で利用できます。時間の経過と共に、iOS、Android、UWP など、残りのすべてのアダプティブカードプラットフォーム用のテンプレート SDK がリリースされます。

プラットフォーム	パッケージ	［インストール］	ドキュメント
JavaScript		`npm install adaptivecards-templating`	ドキュメント
.NET		`dotnet add package AdaptiveCards.Templating`	ドキュメント

JavaScript の例

次の JavaScript は、テンプレートにデータを設定するために使用される一般的なパターンを示しています。

var template = new ACData.Template({ 
    // Card Template JSON
});

var card = template.expand({
    $root: {
        // Data Fields
    }
});

// Now you have an AdaptiveCard ready to render!

C# の例

以下の C# は、テンプレートにデータを事前設定するために使用される一般的なパターンを示しています。

var template = new AdaptiveCards.Templating.AdaptiveCardTemplate(cardJson);
   
var card = template.Expand(new {Key="Value"});

// Now you have an AdaptiveCard ready to render!

テンプレート SDK に関する詳細情報

テンプレートサービス

アダプティブカードテンプレートサービスは、一連の既知のテンプレートをだれでも検索、投稿、共有できるようにする概念実証サービスです。

一部のデータを表示する必要があるが、そのためにカスタムのアダプティブカードを作成するのが面倒な場合に便利です。

テンプレートを取得するための API は十分に簡単ですが、実際にはサービスによって、データを分析し、ユーザーに役立つ可能性のあるテンプレートを見つける機能など、さらに多くの機能が提供されます。

HTTP GET https://templates.adaptivecards.io/graph.microsoft.com/Profile.json

すべてのテンプレートは、GitHub リポジトリに格納されているフラットな JSON ファイルなので、他のオープンソースコードと同じようにだれでも投稿できます。

カードテンプレートサービスに関する詳細情報

次の手順とフィードバックの送信

テンプレートとデータからのプレゼンテーションの分離により、"アプリとサービスとの間のエコシステム標準化されたコンテンツの交換" というミッションにかなり近づきます。この分野はこれから大きく成長していく予定ですのでご期待ください。またご利用の感想について GitHub でお知らせください。

アダプティブ カードのテンプレート