Lenguaje de plantilla de tarjetas adaptables

La creación de plantillas permite separar los datos del diseño en la tarjeta adaptable. El lenguaje de plantilla es la sintaxis utilizada para crear una plantilla.

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}"

Vinculación de datos

Escribir una plantilla es tan simple como reemplazar el contenido "no estático" de la tarjeta por "expresiones de enlace".

Carga útil de tarjeta estática

{
   "type": "TextBlock",
   "text": "Matt"
}

Carga de plantilla

{
   "type": "TextBlock",
   "text": "${firstName}"
}

• Las expresiones de enlace se pueden colocar casi en cualquier lugar donde se pueda colocar contenido estático.
• La sintaxis de enlace comienza con ${ y termina con }. Por ejemplo, ${myProperty}
• Use dot-notation para tener acceso a los subobjetos de una jerarquía de objetos. Por ejemplo, ${myParent.myChild}
• El manejo elegante de null garantiza que no obtendrá excepciones si accede a una propiedad null en un grafo de objetos.
• Use la sintaxis de Indexer para recuperar propiedades por clave o elementos de una matriz. Por ejemplo, ${myArray[0]}

Proporcionar los datos

Ahora que tiene una plantilla, querrá proporcionar los datos con los que completarla. Tiene dos opciones para hacerlo:

1. Opción A: Insertada dentro de la carga de la plantilla. Puede proporcionar los datos directamente dentro de la carga útil de la plantilla AdaptiveCard. Para ello, basta con agregar un $data atributo al objeto raíz AdaptiveCard .
2. Opción B: como un objeto de datos independiente. Con esta opción se proporcionan dos objetos independientes al SDK de plantillas en tiempo de ejecución: el template y el data. Este será el enfoque más común, ya que normalmente creará una plantilla y querrá proporcionar datos dinámicos más adelante.

Opción A: Datos en línea

{
    "type": "AdaptiveCard",
    "$data": {
        "employee": {
            "name": "Matt",
            "manager": { "name": "Thomas" },
            "peers": [{
                "name": "Andrew" 
            }, { 
                "name": "Lei"
            }, { 
                "name": "Mary Anne"
            }, { 
                "name": "Adam"
            }]
        }
    },
    "body": [
        {
            "type": "TextBlock",
            "text": "Hi ${employee.name}! Here's a bit about your org..."
        },
        {
            "type": "TextBlock",
            "text": "Your manager is: ${employee.manager.name}"
        },
        {
            "type": "TextBlock",
            "text": "3 of your peers are: ${employee.peers[0].name}, ${employee.peers[1].name}, ${employee.peers[2].name}"
        }
    ]
}

Opción B: Separar la plantilla de los datos

Como alternativa (y más probable), creará una plantilla de tarjeta que se puede volver a usar sin incluir los datos. Esta plantilla se puede almacenar como un archivo y agregarse al control de código fuente.

EmployeeCardTemplate.json

{
    "type": "AdaptiveCard",
    "body": [
        {
            "type": "TextBlock",
            "text": "Hi ${employee.name}! Here's a bit about your org..."
        },
        {
            "type": "TextBlock",
            "text": "Your manager is: ${employee.manager.name}"
        },
        {
            "type": "TextBlock",
            "text": "3 of your peers are: ${employee.peers[0].name}, ${employee.peers[1].name}, ${employee.peers[2].name}"
        }
    ]
}

A continuación, cárguelos y proporcione los datos en tiempo de ejecución mediante los SDKs de plantillas.

Ejemplo de JavaScript

Uso del paquete adaptivecards-templating .

var template = new ACData.Template({ 
    // EmployeeCardTemplate goes here
});

// Specify data at runtime
var card = template.expand({
    $root: {
        "employee": {
            "name": "Matt",
            "manager": { "name": "Thomas" },
            "peers": [{
                "name": "Andrew" 
            }, { 
                "name": "Lei"
            }, { 
                "name": "Mary Anne"
            }, { 
                "name": "Adam"
            }]
        }
    }
});

// Now you have an AdaptiveCard ready to render!

Soporte para el diseñador

El Diseñador de tarjetas adaptables se ha actualizado para admitir plantillas.

Pruébelo en: https://adaptivecards.microsoft.com/designer

• Editor de datos de ejemplo: especifique los datos de muestra aquí para ver la tarjeta vinculada a datos en "Modo de vista previa". Hay un botón pequeño en este panel para completar la estructura de datos a partir de los datos de muestra existentes.
• Modo de vista previa : presione el botón de la barra de herramientas para alternar entre la experiencia de edición y la experiencia sample-data-preview.
• Abrir ejemplo : haga clic en este botón para abrir varias cargas de ejemplo.

Vinculación avanzada

Ámbitos de enlace

