Zestawy SDK tworzenia szablonów kart adaptacyjnych

Zestawy SDK tworzenia szablonów kart adaptacyjnych ułatwiają wypełnianie szablonu karty rzeczywistymi danymi na dowolnej obsługiwanej platformie.

Przeczytaj to, aby zapoznać się z omówieniem tworzenia szablonów kart adaptacyjnych

Zmiany łamiące zgodność od maja 2020 r.

1. Składnia powiązania została zmieniona z {...} na ${...}.
   • Na przykład: "text": "Hello {name}" staje się "text": "Hello ${name}"
2. API JavaScript nie zawiera już obiektu EvaluationContext. Wystarczy przekazać dane do funkcji expand. Aby uzyskać szczegółowe informacje, zobacz stronę zestawu SDK .
3. Interfejs API platformy .NET został przeprojektowany tak, aby był ściślej zgodny z interfejsem API języka JavaScript. Poniżej znajdują się szczegółowe informacje.

JavaScript

Biblioteka tworzenia szablonów kart adaptacyjnych jest dostępna w usłudze npm i za pośrednictwem sieci CDN. Zobacz link do pakietu, aby uzyskać pełną dokumentację.

npm

npm install adaptivecards-templating

CDN

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

Zastosowanie

W poniższym przykładzie przyjęto założenie, że zainstalowano również bibliotekę kart adaptacyjnych w celu renderowania karty.

Jeśli nie planujesz renderowania karty, możesz usunąć kod parse i render .

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());

.NET

dotnet add package AdaptiveCards.Templating

Zastosowanie

// 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);

Funkcje niestandardowe

Funkcje niestandardowe można dodawać do biblioteki wyrażeń adaptacyjnych oprócz wstępnie utworzonych funkcji.

W poniższym przykładzie dodano niestandardową funkcję stringFormat, a funkcja jest używana do formatowania ciągu.

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);

Rozwiązywanie problemów

Pytanie Dlaczego napotykam na błąd AdaptiveTemplateException podczas wywoływania expand()?
Odp. Jeśli komunikat o błędzie wygląda jak "<błędny element>" w wierszu, "<numer wiersza>" jest nieprawidłowy dla pary '$data : '".
Upewnij się, że wartość podana dla parametru "$data" jest prawidłowym plikiem JSON, takim jak liczba, wartość logiczna, obiekt i tablica, lub jest zgodna z poprawną składnią języka adaptacyjnego szablonu, a wpis istnieje w kontekście danych pod numerem wiersza.

Pytanie Dlaczego natrafiam na wyjątek ArgumentNullException podczas wywoływania expand()?
Odp. Jeśli komunikat o błędzie wygląda następująco: Sprawdź, czy ustawiono kontekst danych nadrzędnych, lub wprowadź wartość inną niż "null" dla '<błędnego elementu>' w wierszu, '<numerze linii>'.
Wskazuje, że nie istnieje kontekst danych dla żądanego powiązania danych. Upewnij się, że kontekst danych głównych jest ustawiony, jeśli istnieje, upewnij się, że dowolny kontekst danych jest dostępny dla bieżącego powiązania, zgodnie z numerem wiersza.

Pytanie Dlaczego data/godzina w formacie RFC 3389, np. "2017-02-14T06:08:00Z" w przypadku użycia z szablonem nie działa z funkcjami TIME/DATE?
Odp. Zestaw .NET SDK nuget w wersji 1.0.0-rc.0 wykazuje to zachowanie. to zachowanie jest poprawiane w kolejnych wersjach. json.Net domyślne zachowanie deserializatora zostało zmienione, aby ciąg formatu daty/godziny został wyłączony w kolejnych wydaniach. Użyj funkcji formatDateTime(), aby sformatować ciąg daty/godziny na RFC 3389, jak pokazano w tym przykładzie, lub możesz pominąć funkcje TIME/DATE i po prostu użyć formatDateTime(). Aby uzyskać więcej informacji na temat formatDateTime(), przejdź tutaj.