Membuat templat widget dengan Kartu Adaptif Designer

Untuk widget Kartu Adaptif, tentukan UI dan interaksi dengan templat JSON Kartu Adaptif dan, secara opsional, payload data JSON terpisah. Artikel ini memandu Anda melalui templat counting-widget dengan pengikatan data dan tata letak bersyarat. Windows widget juga dapat menampilkan HTML dari URL; untuk format konten tersebut, lihat Penyedia widget web.

Widget penghitung

Contoh dalam artikel ini adalah widget penghitungan sederhana yang menampilkan nilai bilangan bulat dan memungkinkan pengguna untuk meningkatkan nilai dengan mengklik tombol di UI widget. Contoh templat ini menggunakan pengikatan data untuk memperbarui UI secara otomatis berdasarkan konteks data.

Aplikasi perlu menerapkan penyedia widget untuk menghasilkan dan memperbarui templat widget dan/atau data dan meneruskannya ke host widget. Artikel Menerapkan penyedia widget di aplikasi win32 menyediakan panduan langkah demi langkah untuk menerapkan penyedia widget untuk widget penghitungan yang akan kami hasilkan dalam langkah-langkah di bawah ini.

Perancang Kartu Adaptif

Kartu Adaptif Designer adalah alat online untuk mengedit kartu JSON dan mempratinjau tata letak dan pengikatan datanya. Buka Perancang untuk mengerjakan templat.

Important

Designer menggunakan renderer dan opsi hostnya sendiri. Jangan berasumsi bahwa fitur yang ditawarkannya didukung oleh Widgets Board, atau bahwa ia memasok nilai $host yang khusus untuk Windows. Panduan ini tidak bergantung pada prasetel host atau editor data host. Uji templat akhir di penyedia widget Windows untuk setiap ukuran dan tema yang didukung.

Gambar di bawah ini menggambarkan tata letak kartu, bukan antarmuka Designer saat ini.

Mulai dengan kartu kosong

Editor payload Kartu berisi definisi JSON kartu. Ganti isinya dengan kartu kosong ini:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": []
}

Editor data sampel berisi konteks data JSON opsional. Untuk informasi tentang mengikat data tersebut ke templat, lihat Kartu Adaptif Template Language.

Properti host widget Windows

Papan Widget menyediakan properti host saat runtime. Rujuk elemen tersebut melalui $host dalam ekspresi templat, seperti ${$host.widgetSize}. Properti ini terpisah dari payload data penyedia Anda; menambahkan bidang widgetSize ke data sampel tidak menetapkan $host.widgetSize.

Harta benda	Nilai	Deskripsi
host.widgetSize	"kecil", "sedang", atau "besar"	Ukuran widget yang disematkan.
host.hostTheme	"terang" atau "gelap"	Tema perangkat saat ini tempat Papan Widget ditampilkan.
host.isSettingsPayload	BENAR atau SALAH	Ketika nilai ini benar, pengguna telah mengklik tombol Sesuaikan widget di menu konteks widget. Anda dapat menggunakan nilai properti ini untuk menampilkan elemen antarmuka pengguna dari pengaturan kustomisasi. Ini adalah metode alternatif untuk menggunakan IWidgetProvider2.OnCustomizationRequested untuk mengubah payload JSON di aplikasi penyedia widget. Untuk informasi selengkapnya, lihat Menerapkan kustomisasi widget.
host.isHeaderSupported	BENAR atau SALAH	Jika nilai ini benar, kustomisasi header didukung. Untuk informasi selengkapnya, lihat isHeaderSupported.
host.isHeader	BENAR atau SALAH	Ketika nilai ini benar, host meminta payload khusus untuk penyajian header widget.
host.isWebSupported	BENAR atau SALAH	Ketika nilai ini salah, host saat ini tidak mendukung pemuatan konten web widget. Ketika ini terjadi, widget web akan menampilkan payload JSON fallback yang disediakan oleh penyedia widget, tetapi nilai ini dapat digunakan untuk menyesuaikan konten lebih lanjut. Untuk informasi selengkapnya, lihat Penyedia widget web
host.isUserContextAuthenticated	BENAR atau SALAH	Ketika nilai ini salah, satu-satunya tindakan yang didukung adalah Action.OpenUrl. Nilai isUserContextAuthenticated dapat digunakan untuk menyesuaikan konten widget dengan tepat, mengingat batasan interaktivitas.

Widget penghitungan menggunakan empat elemen TextBlock dan satu tindakan Action.Execute untuk tombolnya.

Menambahkan elemen TextBlock

Tambahkan empat elemen TextBlock dari palet elemen Designer, atau tambahkan langsung di kartu JSON. Sebelum tata letak bersyarat diterapkan, kartu memiliki empat baris teks, seperti yang diilustrasikan di bawah ini.

Menerapkan tata letak kondisional

Di editor payload Card, ganti array body dengan fragmen berikut:

"body": [
    {
        "type": "TextBlock",
        "text": "You have clicked the button ${count} times"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if medium",
        "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if small",
        "$when": "${$host.widgetSize==\"small\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if large",
        "$when": "${$host.widgetSize==\"large\"}"
    }
]

