Partager via

SDK de modélisation de cartes adaptatives

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

Lisez ceci pour une vue d’ensemble de la mise en forme des cartes adaptatives

Important

Changements cassants dans la version candidate de mai 2020

Nous avons travaillé dur pour lancer la modélisation, et nous sommes enfin dans la dernière ligne droite ! Nous avons dû apporter des modifications majeures qui peuvent entraîner des incompatibilités, alors que nous approchons de la sortie.

Changements majeurs depuis mai 2020

  1. La syntaxe de liaison est passée de {...} à ${...}.
    • Par exemple : "text": "Hello {name}" devient "text": "Hello ${name}"
  2. L’API JavaScript ne contient plus d’objet EvaluationContext . Transmettez simplement vos données à la expand fonction. Pour plus d’informations, consultez la page du Kit de développement logiciel (SDK ).
  3. L’API .NET a été repensée pour correspondre plus étroitement à l’API JavaScript. Pour plus d’informations, veuillez consulter les détails ci-dessous.

JavaScript

La bibliothèque de modèles de cartes adaptatives est disponible sur npm et via CDN. Consultez le lien du package pour obtenir une documentation complète.

npm

npm install 

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 de cartes adaptatives pour afficher la carte.

Si vous ne prévoyez 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

Installation de Nuget 

dotnet add package AdaptiveCards.Templating

Utilisation

// 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 l’fontion est utilisée pour mettre en forme 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 est-ce que je rencontre une AdaptiveTemplateException en appelant expand() ?
Un. Si votre message d’erreur ressemble à «< élément incriminé> » à la ligne, «< numéro> de ligne » est mal formé pour « $data : « paire ».
Assurez-vous que la valeur fournie pour « $data » est un json valide tel que nombre, booléen, objet et tableau, ou suit la syntaxe correcte pour le langage du modèle adaptatif, et l’entrée existe dans le contexte de données au niveau du numéro de ligne.

Q. Pourquoi est-ce que je rencontre une ArgumentNullException en appelant expand() ?
Un. Si votre message d’erreur ressemble à « Vérifiez si le contexte de données parent est défini ou entrez une valeur non nulle pour '<élément> incriminé' à la ligne, '<ligne numéro>'".
Il indique qu’il n’existe pas de contexte de données pour la liaison de données demandée. Assurez-vous que le contexte de données racine est défini, s’il existe, vérifiez que tout contexte de données est disponible pour la liaison actuelle, comme indiqué par le numéro de ligne.

Q. Pourquoi la date/heure au format RFC 3389, par exemple « 2017-02-14T06:08:00Z », lorsqu'elle est utilisée avec un modèle, ne fonctionne-t-elle pas avec les fonctions TEMPS/DATE ?
Un. Le sdk .NET nuget version 1.0.0-rc.0 présente ce comportement. ce comportement est corrigé dans les versions suivantes. Le comportement par défaut du désérialiseur json.Net modifie la chaîne de format de date/heure, et ce changement sera désactivé pour les versions futures. Utilisez la fonction formatDateTime() pour mettre en forme la chaîne de date/heure en RFC 3389 comme indiqué dans cet exemple, ou vous pouvez contourner les fonctions TIME/DATE et utiliser simplement formatDateTime(). Pour plus d’informations sur formatDateTime(), accédez ici.