Windows Developer Day - Adaptive Cards

概述 Windows Developer Day 在 Modern Application Experience 環節展示了一種可以讓開發者以更通用和統一的方式來對卡片對展示和交互的方式，那就是：Adaptive Cards. 早在 Microsoft Build 2017，Matt Hidinge ...

概述

Windows Developer Day 在 Modern Application Experience 環節展示了一種可以讓開發者以更通用和統一的方式來對卡片對展示和交互的方式，那就是：Adaptive Cards.

早在 Microsoft Build 2017，Matt Hidinger 就對 Adaptive Cards 做了展示。

而在 WDD 前夕，Adaptive Cards 1.0 版本正式 Release，開源在 GitHub Microsoft AdaptiveCards， 官網文檔在 Microsoft Doc Adaptive Cards.

基本原理

那麼 Adaptive Cards 是怎麼工作的呢？

卡片的製作者使用 JSON 或 SDK 中類構建的方式來描述卡片內容，包括文本，按鈕，圖片，鏈接等；
卡片內容在宿主程式中完成渲染，宿主程式樣式也是 JSON 或 SDK 類構建方式，樣式包括內容大小，顏色等的定義；
因為卡片的內容準備和 UI 渲染都可以完全通過 JSON 方式定義，所以使用 Adaptive Cards 各平臺 SDK，就可以使用一套 JSON 完成多平臺的通用和統一；

這種實現方式和 Adaptive Cards 要實現的目標也是一致的：

The goals for adaptive cards are:

. Portable - To any app, device, and UI framework

. Open - Libraries and schema are open source and shared

. Low cost - Easy to define, easy to consume

. Expressive - Targeted at the long tail of content that developers want to produce

. Purely declarative - No code is needed or allowed

. Automatically styled - To the Host application UX and brand guidelines

開發體驗

多平臺 SDK 支持

因為 Adaptive Cards 是一種跨平臺方案，所以官方提供了 JavaScript，Android，iOS，UWP 和 .NET 五種常用的原生 SDK 來實現集成。

Install Adaptive Cards SDK

Platform	Install	Build	Docs
JavaScript	npm v1.0.0	Source	Docs
.NET	nuget v1.0.0	Source	Docs
.NET WPF	nuget v1.0.0	Source	Docs
.NET HTML	nuget v1.0.0	Source	Docs
Windows UWP	nuget v1.0.0	Source	Docs
Android	maven-central v1.0.0	Source	Docs
iOS	pod v1.0.0	Source	Docs

而目前 Adaptive Cards 支持的平臺：

已經線上可用的：Bot Framework - WebChat，Cortana Skills，Windows Timeline
還在預覽狀態的：Skype，Outlook，Microsoft Teams，Windows Notifications，Bot Framework - Other Channels

UWP 示例開發

1. 通過 Nuget 方式在 PM 中添加包：

Install-Package AdaptiveCards.Rendering.Uwp -Version 1.0.0

2. 實例化一個 Renderer，這個 Renderer 被用來渲染宿主配置信息和卡片內容：

using AdaptiveCards.Rendering.Uwp;
...
var renderer = new AdaptiveCardRenderer();

3. 為卡片設置宿主配置：

示例中我使用一個 ComboBox 來切換宿主配置，從不同的文本文件讀取對應的 JSON 字元串，反序列化為 HostConfig 並賦值給 Renderer。

string configJson = await getCardString(string.Format(@"Assets\{0}", (hostConfigBox.SelectedItem as ComboBoxItem).Content.ToString()));
var hostConfig = AdaptiveHostConfig.FromJsonString(configJson);
renderer.HostConfig = hostConfig.HostConfig;

4. 設置卡片內容：

示例中我從文本文件中讀取內容對應的 JSON 字元串，反序列化為 AdaptiveCard 類實例。

string cardJson = await getCardString(@"Assets\card.txt");
var card = AdaptiveCard.FromJsonString(cardJson).AdaptiveCard;
RenderedAdaptiveCard renderResult = renderer.RenderAdaptiveCard(card);

5. 在界面中顯示卡片：

把卡片內容顯示在界面的 Grid 中，每次顯示時，先清空前面的顯示內容。

if (renderResult.FrameworkElement != null)
{
    var uiCard = renderResult.FrameworkElement;
    uiCard.HorizontalAlignment = HorizontalAlignment.Left;
    cardGrid.Children.Clear();
    cardGrid.Children.Add(uiCard);
}

來看看運行的效果：

可以看到，使用同樣的卡片內容，在切換不同的宿主配置 Skype 和 Microsoft Teams 時，對應的卡片渲染後的 UI 是不同的，也是符合各自宿主 UI 風格的。

UWP SDK 的使用過程基本就是這樣，非常的簡單易上手。我們來看一下中間兩個重要的類：AdaptiveCard 和 AdaptiveHostConfig.

AdaptiveCard:

這個類里，我們看到了我們用到 FromJson 方法，以及一些主要屬性：Version（用於標識更新版本），Speak （表示卡片的朗讀內容），FallbackText（後備文本），BackgroundImage（卡片背景圖片），Actions（按鈕的操作集合）等。

