Spesifikasi Perender Kartu Adaptif

Spesifikasi berikut menjelaskan cara mengimplementasikan perender Kartu Adaptif pada platform UI asli apa pun.

Mengurai JSON

Kondisi kesalahan

1. Pengurai HARUS memeriksa apakah konten JSON valid
2. Pengurai HARUS memvalidasi terhadap skema (properti yang diperlukan, dll)
3. Kesalahan di atas HARUS dilaporkan ke aplikasi host (pengecualian atau setara)

Jenis tidak diketahui

1. Jika "jenis" yang tidak diketahui ditemukan, mereka HARUS DIHILANGKAN dari hasil
2. Setiap perubahan payload (seperti di atas) HARUS dilaporkan sebagai peringatan ke aplikasi host

Properti tidak diketahui

1. Pengurai HARUS menyertakan properti tambahan pada elemen

Pertimbangan tambahan

1. Properti speak MUNGKIN berisi markup SSML dan HARUS dikembalikan ke aplikasi host sebagaimana ditentukan

Mengurai Konfigurasi Host

1. TODO

Penerapan versi

1. Perender HARUS menerapkan versi skema tertentu.
2. AdaptiveCard Konstruktor HARUS memberi version properti nilai default berdasarkan versi skema saat ini
3. Jika perender menemukan version properti di AdaptiveCard yang lebih tinggi dari versi yang didukung, itu HARUS mengembalikan fallbackText sebagai gantinya.

Rendering

AdaptiveCard Terdiri dari dan body actions. body adalah kumpulan CardElementyang akan dijumlahkan dan dirender oleh perender secara berurutan.

1. Setiap Elemen HARUS membentang ke lebar induknya (pikirkan display: block dalam HTML).
2. Perender HARUS mengabaikan jenis elemen yang tidak diketahui yang ditemuinya dan terus merender payload lainnya.

Teks, TextBlock, dan RichTextBlock

1. TextBlock HARUS mengambil satu baris kecuali wrap properti adalah true.
2. Blok teks HARUS memangkas teks berlebih dengan elipsis (...)

Markdown

1. Kartu Adaptif memungkinkan subset Markdown dan HARUS didukung di TextBlock.
2. RichTextBlock TIDAK mendukung Markdown, dan harus ditata menggunakan properti yang diekspos.
3. Lihat persyaratan markdown lengkap

Fungsi pemformatan

1. TextBlock memungkinkan fungsi pemformatan DATE/TIME yang HARUS didukung pada setiap perender.
2. SEMUA KEGAGALAN HARUS menampilkan string mentah dalam kartu. Tidak ada pesan ramah yang dicoba. (Tujuannya adalah untuk membuat pengembang segera menyadari ada masalah)

Gambar

1. Perender HARUS memungkinkan aplikasi host untuk mengetahui kapan semua gambar HTTP telah diunduh dan kartu "sepenuhnya dirender"
2. Perender HARUS memeriksa param Konfigurasi maxImageSize Host saat mengunduh gambar HTTP
3. Perender HARUS mendukung .png dan .jpeg
4. Perender HARUS mendukung .gif gambar

Perilaku Tata Letak Tingkat Lanjut

Perender HARUS memperhatikan perilaku berikut saat merender elemen kartu sehubungan dengan atribut yang disebutkan dalam dokumen ini.

Perender harus mengelola Batasan dengan mempertimbangkan berbagai faktor seperti margin, padding, tinggi dan lebar dll konfigurasi elemen kartu dan anak-anaknya.

Width

1. Nilai yang diizinkan - auto, stretch dan nilai tetap dalam hal pixels dan weight
2. auto menyediakan ruang yang cukup untuk perluasan lebar (mendukung ekspansi min)
3. stretch mengambil lebar yang tersisa (mendukung ekspansi maks)

Skenario di bawah ini menjelaskan bagaimana batasan dipengaruhi dengan kombinasi lebar yang berbeda untuk kolom

auto vs stretch

1. Kolom dengan auto dan stretch lebar.

• Kolom pertama dengan auto lebar membutuhkan ruang yang cukup untuk menampilkan konten dan kolom kedua dengan stretch lebar membutuhkan seluruh ruang.

2. Kolom dengan lebar saja stretch

• Kolom dengan lebar peregangan hanya mengambil spasi yang tersisa setelah membalahnya secara merata.

3. auto, stretch, dan auto

Lebar kolom pertama dan ketiga disesuaikan terlebih dahulu untuk mengakomodasi elemen dengan cukup dan kolom kedua dengan lebar yang direntangkan membutuhkan ruang yang tersisa.

4. Urutan menampilkan elemen dengan auto kolom lebar

