Kits SDK de création de modèles de cartes adaptatives

Article
08/28/2023

Les kits SDK de création de modèles de cartes adaptatives facilitent le remplissage d’un modèle de carte avec des données réelles sur n’importe quelle plateforme prise en charge.

Lisez la vue d’ensemble de la création de modèles de cartes adaptatives.

Important

Changements cassants dans la version RC (Release Candidate) de mai 2020

Nous avons travaillé dur à la publication des modèles et nous sommes dans la dernière ligne droite ! Nous avons dû apporter des modifications mineures avant de finaliser la version.

Changements cassants de mai 2020

La syntaxe de liaison a changé et passe de {...} à ${...}.
- Par exemple : "text": "Hello {name}" devient "text": "Hello ${name}"
L’API JavaScript ne contient plus d’objet EvaluationContext. Passez simplement vos données à la fonction expand. Consultez la page du SDK pour obtenir les détails complets.
L’API .NET a été reconçue pour correspondre davantage à l’API JavaScript. Vous trouverez des informations détaillées ci-dessous.

JavaScript

La bibliothèque adaptivecards-Templating est disponible sur npm et par le biais de CDN. Suivez le lien du package pour obtenir une documentation complète.

npm

npm install adaptivecards-templating

CDN

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

Utilisation

L’exemple ci-dessous part du principe que vous avez également installé la bibliothèque adaptivecards pour afficher la carte.

Si vous n’envisagez pas d’afficher la carte, vous pouvez supprimer le code parse et 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

Usage

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

Fonctions personnalisées

Les fonctions personnalisées peuvent être ajoutées à la bibliothèque d’expressions adaptatives, en plus des fonctions prédéfinies.

Dans l’exemple ci-dessous, la fonction personnalisée stringFormat est ajoutée, et elle est utilisée pour la mise en forme d’une chaîne.

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

Résolution des problèmes

Q. Pourquoi une exception AdaptiveTemplateException est-elle levée lorsque j’appelle expand() ?
A. Si votre message d’erreur ressemble à « <offending item>' at line, '<line number>' is malformed for '$data : ' pair » (<élément problématique> à la ligne est incorrect pour $data : pair).
Vérifiez que la valeur fournie pour « $data » correspond à du code JSON valide, tel qu’un nombre, une valeur booléenne, un objet ou un tableau, que la syntaxe est correcte pour le langage AEL, et que l’entrée existe dans le contexte de données au numéro de ligne indiqué.

Q. Pourquoi une exception ArgumentNullException est-elle levée lorsque j’appelle expand() ?
A. Si votre message d’erreur ressemble à « Check if parent data context is set, or please enter a non-null value for '<offending item>' at line, '<line number> » (Vérifiez si le contexte de données parent est défini ou entrez une valeur non nulle pour <élément problématique> à la ligne ).
Celui-ci indique qu’il n’existe aucun contexte de données pour la liaison de données demandée. Vérifiez que le contexte de données racine est défini, le cas échéant, et vérifiez qu’un contexte de données est disponible pour la liaison actuelle, comme indiqué par le numéro de ligne.

Q. Pourquoi le format de date/heure dans la RFC 3389, par ex. « 2017-02-14T06:08:00Z », ne fonctionne pas avec les fonctions TIME/DATE quand il est utilisé avec le modèle ?
A. Le SDK .NET nuget version 1.0.0-rc.0 expose ce comportement. Ce comportement est corrigé dans les prochaines mises en production. Le comportement par défaut du désérialiseur json.Net change la chaîne au format date/heure et est désactivé dans les prochaines mises en production. Utilisez la fonction formatDateTime() pour mettre en forme la chaîne date/heure dans la RFC 3389, comme montré dans cet exemple, ou vous pouvez contourner les fonctions TIME/DATE et utiliser juste formatDateTime(). Pour plus d’informations sur formatDateTime(), rendez-vous ici.

Partager via