SDKs de Modelagem de Cartão Adaptável

Artigo
08/28/2023

Os SDKs de Modelagem de Cartão Adaptável tornam mais fácil popular um modelo de cartão com os dados reais em qualquer plataforma compatível.

Leia a Visão geral da Modelagem de Cartão Adaptável

Importante

Alterações da falha na versão Release Candidate de maio de 2020

Temos trabalhado duro para lançar a modelagem e, por fim, estamos na reta final. Com a proximidade do lançamento, tivemos que fazer algumas pequenas alterações da falha.

Alterações da falha a partir de maio de 2020

A sintaxe de associação foi alterada de {...} para ${...}.
- Por exemplo: "text": "Hello {name}" se torna "text": "Hello ${name}"
A API JavaScript não contém mais um objeto EvaluationContext. Passe com facilidade seus dados para a função expand. Confira a Página de SDKs para obter todos os detalhes.
A API .NET foi reprojetada para adequar-se melhor à API JavaScript. Consulte as informações abaixo para obter todos os detalhes.

JavaScript

A biblioteca adaptivecards-templating está disponível em npm e por meio da CDN. Confira o link do pacote para obter a documentação completa.

npm

npm install adaptivecards-templating

CDN

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

Uso

O exemplo a seguir pressupõe que você também instalou a biblioteca adaptivecards para renderizar o cartão.

Se você não planeja renderizar o cartão, pode remover os códigos parse e 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);

Funções personalizadas

Além das funções predefinidas, as funções personalizadas podem ser adicionadas à biblioteca de expressões adaptáveis.

No exemplo abaixo, é adicionada a função personalizada stringFormat, que é usada para formatar uma cadeia de caracteres.

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

Solução de problemas

P. Por que aparece um AdaptiveTemplateException ao chamar expand()?
A. Se a mensagem de erro é parecida com "O '<item incorreto>' na linha '<número de linha>' está malformado devido a '$data : ' pair".
Verifique se o valor fornecido para "$data" é um JSON válido, como um número, um booliano, um objeto e uma matriz, ou segue a sintaxe correta para a linguagem do Modelo Adaptável. Além disso, confirme se a entrada existe no contexto de dados no número de linha.

P. Por que aparece um ArgumentNullException ao chamar expand()?
A. Se a mensagem de erro é parecida com "Verifique se o contexto de dados pai está definido ou insira um valor não nulo para o '<item incorreto>' na linha '<número de linha>'".
Isso indica que não existe contexto de dados para a associação de dados solicitada. Verifique se o contexto de dados raiz está definido. Se ele existir, confirme se algum contexto de dados está disponível para a associação atual, conforme indicado pelo número de linha.

P. Por que data/hora no formato RFC 3389, por exemplo, "2017-02-14T06:08:00Z", quando usado com o modelo não funciona com funções TIME/DATE?
A. O NuGet do SDK do .NET versão 1.0.0-rc.0 exibe esse comportamento. Esse comportamento é corrigido nas versões subsequentes. O comportamento padrão do desserializador de json.net altera a cadeia de caracteres de formato data/hora e está desabilitado para as versões subsequentes. Use a função formatDateTime() para formatar a cadeia de caracteres de data/hora para RFC 3389, conforme visto neste exemplo ou você pode ignorar funções TIME/DATE e usar apenas formatDateTime(). Para obter mais informações sobre formatDateTime(), acesse este artigo.

Partilhar via