Hay algunas palabras clave reservadas para acceder a varios ámbitos de enlace.

{
    "${<property>}": "Implicitly binds to `$data.<property>`",
    "$data": "The current data object",
    "$root": "The root data object. Useful when iterating to escape to parent object",
    "$index": "The current index when iterating"
}

Asignación de un contexto de datos a elementos

Para asignar un "contexto de datos" a cualquier elemento, agregue un $data atributo al elemento .

{
    "type": "Container",
    "$data": "${mySubObject}",
    "items": [
        {
            "type": "TextBlock",
            "text": "This TextBlock is now scoped directly to 'mySubObject': ${mySubObjectProperty}"
        },
        {
            "type": "TextBlock",
            "text": "To break-out and access the root data, use: ${$root}"
        }
    ]
}

Repetición de elementos en una matriz

• Si la propiedad de un elemento de tarjeta adaptable está enlazada a una matriz, entonces el propio elemento se repetirá para cada elemento de la matriz.
• Las expresiones de enlace (${myProperty}) usadas en los valores de propiedad se limitarán al elemento individual dentro de la matriz.
• Si se enlaza a una matriz de cadenas, use ${$data} para acceder al elemento de cadena individual. Por ejemplo, "text": "${$data}"

Por ejemplo, el TextBlock siguiente se repetirá 3 veces, ya que es $data una matriz. Observe cómo la text propiedad está enlazada a la name propiedad de un objeto individual dentro de la matriz.

{
    "type": "Container",
    "items": [
        {
            "type": "TextBlock",
            "$data": [
                { "name": "Matt" }, 
                { "name": "David" }, 
                { "name": "Thomas" }
            ],
            "text": "${name}"
        }
    ]
}

Lo que da como resultado:

{
    "type": "Container",
    "items": [ 
        {
            "type": "TextBlock",
            "text": "Matt"
        },
        {
            "type": "TextBlock",
            "text": "David"
        }
        {
            "type": "TextBlock",
            "text": "Thomas"
        }
    ]
}

Funciones integradas

Ningún lenguaje de plantillas está completo sin un amplio conjunto de funciones auxiliares. Las plantillas de Tarjetas Adaptables están basadas en el lenguaje de Expresiones Adaptables (AEL), que es un estándar abierto para declarar expresiones que se pueden evaluar en muchas plataformas diferentes. Y es un superconjunto adecuado de "Logic Apps", por lo que puede usar una sintaxis similar a Power Automate, etc.

Se trata solo de un pequeño muestreo de las funciones integradas.

Consulte la lista completa de funciones precompiladas del lenguaje de expresiones adaptables.

Evaluación condicional

• if(expression, trueValue, falseValue)

if Ejemplo

{
    "type": "TextBlock",
    "color": "${if(priceChange >= 0, 'good', 'attention')}"
}

Análisis de JSON

• json(jsonString): análisis de una cadena JSON

json Ejemplo

Se trata de una respuesta de Azure DevOps donde la message propiedad es una cadena serializada por JSON. Para acceder a los valores dentro de la cadena, es necesario usar la json función en nuestra plantilla.

Datos

{
    "id": "1291525457129548",
    "status": 4,
    "author": "Matt Hidinger",
    "message": "{\"type\":\"Deployment\",\"buildId\":\"9542982\",\"releaseId\":\"129\",\"buildNumber\":\"20180504.3\",\"releaseName\":\"Release-104\",\"repoProvider\":\"GitHub\"}",
    "start_time": "2018-05-04T18:05:33.3087147Z",
    "end_time": "2018-05-04T18:05:33.3087147Z"
}

Uso

{
    "type": "TextBlock",
    "text": "${json(message).releaseName}"
}

Resultado en

{
    "type": "TextBlock",
    "text": "Release-104"
}

Funciones personalizadas

Las funciones personalizadas se admiten a través de api en los SDK de plantillas.

Diseño condicional con $when

Para quitar un elemento completo si se cumple una condición, use la $when propiedad . Si $when se evalúa como false el elemento no aparecerá al usuario.

{
    "type": "AdaptiveCard",
    "$data": {
        "price": "35"
    },
    "body": [
        {
            "type": "TextBlock",
            "$when": "${price > 30}",
            "text": "This thing is pricy!",
            "color": "attention",
        },
         {
            "type": "TextBlock",
            "$when": "${price <= 30}",
            "text": "Dang, this thing is cheap!",
            "color": "good"
        }
    ]
}

Creación de plantillas

Actualmente no hay compatibilidad para combinar los "elementos" de plantillas. Pero estamos explorando opciones y esperamos compartir más pronto. ¡Cualquier pensamiento aquí bienvenido!

Examples

Navega la página de muestras actualizada para explorar todo tipo de nuevas tarjetas con plantillas.