Langage du modèle cartes adaptatives

La création de modèles permet de séparer les données de la disposition dans votre carte adaptative. Le langage de modèle est la syntaxe utilisée pour créer un modèle.

Lisez-le pour obtenir une vue d’ensemble de la modélisation de cartes adaptatives

Changements cassants depuis mai 2020

1. La syntaxe de liaison est passée de {...} à ${...}
   • Par exemple : "text": "Hello {name}" devient "text": "Hello ${name}"

Liaison à des données

L’écriture d’un modèle est aussi simple que le remplacement du contenu « non statique » de votre carte par des « expressions liantes ».

Charge utile de carte statique

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

Charge utile du modèle

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

• Les expressions de liaison peuvent être placées n’importe où le contenu statique peut l’être.
• La syntaxe de liaison commence par ${ et se termine par }. Par exemple : ${myProperty}
• Utilisez la notation dot pour accéder aux sous-objets d’une hiérarchie d’objets. Par exemple : ${myParent.myChild}
• La gestion normale des valeurs Null garantit que vous n’obtiendrez pas d’exceptions si vous accédez à une propriété Null dans un graphique d’objets
• Utilisez la syntaxe indexeur pour récupérer les propriétés par clé ou par éléments d’un tableau. Par exemple : ${myArray[0]}

Fourniture des données

Maintenant que vous disposez d’un modèle, vous devez fournir les données qui le rendent terminées. Vous avez deux options pour effectuer cette opération :

1. Option A : Intégré dans la charge utile du modèle. Vous pouvez fournir les données inline dans la charge utile du AdaptiveCard modèle. Pour ce faire, ajoutez simplement un $data attribut à l’objet racine AdaptiveCard .
2. Option B : en tant qu’objet de données distinct. Avec cette option, vous fournissez deux objets distincts au Kit de développement logiciel (SDK) Templating au moment de l’exécution : le template et le data. Il s’agit de l’approche la plus courante, car en général, vous allez créer un modèle et vous souhaitez fournir des données dynamiques ultérieurement.

Option A : Données inline

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

Option B : séparation du modèle des données

Vous allez également créer un modèle de carte réutilisable sans inclure les données. Ce modèle peut être stocké en tant que fichier et ajouté au contrôle de code source.

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

Chargez-le, puis fournissez les données en temps réel à l'aide des SDK de création de modèles.

Exemple JavaScript

Utilisation du package de création de modèles de cartes adaptatives .

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!

Assistance du concepteur

Le Concepteur de cartes adaptatives a été mis à jour pour prendre en charge la modélisation.

Essayez-le à l’adresse suivante : https://adaptivecards.microsoft.com/designer

• Exemple d’éditeur de données : spécifiez des exemples de données ici pour afficher la carte liée aux données quand vous utilisez « Mode aperçu ». Il existe un petit bouton dans ce volet pour remplir la structure de données à partir des exemples de données existants.
• Mode Aperçu : appuyez sur le bouton de barre d’outils pour basculer entre l’expérience d’édition et l’expérience sample-data-preview
• Ouvrir l’exemple : cliquez sur ce bouton pour ouvrir différents exemples de charges utiles

Liaison avancée

Étendues de liaison

Il existe quelques mots clés réservés pour accéder à différents contextes d'association.

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

Affectation d’un contexte de données à des éléments

Pour affecter un « contexte de données » à n’importe quel élément, ajoutez un $data attribut à l’élément.

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

Répétition d’éléments dans un tableau

• Si la propriété d’un $data élément Carte adaptative est liée à un tableau, l’élément lui-même est répété pour chaque élément du tableau.
• Toutes les expressions de liaison (${myProperty}) utilisées dans les valeurs de propriété sont limitées à l’élément individuel dans le tableau.
• Si vous liez à un tableau de chaînes, utilisez ${$data} pour accéder à chaque élément de chaîne individuel. Par exemple : "text": "${$data}"

Par exemple, la TextBlock valeur ci-dessous est répétée 3 fois, car il s’agit $data d’un tableau. Notez comment la text propriété est liée à la name propriété d’un objet individuel dans le tableau.

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

Résultat :

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

Fonctions intégrées

Aucun langage de création de modèles n’est complet sans une suite riche de fonctions d’assistance. La création de modèles de carte adaptative est basée sur le langage AEL (Adaptive Expression Language ), qui est une norme ouverte pour déclarer des expressions qui peuvent être évaluées sur de nombreuses plateformes différentes. Il s’agit d’un super-ensemble approprié de « Logic Apps », ce qui vous permet d’utiliser une syntaxe similaire à Power Automate, etc.

Il s’agit simplement d’un petit échantillonnage des fonctions intégrées.

Consultez la liste complète des fonctions prédéfinies du langage d’expression adaptative.

Évaluation conditionnelle

• if(expression, trueValue, falseValue)

if Exemple

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

Analyse syntaxique de JSON

• json(jsonString) - Analyser une chaîne JSON

json Exemple

Il s’agit d’une réponse Azure DevOps où la message propriété est une chaîne sérialisée JSON. Pour accéder aux valeurs dans la chaîne, nous devons utiliser la json fonction dans notre modèle.

Données

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

Utilisation

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

Résultat

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

Fonctions personnalisées

Les fonctions personnalisées sont prises en charge via des API dans les SDK de création de modèles.

Disposition conditionnelle avec $when

Pour supprimer un élément entier si une condition est remplie, utilisez la $when propriété. Si la condition $when est vraie pour false, l’élément n’apparaîtra pas à l’utilisateur.

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

Composition de modèles

Actuellement, il n’existe aucune prise en charge de l’assemblage des « parties » de modèles. Mais nous explorons des options et espérons partager plus rapidement. Vos idées sont les bienvenues ici !

Examples

Parcourez la page Exemples mise à jour pour explorer toutes sortes de nouvelles cartes modèles.