Bahasa Templat Kartu Adaptif

Templat memungkinkan pemisahan data dari tata letak di Kartu Adaptif Anda. Bahasa templat adalah sintaks yang digunakan untuk menulis templat.

Silakan baca ini untuk gambaran umum Templat Kartu Adaptif

Penting

Perubahan yang signifikan dalam Kandidat Rilis Mei 2020

Kami telah bekerja keras untuk peluncuran templat, dan akhirnya kami berada di tahap akhir! Kami harus membuat beberapa perubahan kecil saat kami menutup rilis.

Perubahan mencolok per Mei 2020

Sintaks pengikatan diubah dari {...} ke ${...}
- Misalnya: "text": "Hello {name}" menjadi "text": "Hello ${name}"

Pengikatan ke data

Menulis templat sesederhana mengganti konten "non-statis" kartu Anda dengan "ekspresi pengikatan".

Payload kartu statis

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

Payload templat

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

Ekspresi pengikatan dapat ditempatkan hampir di mana saja konten statis dapat ditempatkan.
Sintaks pengikatan dimulai dengan ${ dan diakhir dengan }. Misalnya, ${myProperty}
Gunakan Dot-notation untuk mengakses sub-objek hierarki objek. Misalnya, ${myParent.myChild}
Penanganan null yang anggun memastikan Anda tidak akan mendapatkan pengecualian jika Anda mengakses properti null dalam grafik objek
Gunakan sintaks Pengindeks untuk mengambil properti menurut kunci atau item dalam array. Misalnya, ${myArray[0]}

Menyediakan data

Sekarang setelah Anda memiliki templat, Anda harus menyediakan data yang membuatnya lengkap. Anda memiliki dua opsi untuk melakukan ini:

Opsi A: Sebaris dalam payload templat. Anda dapat menyediakan data secara sebaris dalam payload templat AdaptiveCard. Untuk melakukannya, cukup tambahkan $data atribut ke objek akar AdaptiveCard .
Opsi B: Sebagai objek data terpisah. Dengan opsi ini, Anda menyediakan dua objek terpisah ke Templating SDK saat runtime: template dan data. Ini akan menjadi pendekatan yang lebih umum, karena biasanya Anda akan membuat templat dan ingin menyediakan data dinamis nanti.

Opsi A: Data sebaris

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

Opsi B: Memisahkan templat dari data

Atau (dan kemungkinan besar), Anda akan membuat templat kartu yang dapat digunakan kembali tanpa menyertakan data. Templat ini dapat disimpan sebagai file dan ditambahkan ke kontrol sumber.

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

Kemudian muat dan berikan data saat runtime menggunakan Templating SDK.

Contoh JavaScript

Menggunakan paket templat kartu adaptif .

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!

Dukungan Desainer

Perancang Kartu Adaptif telah diperbarui untuk mendukung templat.

Cobalah di: https://adaptivecards.microsoft.com/designer

Editor Data Sampel - Tentukan data sampel di sini untuk melihat kartu terikat data saat dalam "Mode Pratinjau." Ada tombol kecil di panel ini untuk mengisi Struktur Data dari data sampel yang ada.
Mode Pratinjau - Tekan tombol toolbar untuk beralih antara pengalaman edit dan pengalaman pratinjau data sampel
Buka Sampel - klik tombol ini untuk membuka berbagai contoh payload

Pengikatan tingkat lanjut

Cakupan pengikatan

Ada beberapa kata kunci terlarang untuk mengakses beragam cakupan pengikatan.

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

Menetapkan konteks data ke elemen

Untuk menetapkan "konteks data" ke elemen apa pun, $data tambahkan atribut ke elemen .

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

Mengulangi item dalam array

Jika properti elemen $data Kartu Adaptif terikat ke array, maka elemen itu sendiri akan diulang untuk setiap item dalam array.
Setiap ekspresi pengikatan (${myProperty}) yang digunakan dalam nilai properti akan dilingkupkan ke item individual dalam array.
Jika mengikat ke array string, gunakan ${$data} untuk mengakses elemen string individual. Misalnya, "text": "${$data}"

Misalnya, di TextBlock bawah ini akan diulang 3 kali karena merupakan $data array. Perhatikan bagaimana text properti terikat pada properti name dari sebuah objek individu di dalam array.

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

Menghasilkan:

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

Fungsi bawaan

Tidak ada bahasa templat yang lengkap tanpa serangkaian fungsi pembantu yang kaya. Templat Kartu Adaptif dibangun di atas Adaptive Expression Language (AEL), yang merupakan standar terbuka untuk mendeklarasikan ekspresi yang dapat dievaluasi pada berbagai platform. Dan ini adalah superset yang tepat dari "Logic Apps", sehingga Anda dapat menggunakan sintaks serupa seperti Power Automate, dll.

Ini hanyalah pengambilan sampel kecil dari fungsi bawaan.

Lihat daftar lengkap fungsi Bawaan Bahasa Ekspresi Adaptif.

Evaluasi bersyarkat

if(expression, trueValue, falseValue)

if Contoh

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

Mengurai JSON

json(jsonString) - Mengurai string JSON

json Contoh

Ini adalah respons Azure DevOps di mana message properti adalah string berseri JSON. Untuk mengakses nilai dalam string, kita perlu menggunakan json fungsi dalam templat kita.

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

Penggunaan

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

Yang Mengakibatkan

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

Fungsi kustom

Fungsi kustom didukung melalui API di SDK Templat.

Tata letak bersyarat dengan `$when`

Untuk menghilangkan seluruh elemen jika kondisi terpenuhi, gunakan $when properti . Jika $when menghasilkan false, elemen tersebut tidak akan muncul kepada pengguna.

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

Menyusun templat

Saat ini tidak ada dukungan untuk menyusun "bagian" templat bersama-sama. Tetapi kami mengeksplorasi pilihan dan berharap untuk berbagi lebih banyak segera. Setiap pemikiran di sini diterima!

Examples

Telusuri halaman Sampel yang diperbarui untuk menjelajahi semua jenis kartu templat baru.

Last updated on 2025-12-18

Bagikan melalui