Membuat templat widget dengan Kartu Adaptif Designer

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 dari Dev Channel Windows dimulai dari build 25217. Untuk informasi tentang build pratinjau 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 ditentukan menggunakan dokumen JSON yang sesuai dengan skema Kartu Adaptif. Artikel ini memanding Anda melalui langkah-langkah untuk membuat templat widget sederhana.

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 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 prasetel

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 Kartu Adaptif Bahasa Templat.

Editor teks ketiga diberi label Editor Data Host Sampel. Perhatikan bahwa editor ini dapat diciutkan di bawah dua editor lainnya pada halaman ini. 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.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.

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 Kartu 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.

Menerapkan tata letak kondisional

Editor Payload Kartu telah diperbarui untuk mencerminkan elemen TextBlock yang kami tambahkan. Ganti string JSON untuk 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 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.

Sekarang pratinjau akan terlihat seperti gambar berikut:

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:

Dari menu dropdown Ukuran kontainer , pilih "Sedang" dan perhatikan bahwa pratinjau beralih ke hanya menampilkan TextBlock untuk 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 $countvariabel . 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 dari TextBlock pertama.

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

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 ditentukan aplikasi yang akan dikirim host widget ke penyedia widget untuk mengomunikasikan niat yang terkait dengan tindakan. Widget dapat memiliki beberapa tindakan, dan kode penyedia widget akan memeriksa nilai kata kerja dalam permintaan untuk menentukan tindakan apa yang harus diambil.

Templat widget lengkap

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