Delen via

Sjabloontaal voor adaptieve kaarten

Met templating kunt u gegevens scheiden van de indeling in uw adaptieve kaart. De sjabloontaal is de syntaxis die wordt gebruikt om een sjabloon te maken.

Lees dit voor een overzicht van Adaptieve Kaart-sjablonering

Belangrijk

Belangrijke wijzigingen in de releasekandidaat van mei 2020

We zijn hard aan het werk geweest om sjablonen vrij te geven, en we zijn eindelijk in de laatste fase! We moesten enkele kleine incompatibele wijzigingen aanbrengen naarmate we de release naderden.

Belangrijke wijzigingen vanaf mei 2020

  1. De bindingsyntaxis is gewijzigd van {...} in ${...}
    • Bijvoorbeeld: "text": "Hello {name}" wordt "text": "Hello ${name}"

Binding met gegevens

Het schrijven van een sjabloon is net zo eenvoudig als het vervangen van de 'niet-statische' inhoud van uw kaart door 'bindingexpressies'.

Statische kaartbelading

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

Nettolading van sjabloon

{
   "type": "TextBlock",
   "text": "${firstName}"
}
  • Bindingexpressies kunnen ongeveer overal worden geplaatst waar statische inhoud kan zijn
  • De syntaxis van de binding begint met ${ en eindigt met }. Bijvoorbeeld ${myProperty}
  • Gebruik punt-notatie om toegang te krijgen tot subobjecten van een objecthiërarchie. Bijvoorbeeld ${myParent.myChild}
  • Graceful null-afhandeling zorgt ervoor dat u geen uitzonderingen krijgt als u toegang krijgt tot een null-eigenschap in een objectdiagram.
  • Gebruik de syntaxis van de indexeerfunctie om eigenschappen op te halen op basis van sleutel of items in een matrix. Bijvoorbeeld ${myArray[0]}

Het verstrekken van de gegevens

Nu u een sjabloon hebt, wilt u de gegevens opgeven die het compleet maken. U hebt twee opties om dit te doen:

  1. Optie A: Inline binnen de payload van de sjabloon. U kunt de gegevens inline opgeven binnen de payload van de AdaptiveCard sjabloon. Hiervoor voegt u gewoon een $data kenmerk toe aan het hoofdobject AdaptiveCard .
  2. Optie B: Als afzonderlijk gegevensobject. Met deze optie geeft u tijdens runtime twee afzonderlijke objecten op voor de Templating SDK : de template en de data. Dit is de meest voorkomende benadering, omdat u doorgaans een sjabloon maakt en later dynamische gegevens wilt opgeven.

Optie A: Inline-gegevens

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

Optie B: De sjabloon scheiden van de gegevens

U zult waarschijnlijk (en mogelijkerwijs) een herbruikbare kaartsjabloon maken zonder de gegevens op te nemen. Deze sjabloon kan worden opgeslagen als een bestand en toegevoegd aan broncodebeheer.

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

Laad deze vervolgens en geef de gegevens tijdens runtime op met behulp van de Templating SDK's.

Voorbeeld van JavaScript

Het adaptivecards-templating-pakket gebruiken.

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!

Ondersteuning voor designer

De adaptieve kaartontwerper is bijgewerkt ter ondersteuning van sjablonen.

Probeer het uit op: https://adaptivecards.microsoft.com/designer

Afbeelding

  • Voorbeeldgegevenseditor : geef hier voorbeeldgegevens op om de gegevensgebonden kaart weer te geven in de preview-modus. Er is een kleine knop in dit deelvenster om de gegevensstructuur van de bestaande voorbeeldgegevens te vullen.
  • Preview-modus : druk op de werkbalkknop om te schakelen tussen de bewerkingservaring en de voorbeeld-gegevens-preview-ervaring
  • Voorbeeld openen - klik op deze knop om verschillende voorbeeldpayloads te openen

Geavanceerde binding

Bindingsgebieden

Er zijn enkele gereserveerde trefwoorden voor toegang tot verschillende bindingsbereiken.

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

Een gegevenscontext toewijzen aan elementen

Als u een 'gegevenscontext' wilt toewijzen aan een element, voegt u een $data kenmerk toe aan het element.

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

Herhalende items in een matrix

  • Als de eigenschap van $data een adaptief kaartelement is gebonden aan een matrix, wordt het element zelf herhaald voor elk item in de matrix.
  • Bindingexpressies (${myProperty}) die in eigenschapswaarden worden gebruikt, zijn van toepassing op het afzonderlijke item binnen de array.
  • Als u een stringarray wilt gebruiken, gebruik dan ${$data} om toegang te krijgen tot het afzonderlijke stringelement. Bijvoorbeeld "text": "${$data}"

Het onderstaande TextBlock wordt bijvoorbeeld drie keer herhaald omdat $data een array is. U ziet hoe de text eigenschap is gebonden aan de name eigenschap van een afzonderlijk object in de matrix.

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

Resulteert in:

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

Ingebouwde functies

Er is geen sjabloontaal zonder een uitgebreide suite helperfuncties. Adaptieve kaart-sjablonering is gebaseerd op de Adaptive Expression Language (AEL), een open standaard voor het declareren van expressies die op veel verschillende platforms kunnen worden geëvalueerd. En het is een juiste superset van 'Logic Apps', zodat u vergelijkbare syntaxis kunt gebruiken als Power Automate, enzovoort.

Dit is slechts een kleine steekproef van de ingebouwde functies.

Bekijk de volledige lijst met vooraf gebouwde functies voor adaptieve expressietaal.

Voorwaardelijke evaluatie

  • als(expressie, trueValue, falseValue)

if Voorbeeld

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

JSON parseren

  • json(jsonString) - Een JSON-tekenreeks parseren

json Voorbeeld

Dit is een Azure DevOps-antwoord waarbij de message eigenschap een door JSON geserialiseerde tekenreeks is. Om toegang te krijgen tot waarden in de tekenreeks, moeten we de json functie in onze sjabloon gebruiken.

Gegevens

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

Gebruik

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

Resulteert in

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

Aangepaste functies

Aangepaste functies worden ondersteund via API's in de Templating SDK's.

Voorwaardelijke indeling met $when

Als u een volledig element wilt verwijderen als aan een voorwaarde wordt voldaan, gebruikt u de $when eigenschap. Als $when evalueert naar false, wordt het element niet aan de gebruiker getoond.

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

Sjablonen opstellen

Momenteel is er geen ondersteuning voor het samenstellen van sjabloononderdelen. Maar we verkennen opties en hopen binnenkort meer te delen. Alle gedachten hier welkom!

Voorbeelden

Blader door de bijgewerkte pagina Voorbeelden om allerlei nieuwe sjabloonkaarten te verkennen.

  • Last updated on