• Kolom dengan auto akan memposisikan diri mereka sendiri untuk memberikan ruang yang cukup bagi konten untuk dirender.
• Dalam kasus tampilan Gambar, gambar akan downscale agar sesuai dengan lebar yang tersisa.
• Catatan: Gambar hanya akan downscale untuk stretch auto dan ukuran gambar, tetapi tidak untuk lebar dan tinggi tetap dalam piksel.

weights vs pixels

1. Kolom dengan weight kombinasi lebar dan pixel

• Kartu di atas memiliki tiga kolom dengan konfigurasi lebar berikut -
• Column1: Weight 50, , Column2: 100pxColumn3: Weight 50
• Lebar Kolom 2 ditentukan oleh pixel value
• Lebar Kolom 1 dan 3 disesuaikan berdasarkan weights dan yang dihitung weight ratio.

2. Kolom dengan weightatribut , pixel width dan auto

• Kartu di atas memiliki empat kolom dengan konfigurasi lebar berikut -
• Column1: Weight 50, Column2: 100px, Column3: Weight 50, dan Column4: auto
• Catatan: Tampilan gambar dengan auto downscales kolom lebar untuk menyesuaikan ke ruang yang tersisa.

Urutan prioritas menampilkan elemen dengan atribut lebar

px > weight > auto > stretch

Height

Nilai yang diizinkan - auto dan stretch

Skenario di bawah ini menjelaskan bagaimana batasan dipengaruhi dengan kombinasi tinggi yang berbeda untuk elemen kartu

1. Elemen diperluas secara bebas secara vertikal ketika kartu tidak memiliki tinggi tetap

• Kedua kolom dapat diperluas dengan cukup vertikal terlepas dari auto nilai dan stretch
• Ini dengan properti dinonaktifkan wrap untuk blok teks.

2. Kartu di bawah ini mengaktifkan wrap properti untuk blok teks.

Penspasian dan Pemisah

1. Properti spacing pada setiap elemen memengaruhi jumlah ruang antara elemen CURRENT dan yang SEBELUM .
2. Penspasian HANYA BOLEH berlaku ketika sebenarnya ada elemen yang mendahuluinya. (Misalnya, tidak akan berlaku untuk item pertama dalam array)
3. Perender HARUS mencari jumlah ruang yang akan digunakan dari hostConfig penspasian untuk nilai enum yang diterapkan ke elemen saat ini.
4. Jika elemen memiliki separator nilai true, maka baris yang terlihat HARUS digambar antara elemen saat ini dan yang sebelumnya.
5. Garis pemisah HARUS digambar menggunakan container.style.default.foregroundColor.
6. Pemisah HANYA BOLEH digambar jika item BUKAN yang pertama dalam array.
7. Penspasian - Nilai noneyang diizinkan , , smalldefault, medium, large, extra large danpadding

• Atribut spasi menambahkan penspasian antara elemen ini dan elemen sebelumnya.

• Atribut spasi tidak memiliki efek apa pun ketika itu adalah elemen pertama dalam kontainer tampilan.

• Elemen yang ditandai dengan panah adalah elemen pertama di antara saudara-saudaranya, sehingga penspasian tidak berpengaruh.

2. Pemisah - Nilai yang mungkin (aktif/matikan)

• Menggambar garis pemisah di bagian atas elemen.

3. Kombinasi Spasi dan Pemisah

• Batasan penspasian dan kombinasi pemisah diilustrasikan di bawah ini.

• Jarak penspasian keseluruhan dipertahankan sehubungan dengan nilai yang disediakan.
• Seperator ditambahkan setengah di tengah jarak berjarak.

[Catatan. Perlu mengonfirmasi jarak tempat seperator dimasukkan di area penspasian. Sepertinya tengah]

Gaya Kontainer

• Menyediakan petunjuk gaya untuk kontainer seperti kolom dan kumpulan kolom
• Nilai noneyang diizinkan , default, emphasis, good, attention, warning dan accent
• Opsi gaya yang telah ditentukan sebelumnya ini menyediakan padding untuk elemen dalam kontainer dan warna latar belakang

1. Kartu A mengilustrasikan kolom dan kumpulan kolom tanpa opsi gaya
2. Kartu B mengilustrasikan kumpulan kolom dengan gaya Perhatian . Perhatikan padding dalam kontainer kumpulan kolom dan perubahan warna latar belakang.
3. Kartu C mengilustrasikan kolom dengan gaya saja. Mirip dengan yang sebelumnya, kolom menyertakan padding dan perubahan latar belakang.
4. Kartu D mengilustrasikan kolom dan kumpulan kolom keduanya dengan opsi gaya.

