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

アダプティブ カードの 作成再利用共有 に役立つ新しいツールのプレビューをご紹介します。We're excited to share a preview of new tools that will help you create, reuse, and share Adaptive Cards.

重要

2020 年 5 月リリース候補 での 破壊的変更Breaking changes in the May 2020 Release Candidate

テンプレート リリース候補には、古いパッケージを使用している場合に注意する必要がある破壊的変更がいくつか含まれています。The templating release candidate includes some minor breaking changes that you should be aware of if you've been using the older packages. 詳細については、以下参照してください。See below for details.

2020 年 5 月時点での破壊的変更Breaking changes as of May 2020

  1. バインディング構文が {...} から ${...} に変更されました。The binding syntax changed from {...} to ${...}.
    • たとえば、"text": "Hello {name}""text": "Hello ${name}" になります。For Example: "text": "Hello {name}" becomes "text": "Hello ${name}"
  2. JavaScript API に EvaluationContext オブジェクトが含まれなくなりました。The JavaScript API no longer contains an EvaluationContext object. 単にデータを expand 関数に渡すだけです。Simply pass your data to the expand function. 詳細については、SDK ページを参照してください。Please see the SDK page for full details.
  3. .NET API は、JavaScript API により近づくように再設計されました。The .NET API was redesigned to more closely match the JavaScript API. 詳細については、SDK ページを参照してください。Please see the SDK page for full details.

テンプレートの利用方法How can templating help you

テンプレートを使用すると、アダプティブ カードの レイアウト から データ を分離することができます。Templating enables the separation of data from the layout in an Adaptive Card.

カードを 1 回デザインしてから実際のデータを設定するのに役立つIt helps design a card once, and then populate it with real data

現在、アダプティブ カード デザイナーを使用してカードを作成し、その JSON を使用してペイロードに 動的なコンテンツ を設定することはできません。Today it's impossible to create a card using the Adaptive Card Designer and use that JSON to populate the payload with dynamic content. これを実現するには、JSON 文字列を作成するためのカスタム コードを記述するか、オブジェクト モデル SDK を使用してカードを表す OM を作成し、それを JSON にシリアル化する必要があります。In order to achieve this you must write custom code to build a JSON string, or use the Object Model SDKs to build an OM representing your card and serialize it to JSON. どちらの場合も、デザイナーは 1 回限りの一方向の操作であり、コードに変換した後はカードのデザインを簡単に調整できません。In either case the Designer is a one-time one-way operation and doesn't make it easy to tweak the card design later once you've converted it to code.

ネットワーク経由での転送サイズが小さくなるIt makes transmissions over the wire smaller

テンプレートとデータを クライアント上で直接 結合できる環境があると想像してください。Imagine a world where a template and data can be combined directly on the client. つまり、同じテンプレートを複数回使用する場合、または新しいデータで更新する場合は、新しいデータをデバイスに送信することだけ必要で、同じテンプレートを何度も再利用することができます。This means if you use the same template multiple times, or want to update it with new data, you just need to send new data to the device and it can re-use the same template over and over.

入力したデータだけから優れた外観のカードを作成するのに役立つIt helps you create a great looking card from just the data you provide

アダプティブ カードは優れたものと思われますが、ユーザーに表示するものすべてに対してアダプティブ カードを作成しなくてもよかったらどうでしょうか。We think Adaptive Cards are great, but what if you didn't have to write an Adaptive Card for everything you want to display to a user? テンプレート サービス (以下で説明) を使用すると、すべてのユーザーが任意の種類のデータに対してテンプレートの投稿、検出、共有を行うことができる環境を作成できます。With a template service (described below) we can create a world where everyone can contribute, discover, and share templates over any type of data.

ご自身のプロジェクト内、ご自身の組織内、またはインターネット全体で共有します。Share within your own projects, your organization, or with the entire internet.

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

コンテンツからデータを分離することによって、表示されるカード内のデータを "推論" するためのドアを AI やその他のサービスに開き、ユーザーの生産性を向上させたり、マイクロソフトが情報を見つけやすくしたりします。By separating data from content it opens a door for AI and other services to "reason" over the data in the cards we see and enhance user productivity or help us find things.

アダプティブ カード テンプレートとはWhat is Adaptive Cards Templating?

これは、3 つの主要なコンポーネントで構成されています。It's comprised of 3 major components:

  1. テンプレート言語 は、テンプレートの作成に使用される構文です。The Template Language is the syntax used for authoring a template. デザイナーでは、"サンプル データ" を含めることによって、デザイン時にテンプレートのプレビューを表示することもできます。The Designer even lets you preview your templates at design time by including "sample data".
  2. テンプレート SDK は、サポートされているすべてのアダプティブ カード プラットフォーム上に存在します。The Templating SDK's will exist on all supported Adaptive Card platforms. これらの SDK を使用すると、テンプレートに実際のデータをバックエンドで、またはクライアント上で直接設定できます。These SDKs allow you to populate a template with real data, on the back-end or directly on the client.
  3. テンプレート サービス は、一連の既知のテンプレートをだれでも検索、投稿、共有できるようにする概念実証サービスです。The Template Service is a proof-of-concept service that allows anyone to find, contribute to, and share a set of well-known templates.

