Sady SDK pro adaptivní šablonování karet

Sady SDK šablon adaptivních karet usnadňují naplnění šablony karet skutečnými daty na libovolné podporované platformě.

Přečtěte si tento článek pro přehled šablonování adaptivních karet.

Důležité

Zásadní změny v kandidátu na vydání z května 2020

Usilovně jsme pracovali na uvedení šablon a konečně jsme téměř u cíle! Museli jsme provést několik menších zásadních změn, jakmile se blížíme k vydání.

Zásadní změny k květnu 2020

1. Syntaxe vazby se změnila z {...} na ${...}.
   • Příklad: "text": "Hello {name}" se změní na "text": "Hello ${name}"
2. Rozhraní JAVAScript API již neobsahuje EvaluationContext objekt. Jednoduše předejte data funkci expand . Úplné podrobnosti najdete na stránce sady SDK .
3. Rozhraní .NET API bylo přepracované tak, aby lépe odpovídalo rozhraní JAVAScript API. Úplné podrobnosti najdete níže.

JavaScript

Knihovna šablon adaptivních pohlednic je k dispozici na npm a prostřednictvím CDN. Úplnou dokumentaci najdete na odkazu na balíček.

npm

npm install adaptivecards-templating

CDN

<script src="https://unpkg.com/adaptivecards-templating/dist/adaptivecards-templating.min.js"></script>

Použití

Následující ukázka předpokládá, že jste také nainstalovali knihovnu adaptivecards, abyste mohli vykreslit kartu.

Pokud nemáte v plánu vykreslovat kartu, můžete odebrat parse a render kód.

import * as ACData from "adaptivecards-templating";
import * as AdaptiveCards from "adaptivecards";
 
// Define a template payload
var templatePayload = {
    "type": "AdaptiveCard",
    "version": "1.0",
    "body": [
        {
            "type": "TextBlock",
            "text": "Hello ${name}!"
        }
    ]
};
 
// Create a Template instance from the template payload
var template = new ACData.Template(templatePayload);
 
// Expand the template with your `$root` data object.
// This binds it to the data and produces the final Adaptive Card payload
var cardPayload = template.expand({
   $root: {
      name: "Matt Hidinger"
   }
});
 
// OPTIONAL: Render the card (requires that the adaptivecards library be loaded)
var adaptiveCard = new AdaptiveCards.AdaptiveCard();
adaptiveCard.parse(cardPayload);
document.getElementById('exampleDiv').appendChild(adaptiveCard.render());

platforma .NET

dotnet add package AdaptiveCards.Templating

Použití

// Import the library 
using AdaptiveCards.Templating;

var templateJson = @"
{
    ""type"": ""AdaptiveCard"",
    ""version"": ""1.2"",
    ""body"": [
        {
            ""type"": ""TextBlock"",
            ""text"": ""Hello ${name}!""
        }
    ]
}";

// Create a Template instance from the template payload
AdaptiveCardTemplate template = new AdaptiveCardTemplate(templateJson);

// You can use any serializable object as your data
var myData = new
{
    Name = "Matt Hidinger"
};

// "Expand" the template - this generates the final Adaptive Card payload
string cardJson = template.Expand(myData);

Vlastní funkce

Kromě předem připravených funkcí je možné do knihovny adaptivních výrazů přidat i vlastní funkce.

V následujícím příkladu je přidána vlastní funkce stringFormat a funkce slouží k formátování řetězce.

string jsonTemplate = @"{
    ""type"": ""AdaptiveCard"",
    ""version"": ""1.0"",
    ""body"": [{
        ""type"": ""TextBlock"",
        ""text"": ""${stringFormat(strings.myName, person.firstName, person.lastName)}""
    }]
}";

string jsonData = @"{
    ""strings"": {
        ""myName"": ""My name is {0} {1}""
    },
    ""person"": {
        ""firstName"": ""Andrew"",
        ""lastName"": ""Leader""
    }
}";

AdaptiveCardTemplate template = new AdaptiveCardTemplate(jsonTemplate);

var context = new EvaluationContext
{
    Root = jsonData
};

// a custom function is added
AdaptiveExpressions.Expression.Functions.Add("stringFormat", (args) =>
{
    string formattedString = "";

    // argument is packed in sequential order as defined in the template
    // For example, suppose we have "${stringFormat(strings.myName, person.firstName, person.lastName)}"
    // args will have following entries
    // args[0]: strings.myName
    // args[1]: person.firstName
    // args[2]: strings.lastName
    if (args[0] != null && args[1] != null && args[2] != null) 
    {
        string formatString = args[0];
        string[] stringArguments = {args[1], args[2] };
        formattedString = string.Format(formatString, stringArguments);
    }
    return formattedString;
});

string cardJson = template.Expand(context);

Řešení problémů

Otázka. Proč dostávám chybu AdaptiveTemplateException při volání expand()?
A. Pokud chybová zpráva vypadá jako< "offending item>" na řádku, "<číslo> řádku" je chybné pro '$data : ' pair".
Ujistěte se, že hodnota zadaná pro "$data" je platná hodnota JSON, například čísla, logické hodnoty, objektu nebo pole, nebo že následuje správnou syntaxi jazyka adaptivních šablon a položka existuje v kontextu dat na konkrétní linii.

Otázka. Proč při volání expand() narazím na ArgumentNullException?
A. Pokud chybová zpráva vypadá takto: Zkontrolujte, jestli je nastavený kontext nadřazených dat, nebo zadejte nenulovou hodnotu pro '<problémová položka>' na řádku, '<řádkové číslo>'.
Značí, že pro požadovanou datnou vazbu neexistuje kontext dat. Ujistěte se, že je nastavený kontext kořenových dat, pokud existuje, ujistěte se, že je pro aktuální vazbu dostupný libovolný kontext dat, jak je uvedeno číslem řádku.

Otázka. Proč datum a čas ve formátu RFC 3389, například "2017-02-14T06:08:00Z" při použití se šablonami nefunguje s funkcemi ČAS/DATUM?
A. Toto chování vykazuje nuget sady .NET sdk verze 1.0.0-rc.0. toto chování je v následných verzích opraveno. Json.NET má u deserializéru výchozí chování, které mění řetězec formátu data a času, a v následujících verzích je tento chování zakázáno. Pomocí funkce formatDateTime() naformátujte řetězec data a času na RFC 3389, jak je vidět v tomto příkladu, nebo můžete vynechat funkce ČAS/DATUM a použít pouze formatDateTime(). Další informace o formátuDateTime() najdete tady.