[Catatan. Perlu memeriksa bagaimana jumlah padding ditentukan. Apakah ditentukan oleh host? ]

Keluarkan

• Properti ini memungkinkan kontainer seperti kolom dan kumpulan kolom berdarah melalui induknya.
• on Nilai yang mungkin dan off.

1. Kartu A mengilustrasikan kolom dan kumpulan kolom dengan gaya reguler.
2. Kartu B mengilustrasikan kolom pertama dengan opsi berdarah. Konten hanya berdarah melalui batas-batasnya ke induknya.

Ukuran Gambar

atribut Size

• Nilai yang diizinkan - auto, stretch, small, medium, large
• auto : Gambar akan menurunkan skala agar pas jika diperlukan, tetapi tidak akan meningkatkan skala untuk mengisi area.
• stretch : Gambar dengan skala turun dan naik agar sesuai kebutuhan.
• small, medium dan large: Gambar ditampilkan dengan lebar tetap, di mana lebar ditentukan oleh host.

1. auto vs stretch

2. Lebar kolom dan kombinasi Ukuran Gambar

• Umumnya, Kolom dengan stretch lebar memungkinkan gambar untuk meningkatkan skala dengan bebas dengan stretch ukuran.
• Kolom dengan auto lebar memungkinkan gambar untuk menempati ruang yang tepat terlepas dari auto ukuran dan stretch ukuran gambar.
• Lebar kolom lebih diutamakan dalam menentukan ukuran gambar dalam pengaturan ini.

Atribut gambar Width (in pixels)

• Ini menyediakan lebar gambar pada layar yang diinginkan.
• size properti ditimpa ketika nilai ditentukan

• Kolom dengan auto lebar akan lebih diutamakan daripada stretch menyediakan ruang untuk konten gambar dalam pengaturan ini.

Lebar Kolom (berat dan piksel) dan Ukuran gambar (otomatis dan regangkan) Kombinasi

• Gambar dengan auto ukuran membutuhkan ruang yang cukup untuk ekspansi (atau downscales) dalam batasan weight kolom dan pixel lebar.
• Gambar dengan stretch ukuran dapat diperluas untuk mengisi ruang yang tersisa dalam batasan kolom weight dan pixel lebar.

Ringkasan Tata Letak Tingkat Lanjut

• Lebar kolom lebih diutamakan dalam menentukan ukuran gambar daripada ukuran gambarnya (otomatis, bentang, lebar min, dll).
• Prioritas lebar kolom yang diambil untuk menampilkan kontennya dengan cukup - px>weight>auto>stretch
• Gambar size (auto, stretch) diabaikan saat Gambar width dan height dalam px disediakan.
• Atribut ukuran gambar stretch akan meningkatkan skala gambar hanya ketika ada ruang yang tersisa dan kolom otomatis bukan auto.
• Gambar membentang sendiri ke batas di mana ia mempertahankan rasio aspeknya di ruang yang tersedia di kolom. Pada gilirannya, tinggi meluas dengan bebas.
• Spacing atribut tidak akan berpengaruh ketika itu adalah elemen pertama atau satu-satunya di antara saudara kandungnya.

Tindakan

1. Jika HostConfig supportsInteractivity adalah false, perender TIDAK BOLEH merender tindakan apa pun.
2. Properti actions HARUS dirender sebagai tombol di beberapa jenis bilah tindakan, biasanya di bagian bawah kartu.
3. Saat tombol diketuk, itu HARUS memungkinkan aplikasi host untuk menangani peristiwa.
4. Peristiwa HARUS melewati semua properti terkait dengan tindakan
5. Peristiwa HARUS melewati AdaptiveCard yang dijalankan

Action.OpenUrl

1. Action.OpenUrlHARUS membuka URL menggunakan mekanisme platform asli
2. Jika ini tidak memungkinkan, ANDA HARUS menaikkan peristiwa ke aplikasi host untuk menangani pembukaan URL. Kejadian ini HARUS memungkinkan aplikasi host untuk mengambil alih perilaku default. Misalnya, biarkan mereka membuka URL dalam aplikasi mereka sendiri.

Action.ShowCard

1. Action.ShowCardHARUS didukung dalam beberapa cara, berdasarkan pengaturan hostConfig. Ada dua mode: sebaris, dan popup. Kartu sebaris HARUS mengalihkan visibilitas kartu secara otomatis. Dalam mode popup, peristiwa HARUS ditembakkan ke aplikasi host untuk menampilkan kartu dalam beberapa cara.

Action.Submit