テンプレート言語Template Language

テンプレート言語は、アダプティブ カード テンプレートを作成するために使用される構文です。The template language is the syntax used to author an Adaptive Card template.

注意

新しいタブを開いて次の例に追従するFollow along with the example below by opening up a new tab to

https://adaptivecards.io/designer

デザイン モードとプレビュー モード間を切り替えるには、 [プレビュー モード] ボタンをクリックします。Click the Preview Mode button to toggle between design-mode and preview-mode.

デザイナーのスクリーンショット

新しく更新されたデザイナーでは、テンプレートの作成と、デザイン時にカードのプレビューを表示するための サンプル データ の提供のサポートが追加されます。The newly updated Designer adds support for authoring templates and providing Sample Data to preview the card at design-time.

次の例を [Card Payload Editor](カード ペイロード エディター) ウィンドウに貼り付けます。Paste the example below into the Card Payload Editor pane:

EmployeeCardTemplate.jsonEmployeeCardTemplate.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 データを サンプル データ エディター に貼り付けます。Then paste the JSON data below into the Sample Data Editor.

サンプル データ を使用すると、実行時に実際のデータが渡されたときにカードがどのように表示されるかを正確に確認できます。Sample Data helps you see exactly how your card will appear at runtime when passed actual data.

EmployeeDataEmployeeData

{
    "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"
        }
    ]
}

[プレビュー モード] ボタンをクリックします。Click the Preview Mode button. 上記のサンプル データに従って、カードのレンダリングが表示されます。You should see the card render according to the sample data provided above. サンプル データを自由に調整し、カードの更新をリアルタイムで確認できます。Feel free to make tweaks to the sample data and watch the card update in realtime.

これで終了です。初めてのアダプティブ カード テンプレートを作成しました。Congratulations, you just authored your first Adaptive Card Template! 次に、テンプレートに実際のデータを設定する方法について説明します。Next let's learn how to populate the template with real data.

テンプレート言語に関する詳細情報Learn more about the template language

SDK サポートSDK support

テンプレート SDK を使用すると、テンプレートに実際のデータを設定できるようになります。The Templating SDKs make it possible to populate a template with real-data.

注意

現時点では、テンプレート SDK は .NET と NodeJS で利用できます。At this time templating SDKs are available for .NET and NodeJS. 時間の経過と共に、iOS、Android、UWP など、残りのすべてのアダプティブ カード プラットフォーム用のテンプレート SDK がリリースされます。Over time we will release templating SDKs for all remaining Adaptive Cards platform, like iOS, Android, UWP, etc.

プラットフォームPlatform パッケージPackage [インストール]Install ドキュメントDocumentation
JavaScriptJavaScript npm インストールnpm install npm install adaptivecards-templating ドキュメントDocumentation
.NET.NET Nuget インストールNuget install dotnet add package AdaptiveCards.Templating ドキュメントDocumentation

JavaScript の例JavaScript Example

次の JavaScript は、テンプレートにデータを設定するために使用される一般的なパターンを示しています。The JavaScript below shows the general pattern that will be used to populate a template with data.

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# Example

以下の C# は、テンプレートにデータを事前設定するために使用される一般的なパターンを示しています。The C# below shows the general pattern that will be used to populate a template with data.

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

// Now you have an AdaptiveCard ready to render!

テンプレート SDK に関する詳細情報Learn more about the templating SDKs

テンプレート サービスTemplate Service

アダプティブ カード テンプレート サービスは、一連の既知のテンプレートをだれでも検索、投稿、共有できるようにする概念実証サービスです。The Adaptive Cards Template Service is a proof-of-concept service that allows anyone to find, contribute to, and share a set of well-known templates.

一部のデータを表示する必要があるが、そのためにカスタムのアダプティブ カードを作成するのが面倒な場合に便利です。It's useful if you want to display some data but don't want to bother writing a custom Adaptive Card for it.

テンプレートを取得するための API は十分に簡単ですが、実際にはサービスによって、データを分析し、ユーザーに役立つ可能性のあるテンプレートを見つける機能など、さらに多くの機能が提供されます。The API to get a template is straight-forward enough, but the service actually offers much more, including the ability to analyze your data and find a template that might work for you.

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

すべてのテンプレートは、GitHub リポジトリに格納されているフラットな JSON ファイルなので、他のオープン ソース コードと同じようにだれでも投稿できます。All templates are flat JSON files stored in a GitHub repo so anyone can contribute to them like any other open source code.

カード テンプレート サービスに関する詳細情報Learn more about the card template Service

次の手順とフィードバックの送信What's next and sending feedback

テンプレートとデータからのプレゼンテーションの分離により、"アプリとサービスとの間のエコシステム標準化されたコンテンツの交換" というミッションにかなり近づきます。Templating and the separation of presentation from data takes us a whole lot closer toward our mission: "an ecosystem standardized content exchange between apps and services". この分野はこれから大きく成長していく予定ですのでご期待ください。またご利用の感想について GitHub でお知らせください。We've got plenty to deliver in this area, so stay tuned and let us know how it's working for you on GitHub!