Jazyk šablon pro adaptivní karty

Šablonování umožňuje oddělení dat od rozložení na adaptivní kartě. Jazyk šablony je syntaxe použitá k vytvoření šablony.

Přečtěte si toto pro přehled adaptivních šablon karty.

Důležité

Změny narušující kompatibilitu ve verzi Release Candidate z května 2020

Tvrdě jsme pracovali na uvedení šablon a jsme konečně ve finální fázi! Museli jsme provést několik menších zásadních změn, jakmile se blížíme k vydání.

Zásadní změny k květnu 2020

Syntaxe vazby se změnila z {...} na ${...}
- Příklad: "text": "Hello {name}" se stane "text": "Hello ${name}"

Vazba na data

Zápis šablony je stejně jednoduchý jako nahrazení "nestatického" obsahu karty výrazy vazby.

Datová část statické karty

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

Datová část šablony

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

Vazbové výrazy lze umístit prakticky kdekoli, kde může být statický obsah.
Syntaxe vazby začíná ${ a končí na }. Například ${myProperty}
Použijte tečkovou notaci pro přístup k dílčím objektům v hierarchii objektů. Například ${myParent.myChild}
Elegantní zacházení s hodnotami null zajišťuje, že nedojde k výjimkám, pokud v objektovém grafu přistupujete k nulové vlastnosti.
Pomocí syntaxe indexeru můžete načíst vlastnosti podle klíčů nebo položek v poli. Například ${myArray[0]}

Poskytnutí dat

Teď, když máte šablonu, budete chtít poskytnout data, která ji doplní. Máte dvě možnosti, jak to udělat:

Možnost A: Vložená v datové části šablony. Data můžete zadat přímo v rámci části šablony AdaptiveCard. Uděláte to jednoduše tak, že do kořenového $data objektu přidáte AdaptiveCard atribut.
Možnost B: Jako samostatný datový objekt Pomocí této možnosti poskytnete za běhu dva samostatné objekty šablonovací sadě SDK: objekty template a data. To bude častější přístup, protože obvykle vytvoříte šablonu a budete chtít později poskytnout dynamická data.

Možnost A: Inline data

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

Možnost B: Oddělení šablony od dat

Alternativně (a pravděpodobnější) vytvoříte opakovaně použitelnou šablonu karty bez zahrnutí dat. Tato šablona může být uložena jako soubor a přidána do správy zdrojového kódu.

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

Nejprve je načtěte a pak poskytněte data za běhu pomocí Templating SDK.

Příklad JavaScriptu

Použití balíčku 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!

Podpora návrháře

Návrhář adaptivních karet byl aktualizován tak, aby podporoval šablonování.

Vyzkoušejte si to na adrese: https://adaptivecards.microsoft.com/designer

Ukázkový editor dat – Sem zadejte ukázková data, aby se v režimu náhledu zobrazila karta vázaná na data. V tomto podokně je malé tlačítko pro naplnění datové struktury z existujících ukázkových dat.
Režim náhledu – Stisknutím tlačítka panelu nástrojů můžete přepínat mezi prostředím pro úpravy a prostředím náhledu ukázkových dat.
Otevřít ukázku – kliknutím na toto tlačítko otevřete různé ukázkové datové části.

Pokročilá vazba

Rozsahy vazeb

Pro přístup k různým oborům vazeb existuje několik rezervovaných klíčových slov.

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

Přiřazení kontextu dat k prvkům

Chcete-li přiřadit "kontext dat" libovolnému prvku, přidejte $data atribut do elementu.

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

Opakující se položky v poli

Pokud je vlastnost prvku $data adaptivní karty svázaná s polem, samotný prvek se bude opakovat pro každou položku v poli.
Všechny vazbové výrazy (${myProperty}) použité v hodnotách vlastností budou vymezeny na jednotlivé položky v rámci pole.
Pokud je vazba na pole řetězců, použijte ${$data} pro přístup k jednotlivým řetězcovým elementům. Například "text": "${$data}"

Následující TextBlock se opakuje 3krát, protože $data je pole. Všimněte si, jak text je vlastnost vázána na name vlastnost jednotlivého objektu v rámci pole.

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

Výsledkem je:

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

Integrované funkce

Bez bohaté sady pomocných funkcí není dokončen žádný jazyk šablon. Adaptivní šablonování karet je postavené na jazyce AEL ( Adaptive Expression Language ), což je otevřený standard pro deklarování výrazů, které je možné vyhodnotit na mnoha různých platformách. A je to správná nadmnožina "Logic Apps", takže můžete použít podobnou syntaxi jako Power Automate atd.

Toto je jen malý vzorek vestavěných funkcí.

Podívejte se na úplný seznam předdefinovaných funkcí jazyka Adaptivní výraz.

Podmíněné vyhodnocení

if(expression; trueValue; falseValue)

if Příklad

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

Analýza JSON

json(jsonString) – Parsování řetězce JSON

json Příklad

Jedná se o odpověď Azure DevOps, ve které je vlastnost message serializována jako řetězec JSON. Abychom mohli přistupovat k hodnotám v řetězci, musíme použít json funkci v naší šabloně.

Data

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

Využití

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

Výsledkem je

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

Vlastní funkce

Podpora vlastních funkcí je zajištěna prostřednictvím rozhraní API v šablonovacích SDK.

Podmíněné rozložení s využitím `$when`

Chcete-li odstranit celý prvek, pokud je splněna podmínka, použijte $when vlastnost. Pokud se $when vyhodnotí jako false, prvek se uživateli nezobrazí.

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

Vytváření šablon

V současné době neexistuje podpora pro společné vytváření "částí" šablony. Ale zkoumáme možnosti a doufáme, že se brzy podělíme o něco víc. Všechny myšlenky zde vítejte!

Examples

Projděte si aktualizovanou stránku Ukázky a prozkoumejte nejrůznější nové šablonované karty.

Last updated on 2025-12-18

Sdílet prostřednictvím