• Action.Submit elemen mengumpulkan bidang input, menggabungkan dengan bidang data opsional, dan mengirim peristiwa ke klien.
• Perbedaan signifikan dalam perilaku elemen ada antara versi 1.x dan 2.x dari penyaji ACL.

Tindakan Kirim bertingkah seperti pengiriman formulir HTML, kecuali bahwa di mana HTML biasanya memicu posting HTTP, Kartu Adaptif meninggalkannya ke setiap aplikasi host untuk menentukan apa arti "kirim" bagi mereka.

1. Saat ini HARUS memunculkan peristiwa, pengguna mengetuk tindakan yang dipanggil.
2. Properti data HARUS disertakan dalam payload panggilan balik.
3. Untuk Action.Submit, perender HARUS mengumpulkan semua input pada kartu dan mengambil nilainya.

• 1.x Renderer - Input dikumpulkan dari semua bidang terlepas dari di mana dalam hierarki bidang input ada.
• 2.x Renderer - Input dikumpulkan dari bidang yang ada dalam kontainer induk atau sebagai saudara kandung Action.Submit dari elemen .

Action.Execute (Detail akan datang nanti)

Action.Execute diperkenalkan dalam versi 1.4. Kami akan memberikan panduan implementasi untuk SDK di kemudian hari. Silakan hubungi jika Anda memiliki pertanyaan tentang topik ini.

selectAction

1. Jika Konfigurasi supportedInteractivity Host adalah false maka selectAction TIDAK BOLEH dirender sebagai target sentuhan.
2. Image, ColumnSet, dan Column menawarkan selectAction properti, yang HARUS dijalankan ketika pengguna memanggilnya, misalnya, dengan mengetuk elemen .

Input

1. Jika HostConfig supportsInteractivity adalah false perender TIDAK BOLEH merender input apa pun.
2. Input HARUS dirender dengan keakuratan tertinggi yang mungkin. Misalnya, Input.Date idealnya akan menawarkan pemilih tanggal kepada pengguna, tetapi jika ini tidak dimungkinkan pada tumpukan UI Anda, maka perender HARUS kembali untuk merender kotak teks standar.
3. Perender HARUS menampilkan placeholderText jika memungkinkan
4. Pengikatan nilai input HARUS diloloskan dengan benar
5. Sebelum v1.3, Perender TIDAK harus menerapkan validasi input. Pengguna Kartu Adaptif harus berencana untuk memvalidasi data apa pun yang diterima di akhir mereka.
6. Label Input dan Validasi diperkenalkan dalam v1.3 dari Skema Kartu Adaptif. Perawatan ekstra harus dilakukan untuk merender label terkait, petunjuk validasi, dan pesan kesalahan.

API Gaya, Kustomisasi, dan Ekstensibilitas

Setiap SDK harus memberikan tingkat fleksibilitas tertentu untuk Aplikasi Host untuk mengontrol gaya keseluruhan, dan memperluas skema sesuai keinginan.

Konfigurasi Host

• TODO: Apa yang harus default? Haruskah mereka semua berbagi? Haruskah kita menyematkan file hostConfig.json umum di biner?

HostConfig adalah objek konfigurasi bersama yang menentukan bagaimana Perender Kartu Adaptif menghasilkan UI.

Ini memungkinkan properti yang merupakan agnostik platform untuk dibagikan di antara perender di berbagai platform dan perangkat. Ini juga memungkinkan alat untuk dibuat yang memberi Anda gambaran tentang tampilan dan nuansa yang akan dimiliki kartu untuk lingkungan tertentu.

1. Perender HARUS mengekspos parameter Konfigurasi Host untuk menghosting aplikasi
2. Semua elemen HARUS ditata sesuai dengan pengaturan Konfigurasi Host masing-masing

Gaya platform asli

1. Setiap jenis elemen HARUS melampirkan gaya platform asli dengan elemen UI yang dihasilkan. Misalnya, dalam HTML kami menambahkan kelas CSS ke jenis elemen, dan di XAML kami menetapkan Gaya tertentu.

Ekstensibilitas

1. Perender HARUS memungkinkan aplikasi host untuk mengambil alih perender elemen default. Misalnya, ganti TextBlock penyajian dengan logika mereka sendiri.
2. Perender HARUS memungkinkan aplikasi host untuk mendaftarkan jenis elemen kustom. Misalnya, tambahkan dukungan untuk elemen kustom Rating
3. Perender HARUS memungkinkan aplikasi host menghapus dukungan untuk elemen default. Misalnya, hapus Action.Submit jika mereka tidak ingin didukung.

Acara

1. Perender HARUS mengaktifkan peristiwa ketika visibilitas elemen telah berubah, memungkinkan aplikasi host untuk menggulir kartu ke posisi.