Membuat templat widget dengan Perancang Kartu Adaptif

2025-06-10

Nota

Beberapa informasi berkaitan dengan produk yang telah dirilis sebelumnya, yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersurat maupun tersirat, sehubungan dengan informasi yang diberikan di sini.

Penting

Fitur yang dijelaskan dalam topik ini tersedia di build pratinjau Dev Channel Windows yang dimulai dengan build 25217. Untuk informasi tentang versi pratinjau dari Windows, lihat Windows 10 Insider Preview.

Antarmuka pengguna dan interaksi untuk Widget Windows diimplementasikan menggunakan Kartu Adaptif. Setiap widget menyediakan templat visual dan, secara opsional, templat data yang didefinisikan menggunakan dokumen JSON yang sesuai dengan skema Kartu Adaptif. Artikel ini memanding Anda melalui langkah-langkah untuk membuat templat widget sederhana.

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

Perancang Kartu Adaptif adalah alat interaktif online yang memudahkan pembuatan templat JSON untuk Kartu Adaptif. Dengan menggunakan perancang, Anda dapat melihat visual yang dirender dan perilaku pengikatan data secara real time saat Anda membangun templat widget Anda. Ikuti tautan untuk membuka perancang, yang akan digunakan untuk semua langkah dalam panduan ini.

Buat templat kosong dari pengaturan awal

Di bagian atas halaman, dari menu dropdown Pilih aplikasi host, pilih Papan Widget. Ini akan mengatur ukuran kontainer untuk Kartu Adaptif agar memiliki ukuran yang didukung untuk widget. Perhatikan bahwa widget mendukung ukuran kecil, sedang, dan besar. Ukuran preset templat default adalah ukuran yang benar untuk widget kecil. Jangan khawatir jika konten meluap ke batas karena kami akan menggantinya dengan konten yang dirancang agar pas di dalam widget.

Ada tiga editor teks di bagian bawah halaman. Yang berlabel Editor Payload Kartu berisi definisi JSON dari UI widget Anda. Editor berlabel Editor Data Sampel berisi JSON yang menentukan konteks data opsional untuk widget Anda. Konteks data terikat secara dinamis ke Kartu Adaptif saat widget dirender. Untuk informasi selengkapnya tentang pengikatan data di Kartu Adaptif, lihat Bahasa Templat Kartu Adaptif.

Editor teks ketiga diberi label Sampel Editor Data Host. Perhatikan bahwa editor ini mungkin akan berada di bawah dua editor lainnya pada halaman. Jika demikian, klik + untuk memperluas editor. Aplikasi host widget dapat menentukan properti host yang dapat Anda gunakan di templat widget Anda untuk menampilkan konten yang berbeda secara dinamis berdasarkan nilai properti saat ini. Papan Widget mendukung properti host berikut.

Harta benda	Nilai	Deskripsi
host.ukuranWidget	"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 pengaturan khusus. 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.

Menu dropdown Ukuran kontainer dan Tema di samping menu dropdown Pilih aplikasi host di bagian atas halaman memungkinkan Anda mengatur properti ini tanpa mengedit sampel JSON secara manual di editor.

Membuat kartu baru

Di sudut kiri atas halaman, klik Kartu baru. Dalam dialog Buat , pilih Kartu Kosong. Anda sekarang akan melihat Kartu Adaptif kosong. Anda juga akan melihat bahwa dokumen JSON di editor data sampel kosong.

Widget penghitungan yang akan kita buat sangat sederhana, hanya terdiri dari 4 elemen TextBlock dan satu tindakan jenis Action.Execute, yang menentukan tombol widget.

Menambahkan elemen TextBlock

Tambahkan empat elemen TextBlock dengan menyeretnya dari panel elemen Card di sebelah kiri halaman ke kartu adaptif kosong di panel pratinjau. Pada titik ini, pratinjau widget akan terlihat seperti gambar berikut. Konten lagi meluap di luar batas widget, tetapi ini akan diperbaiki dalam langkah-langkah berikut.

Kartu adaptif sedang dalam proses. Ini menunjukkan widget dengan empat baris yang berisi teks Blok Teks Baru. Empat baris teks melimpah ke batas bawah widget.

