Kits SDK de création de modèles de cartes adaptativesAdaptive Card Templating SDKs

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.The Adaptive Card Templating SDKs make it easy to populate a card template with real data on any supported platform.

Lisez la vue d’ensemble de la création de modèles de cartes adaptatives.Please read this for an overview of Adaptive Card Templating

Important

Changements cassants dans la version RC (Release Candidate) de mai 2020Breaking changes in the May 2020 Release Candidate

Nous avons travaillé dur à la publication des modèles et nous sommes dans la dernière ligne droite !We've been hard at work getting templating released, and we're finally in the home stretch! Nous avons dû apporter des modifications mineures avant de finaliser la version.We had to make some minor breaking changes as we close on the release.

Changements cassants de mai 2020Breaking changes as of May 2020

  1. La syntaxe de liaison a changé et passe de {...} à ${...}.The binding syntax changed from {...} to ${...}.
    • Par exemple : "text": "Hello {name}" devient "text": "Hello ${name}"For Example: "text": "Hello {name}" becomes "text": "Hello ${name}"
  2. L’API JavaScript ne contient plus d’objet EvaluationContext.The JavaScript API no longer contains an EvaluationContext object. Passez simplement vos données à la fonction expand.Simply pass your data to the expand function. Consultez la page du SDK pour obtenir les détails complets.Please see the SDK page for full details.
  3. L’API .NET a été reconçue pour correspondre davantage à l’API JavaScript.The .NET API was redesigned to more closely match the JavaScript API. Vous trouverez des informations détaillées ci-dessous.Please below for full details.

JavaScriptJavaScript

La bibliothèque adaptivecards-Templating est disponible sur npm et par le biais de CDN.The adaptivecards-templating library is available on npm and via CDN. Suivez le lien du package pour obtenir une documentation complète.See the package link for full documentation.

npmnpm

Installation npmnpm install

npm install adaptivecards-templating

CDNCDN

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

UtilisationUsage

L’exemple ci-dessous part du principe que vous avez également installé la bibliothèque adaptivecards pour afficher la carte.The sample below assumes you've also installed the adaptivecards library in order to render the card.

Si vous n’envisagez pas d’afficher la carte, vous pouvez supprimer le code parse et render.If you don't plan on rendering the card then you can remove the parse and render code.

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.NET

Important

La version Release Candidate de .NET sera disponible vers le 23 mai.The .NET Release Candidate will be available around 05/23. Recherchez la version 1.0.0-RC1.Look for version 1.0.0-RC1

Installation NuGetNuget install

dotnet add package AdaptiveCards.Templating

UtilisationUsage

// 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éesCustom Functions

Les fonctions personnalisées peuvent être ajoutées à la bibliothèque d’expressions adaptatives, en plus des fonctions prédéfinies.Custom functions can be added to Adaptive Expression Library in addition to the prebuilt functions.

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.In the below example, stringFormat custom function is added, and the funtion is used to format a string.

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èmesTroubleshooting

Q.Q. Pourquoi une exception AdaptiveTemplateException est-elle levée lorsque j’appelle expand() ?Why am I running into an AdaptiveTemplateException calling expand()?
A.A. Si votre message d’erreur ressemble à « '<offending item>' à la ligne '<line number>' est mal formé pour '$data : ' pair ».If your error message looks like '<offending item>' at line, '<line number>' is malformed for '$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é.Please ensure that value provided for "$data" is valid json such as number, boolean, object, and array, or follows correct syntax for Adaptive Template language, and the entry exists in the data context at the line number.

Q.Q. Pourquoi une exception ArgumentNullException est-elle levée lorsque j’appelle expand() ?Why am I running into an ArgumentNullException calling expand()?
A.A. 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 '<offending item>' à la ligne '<line number>' ».If your error message looks like" Check if parent data context is set, or please enter a non-null value for '<offending item>' at line, '<line number>'".
Celui-ci indique qu’il n’existe aucun contexte de données pour la liaison de données demandée.It indicates that there doesn't exist data context for the requested data binding. 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.Please ensure that root data context is set, if exists, ensure that any data context is available for current binding as indicated by the line number.

Q.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 ?Why date/time in RFC 3389 format e.g "2017-02-14T06:08:00Z" when used with template doesn't works with TIME/DATE functions?
A.A. Le SDK .NET nuget version 1.0.0-rc.0 expose ce comportement..NET sdk nuget version 1.0.0-rc.0 exhibits this behavior. Ce comportement est corrigé dans les prochaines mises en production.this behavior is corrected in the subsequent releases. 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.json.Net deserilizer's default behavior changes date/time format string, and it's disabled for the subsequent releases. 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().Please use formatDateTime() function to format the date/time string to RFC 3389 as seen in this example, or you can bypass TIME/DATE functions, and just use formatDateTime(). Pour plus d’informations sur formatDateTime(), rendez-vous ici.For more information on formatDateTime(), please go here.