#region 程式集 AdaptiveCards.Rendering.Uwp, Version=255.255.255.255, Culture=neutral, PublicKeyToken=null, ContentType=WindowsRuntime
// C:\Users\123\.nuget\packages\AdaptiveCards.Rendering.Uwp\1.0.0\lib\uap10.0\AdaptiveCards.Rendering.Uwp.winmd
#endregion

using System;
using System.Collections.Generic;
using Windows.Data.Json;
using Windows.Foundation.Metadata;

namespace AdaptiveCards.Rendering.Uwp
{
    [Activatable(167772162)]
    [Static(typeof(IAdaptiveCardStatics), 167772162)]
    [Version(167772162)]
    public sealed class AdaptiveCard : IAdaptiveCard
    {
        public AdaptiveCard();

        public JsonObject ToJson();
        [Overload("FromJson")]
        public static AdaptiveCardParseResult FromJson(JsonObject adaptiveJson);
        [Overload("FromJsonWithParserRegistration")]
        public static AdaptiveCardParseResult FromJson(JsonObject adaptiveJson, AdaptiveElementParserRegistration elementRegistration, AdaptiveActionParserRegistration actionRegistration);
        [Overload("FromJsonString")]
        public static AdaptiveCardParseResult FromJsonString(string adaptiveJson);
        [Overload("FromJsonStringWithParserRegistration")]
        public static AdaptiveCardParseResult FromJsonString(string adaptiveJson, AdaptiveElementParserRegistration elementRegistration, AdaptiveActionParserRegistration actionRegistration);

        public string Version { get; set; }
        public ContainerStyle Style { get; set; }
        public string Speak { get; set; }
        public string FallbackText { get; set; }
        public Uri BackgroundImage { get; set; }
        public IList<IAdaptiveActionElement> Actions { get; }
        public IList<IAdaptiveCardElement> Body { get; }
        public ElementType ElementType { get; }
    }
}

而針對 AdaptiveCard 的格式，完整的說明文檔可以在官方文檔的 Card Schema 中看到：https://docs.microsoft.com/zh-cn/adaptive-cards/create/cardschema

對應上面的示例，我們使用的 JSON 文件大致組成如下：

AdaptiveHostConfig:

這裡類里，我們看到了我們用到的 FromJson 方法，以及設置宿主樣式的配置信息，如字體，文字大小，按鈕操作，文字間距等樣式配置。大家也可以再去具體看每個配置都有哪些枚舉值可用。

#region 程式集 AdaptiveCards.Rendering.Uwp, Version=255.255.255.255, Culture=neutral, PublicKeyToken=null, ContentType=WindowsRuntime
// C:\Users\123\.nuget\packages\AdaptiveCards.Rendering.Uwp\1.0.0\lib\uap10.0\AdaptiveCards.Rendering.Uwp.winmd
#endregion

using Windows.Data.Json;
using Windows.Foundation.Metadata;

namespace AdaptiveCards.Rendering.Uwp
{
    [Activatable(167772162)]
    [Static(typeof(IAdaptiveHostConfigStatics), 167772162)]
    [Version(167772162)]
    public sealed class AdaptiveHostConfig : IAdaptiveHostConfig
    {
        public AdaptiveHostConfig();

        public static AdaptiveHostConfigParseResult FromJsonString(string hostConfigJson);
        public static AdaptiveHostConfigParseResult FromJson(JsonObject hostConfigJson);

        public bool SupportsInteractivity { get; set; }
        public AdaptiveSpacingConfig Spacing { get; set; }
        public AdaptiveSeparatorConfig Separator { get; set; }
        public AdaptiveImageSizesConfig ImageSizes { get; set; }
        public AdaptiveImageSetConfig ImageSet { get; set; }
        public AdaptiveImageConfig Image { get; set; }
        public AdaptiveFontWeightsConfig FontWeights { get; set; }
        public AdaptiveFontSizesConfig FontSizes { get; set; }
        public string FontFamily { get; set; }
        public AdaptiveFactSetConfig FactSet { get; set; }
        public AdaptiveContainerStylesDefinition ContainerStyles { get; set; }
        public AdaptiveCardConfig AdaptiveCard { get; set; }
        public AdaptiveActionsConfig Actions { get; set; }
    }
}

而針對 AdaptiveHostConfig 的欄位，完整的說明文檔可以在官方文檔的 Card Schema 中看到：https://docs.microsoft.com/zh-cn/adaptive-cards/display/hostconfig

對應上面的示例，我們使用的 JSON 文件大致組成如下：

如果大家想簡單體驗一下 AdaptiveCard 和 AdaptiveHostConfig 的變化對卡片的影響，不想自己寫 Demo，也可以通過它提供的線上體驗的方式：http://adaptivecards.io/visualizer/index.html?hostApp=Bot%20Framework%20WebChat

通過這個線上編輯器，可以很直觀的看到每個欄位的修改對卡片的影響。

對 Adaptive Cards 的簡單體驗和示例就到這裡，後面如果產品代碼中實際用到，我會再結合實際場景來具體展開分析，謝謝大家！