Windows Developer Day - Adaptive Cards

概述

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 ..

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()]
    [Static(typeof(IAdaptiveCardStatics), )]
    [Version()]
    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()]
    [Static(typeof(IAdaptiveHostConfigStatics), )]
    [Version()]
    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 的简单体验和示例就到这里，后面如果产品代码中实际用到，我会再结合实际场景来具体展开分析，谢谢大家！