Dalam Bahasa Templat Kartu Adaptif, properti $when menentukan bahwa elemen yang memuat ditampilkan ketika nilai terkait dievaluasi menjadi true. Jika nilai dievaluasi menjadi false, elemen yang bersangkutan tidak ditampilkan. Dalam elemen isi dalam contoh kami, salah satu dari tiga elemen TextBlock akan ditampilkan, dan dua lainnya tersembunyi, tergantung pada nilai $host.widgetSize properti. Untuk informasi selengkapnya tentang kondisi yang didukung di Kartu Adaptif, lihat Tata Letak Bersyarat dengan $when.

Tanpa mengevaluasi ekspresi templat, kartu menunjukkan keempat blok teks:

Saat Papan Widget mengevaluasi templat dengan $host.widgetSize diatur ke "small", hanya blok teks ukuran kecil yang muncul bersama jumlahnya:

Setelah mengintegrasikan templat dengan penyedia Anda, ubah ukuran widget yang disematkan di Papan Widget lalu periksa apakah blok teks yang cocok muncul. Deklarasikan setiap ukuran yang ingin Anda uji dalam manifes penyedia widget. Pratinjau Perancang generik tanpa data host Windows tidak dapat memverifikasi kondisi ini.

Ikat ke konteks data

Contoh menggunakan properti data bernama count, yang dirujuk oleh ${count} di TextBlock pertama. Pada runtime, penyedia mengirim payload data ke host widget. Pada waktu desain, masukkan JSON berikut di editor Data sampel dan aktifkan pratinjau Perancang untuk memeriksa binding hitungan. Data sampel ini tidak menyediakan properti host Windows terpisah.

{"count": "2"}

Dengan {"count": "2"} sebagai data sampel, ekspansi templat menggantikan ${count} dengan 2 di TextBlock pertama. Periksa binding ini di Designer setelah mengaktifkan pratinjau. Periksa kondisi terpisah $host.widgetSize di Papan Widget, seperti yang dijelaskan di atas.

Sedang dalam proses pembuatan kartu adaptif. Baris pertama teks sekarang menyertakan nilai 2 dari muatan data.

Menambahkan tombol

Langkah selanjutnya adalah menambahkan tombol ke widget kami. Di host widget, ketika pengguna mengklik tombol , host akan membuat permintaan ke penyedia widget. Untuk contoh ini, penyedia widget akan menaikkan nilai hitungan dan mengembalikan payload data yang diperbarui. Karena operasi ini memerlukan penyedia widget, Anda tidak akan dapat melihat perilaku ini di Kartu Adaptif Designer, tetapi Anda masih dapat menggunakan perancang untuk menyesuaikan tata letak tombol Anda dalam UI Anda.

Dengan Kartu Adaptif, elemen interaktif didefinisikan dengan elemen action. Tambahkan blok JSON berikut langsung setelah elemen body di editor payload kartu. Pastikan untuk menambahkan koma setelah kurung siku penutup (]) elemen isi atau perancang akan melaporkan kesalahan pemformatan.

,
"actions": [                                                      
    {                                                               
        "type": "Action.Execute",                               
        "title": "Increment",                                   
        "verb": "inc"                                           
    }                                                               
]

Properti type memilih Action.Execute, yang diteruskan host widget ke panggilan balik OnActionInvoked penyedia Anda. Gunakan Action.OpenUrl untuk navigasi URL sebagai gantinya; itu tidak menginvokasi callback penyedia tersebut. Judul menyediakan teks tombol, dan verb adalah operasi yang ditentukan aplikasi yang ditangani penyedia. Jika $host.isUserContextAuthenticated bernilai false, jangan tawarkan interaksi Action.Execute; hanya Action.OpenUrl yang didukung.

Templat widget lengkap

Daftar kode berikut menunjukkan templat akhir untuk interaksi counting-widget. Tombol Action.Execute memerlukan konteks pengguna yang diautentikasi. Validasikan di Widgets Board dengan penyedia Anda; Perancang tidak menjalankan handler inkrement penyedia Anda.

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": [
    {
      "type": "TextBlock",
      "text": "You have clicked the button ${count} times"
    },
    {
      "type": "TextBlock",
       "text": "Rendering Only if Small",
      "$when": "${$host.widgetSize==\"small\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Medium",
      "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Large",
      "$when": "${$host.widgetSize==\"large\"}"
    }
    ],
   "actions": [
    {
      "type": "Action.Execute",
      "title": "Increment",
      "verb": "inc"
    }
  ]
}

Contoh pengaturan payload

Daftar kode berikut menunjukkan contoh sederhana payload JSON yang menggunakan properti host.isSettingsPayload untuk menampilkan konten yang berbeda ketika pengguna telah mengklik tombol Kustomisasi widget .

{
    "type": "AdaptiveCard",
    "body": [
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Content payload",
                "$when": "${!$host.isSettingsPayload}"
            }
        ]
    },
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Settings payload",
                "$when": "${$host.isSettingsPayload}"
            }
        ]
    }
],
"actions": [
    {
        "type": "Action.Execute",
        "title": "Increment",
        "verb": "inc",
        "$when": "${!$host.isSettingsPayload}"
    },
    {
        "type": "Action.Execute",
        "title": "Update Setting",
        "verb": "setting",
        "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}