SDK de plantillas de tarjetas adaptables

Los SDK de plantillas de tarjetas adaptables facilitan la rellenación de una plantilla de tarjeta con datos reales en cualquier plataforma compatible.

Lea esta información para obtener información general sobre plantillas de tarjetas adaptables.

Cambios importantes a partir de mayo de 2020

1. La sintaxis de enlace ha cambiado de {...} a ${...}.
   • Por ejemplo: "text": "Hello {name}" se convierte en "text": "Hello ${name}"
2. La API de JavaScript ya no contiene un EvaluationContext objeto . Simplemente pase los datos a la expand función. Consulte la página del SDK para obtener más información.
3. La API de .NET se ha rediseñado para que coincida más estrechamente con la API de JavaScript. A continuación encontrará los detalles completos.

JavaScript

La biblioteca adaptivecards-templating está disponible en npm y a través de CDN. Consulte el vínculo del paquete para obtener documentación completa.

npm

npm install adaptivecards-templating

CDN

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

Uso

En el ejemplo siguiente se supone que también ha instalado la biblioteca adaptivecards para representar la tarjeta.

Si no piensa en renderizar la tarjeta, puede quitar el código parse y 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

Uso

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

Funciones personalizadas

Las funciones personalizadas se pueden agregar a la biblioteca de expresiones adaptables además de las funciones precompiladas.

En el ejemplo siguiente, se agrega la función personalizada stringFormat y la función se usa para dar formato a una cadena.

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

Solución de problemas

P. ¿Por qué estoy ejecutando una llamada expand()adaptiveTemplateException?
A. Si su mensaje de error se parece a "<elemento infractor>" en la línea "<número de línea>", tiene un formato incorrecto para el par "$data : "".
Asegúrese de que el valor proporcionado para "$data" sea json válido, como number, boolean, object y array, o siga la sintaxis correcta para el lenguaje de plantilla adaptable y la entrada exista en el contexto de datos en el número de línea.

P. ¿Por qué al llamar a expand() recibo una ArgumentNullException?
A. Si el mensaje de error es similar a " Compruebe si se ha establecido el contexto de datos primario o escriba un valor distinto de NULL para "<elemento> infractor" en la línea, "<número> de línea".
Indica que no existe el contexto de datos para el enlace de datos solicitado. Asegúrese de que se establece el contexto de datos raíz, si existe, asegúrese de que cualquier contexto de datos esté disponible para el enlace actual, tal como se indica en el número de línea.

P. ¿Por qué la fecha y hora en formato RFC 3389, por ejemplo, "2017-02-14T06:08:00Z" cuando se usa con la plantilla no funciona con funciones TIME/DATE?
A. La versión 1.0.0-rc.0 del sdk de .NET muestra este comportamiento. este comportamiento se corrige en las versiones posteriores. El comportamiento predeterminado del deserializador de json.Net cambia la cadena de formato de fecha y hora, y este comportamiento se deshabilitará en las versiones posteriores. Use la función formatDateTime() para dar formato a la cadena de fecha y hora a RFC 3389 como se muestra en este ejemplo, o bien puede omitir las funciones TIME/DATE y simplemente usar formatDateTime(). Para obtener más información sobre formatDateTime(), vaya aquí.