Menerapkan tata letak kondisional

Editor Payload Kartu telah diperbarui untuk mencerminkan elemen TextBlock yang kami tambahkan. Ganti string JSON dari objek isi dengan yang berikut ini:

"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 Template Kartu Adaptif, properti $when menentukan bahwa elemen yang mengandung ditampilkan ketika nilai terkait dievaluasi menjadi benar. 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 properti . Untuk informasi selengkapnya tentang kondisional yang didukung dalam Adaptive Cards, lihat tata letak bersyarat dengan $when .

Sekarang pratinjau akan terlihat seperti gambar berikut:

Kartu adaptif sedang berlangsung. Ini menunjukkan widget dengan empat baris yang berisi teks yang ditentukan dalam payload JSON yang ditunjukkan pada langkah sebelumnya. Alih-alih menyembunyikan elemen secara kondisional, semua elemen terlihat dan meluap ke batas bawah gambar.

Perhatikan bahwa pernyataan kondisional tidak tercermin dalam pratinjau. Ini karena perancang tidak mensimulasikan perilaku host widget. Klik tombol mode Pratinjau di bagian atas halaman untuk memulai simulasi. Pratinjau widget sekarang terlihat seperti gambar berikut:

Kartu adaptif sedang dalam proses. Ini menampilkan widget dengan dua baris yang memuat teks yang ditentukan dalam payload JSON. Hanya TextBlock untuk ukuran kecil yang dirender.

Dari dropdown ukuran Kontainer , pilih "Sedang" dan perhatikan bahwa pratinjau beralih untuk hanya menampilkan TextBlock pada ukuran sedang. Kontainer dalam pratinjau juga mengubah ukuran, menunjukkan bagaimana Anda dapat menggunakan pratinjau untuk memastikan bahwa UI Anda sesuai dalam kontainer widget untuk setiap ukuran yang didukung.

Ikat ke konteks data

Contoh widget kami akan menggunakan properti status kustom bernama "count". Anda dapat melihat di templat saat ini bahwa nilai untuk TextBlock pertama menyertakan referensi variabel . Ketika widget berjalan di Papan Widget, penyedia widget bertanggung jawab untuk merakit payload data dan meneruskannya ke host widget. Pada waktu desain, Anda dapat menggunakan Editor Data Sampel untuk membuat prototipe payload data Anda dan melihat bagaimana nilai yang berbeda memengaruhi tampilan widget Anda. Ganti payload data kosong dengan JSON berikut.

{"count": "2"}

Perhatikan bahwa pratinjau sekarang menyisipkan nilai yang ditentukan untuk properti jumlah ke dalam teks untuk TextBlock pertama .

Kartu adaptif sedang dalam proses. Baris pertama teks sekarang menyertakan nilai 2 dari payload 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 Perancang Kartu Adaptif, tetapi Anda masih dapat menggunakan perancang untuk menyesuaikan tata letak tombol Anda dalam UI Anda.

Dengan Kartu Adaptif, elemen interaktif didefinisikan dengan elemen tindakan . Tambahkan blok JSON berikut langsung setelah elemen badan 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"                                           
    }                                                               
]

Dalam string JSON ini, properti jenis menentukan jenis tindakan yang sedang diwakili. Widget hanya mendukung jenis tindakan "Action.Execute". Judul berisi teks yang ditampilkan pada tombol untuk tindakan. Properti kata kerja adalah string yang didefinisikan oleh aplikasi yang akan dikirimkan oleh host widget ke penyedia widget untuk menyampaikan maksud terkait tindakan tersebut. Widget dapat memiliki beberapa tindakan, dan kode penyedia widget akan memeriksa nilai kata kerja dalam permintaan untuk menentukan tindakan apa yang harus diambil.

Kartu adaptif akhir. Tombol biru dengan teks 'Increment' ditampilkan setelah dua baris teks.

Daftar kode berikut menunjukkan versi akhir payload JSON.

{
    "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.Submit",
    "title": "Increment",
    "verb": "inc",
    "$when": "${!$host.isSettingsPayload}"
    },
    {
    "type": "Action.Submit",
    "title": "Update Setting",
    "verb": "setting",
    "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}

Bagikan melalui

Widget penghitung