Vorlagen-SDKs für adaptive Karten

Artikel
08/28/2023

Die Vorlagen-SDKs für adaptive Karten vereinfachen das Auffüllen einer Kartenvorlage mit echten Daten auf unterstützten Plattformen.

Hier finden Sie einen Überblick über Vorlagen für adaptive Karten.

Wichtig

Breaking Changes im Release Candidate von Mai 2020

Wir haben hart an der Veröffentlichung der Vorlagen gearbeitet, und endlich sind wir auf der Zielgeraden. Wir mussten kurz vor der Veröffentlichung einige geringfügige, nicht abwärtskompatible Änderungen vornehmen.

Breaking Changes Stand Mai 2020

Die Bindungssyntax wurde von {...} in ${...} geändert.
- Beispiel: Aus "text": "Hello {name}" wird "text": "Hello ${name}".
Die JavaScript-API enthält kein EvaluationContext-Objekt mehr. Übergeben Sie Ihre Daten einfach an die expand-Funktion. Ausführliche Informationen finden Sie auf der SDK-Seite.
Die .NET-API wurde umgestaltet, damit sie der JavaScript-API besser entspricht. Nachfolgend finden Sie ausführliche Informationen.

JavaScript

Die adaptivecards-templating-Bibliothek ist auf npm und über das CDN verfügbar. Die vollständige Dokumentation finden Sie unter dem Paketlink.

npm

npm install adaptivecards-templating

CDN

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

Usage

Im folgenden Beispiel wird davon ausgegangen, dass Sie auch die adaptivecards-Bibliothek installiert haben, um die Karte zu rendern.

Wenn Sie nicht beabsichtigen, die Karte zu rendern, können Sie den parse- und render-Code entfernen.

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

Verwendung

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

Benutzerdefinierte Funktionen

Zusätzlich zu den vordefinierten Funktionen können der Adaptive Expression Library benutzerdefinierte Funktionen hinzugefügt werden.

Im Beispiel unten wird die benutzerdefinierte Funktion stringFormat hinzugefügt, und die Funktion wird zum Formatieren einer Zeichenfolge verwendet.

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

Problembehandlung

F. Warum wird beim Aufrufen von expand() eine AdaptiveTemplateException ausgelöst?
A. Ihre Fehlermeldung weist die Form '<fehlerhaftes Element>' in Zeile '<Zeilennummer>' hat ein falsches Format für das '$data : '-Paar" auf.
Stellen Sie sicher, dass es sich bei dem für "$data" übergebenen Wert um ein gültiges JSON-Element handelt, wie etwa eine Zahl, einen booleschen Wert, ein Objekt oder ein Array, die richtige Syntax für die Adaptive Template-Sprache eingehalten wird und der Eintrag im Datenkontext an der Zeilennummer vorhanden ist.

F. Warum wird beim Aufrufen von expand() eine ArgumentNullException ausgelöst?
A. Ihre Fehlermeldung weist die Form "Überprüfen Sie, ob der übergeordnete Datenkontext festgelegt ist, oder geben Sie einen Wert ungleich Null für '<fehlerhaftes Element>' in Zeile '<Zeilennummer>' ein" auf.
Dies weist darauf hin, dass für die angeforderte Datenbindung kein Datenkontext vorhanden ist. Stellen Sie sicher, dass der Stammdatenkontext festgelegt ist, sofern vorhanden, und stellen Sie sicher, dass für die aktuelle Bindung, die durch die Zeilennummer angegeben ist, ein Datenkontext vorhanden ist.

F. Warum funktionieren Datum-/Uhrzeitangaben im RFC 3389-Format, z. B. „2017-02-14T06:08:00Z“ in Kombination mit der Vorlage nicht mit TIME/DATE-Funktionen?
A. Dieses Verhalten zeigt sich in der .NET SDK-NuGet-Version 1.0.0-rc.0. Dieses Verhalten wurde in den nachfolgenden Versionen korrigiert. Das Standardverhalten des JSON.Net-Deserialisierers ändert die Formatzeichenfolge für Datum/Uhrzeit, es wurde in den nachfolgenden Versionen deaktiviert. Verwenden Sie die Funktion „formatDateTime()“, um Datums-/Uhrzeitzeichenfolgen gemäß RFC 3389 zu formatieren, wie in diesem Beispiel zu sehen. Alternativ können Sie TIME/DATE-Funktionen umgehen und einfach „formatDateTime()“ verwenden. Weitere Informationen zu „formatDateTime ()“ finden Sie hier.

Freigeben über