Pilih tampilan baca minimum yang berguna
Dalam aplikasi pendakian ilustratif, kartu seharusnya membantu pembaca menentukan apakah akan membuka referensi historis. Mulailah dengan teks tersedia, konteks sumber, tanggal, serta tautan yang dapat digunakan. API mengembalikan rekaman datar, bukan model kartu siap pakai, dan tidak menjamin setiap field pilihan ada. Buat adaptor kecil antara rekaman tersebut dan layar.
Pisahkan identitas sumber dari teks tampilan. id rekaman yang tersedia dapat membantu aplikasi melacak item, tetapi judul atau cuplikan bukan pengganti identitas yang andal. Jangan menggabungkan rekaman berbeda hanya karena membahas frasa sama. Sediakan data asli bagi adaptor tanpa menampilkan kredensial layanan atau detail debug internal pada kartu.
Jangan menebak jenis atau judul yang tidak ada
Gunakan nilai kind yang valid jika tersedia: post dan comment mendukung label berbeda. Jika jenis tidak ada atau tak dikenal, gunakan label netral Rekaman arsip. Jangan otomatis menganggap semua rekaman tak dikenal sebagai komentar atau menyiratkan komentar terpisah mewakili seluruh diskusi induknya.
Pertimbangkan fixture usulan dengan kind=comment, teks terbaca, tanpa judul dan tanpa tautan sumber yang bisa dipakai. Kartu dapat menuliskan Komentar dan Tautan sumber tidak tersedia, diikuti teksnya. Tidak diperlukan judul hasil generasi atau URL buatan. Fixture lain mungkin memiliki judul posting panjang; biarkan membungkus ke baris berikutnya atau sediakan cara jelas untuk memperluasnya. Ini contoh pengujian, bukan rekaman yang diklaim ada di arsip.
Tampilkan teks sebagai konten yang tidak tepercaya
Lakukan escaping yang aman terhadap teks tidak tepercaya sebelum memasukkannya ke antarmuka. Pertahankan jeda paragraf yang bermakna, tetapi jangan perlakukan konten rekaman sembarang sebagai instruksi HTML. Jika kemudian mendukung Markdown, pilih dan uji aturan perenderan yang dibatasi. Teks biasa adalah versi awal yang sah dan tidak menjanjikan pemformatan yang belum dibuat.
Validasi tautan sumber sebelum mengaktifkannya dan perlakukan nilai hilang atau tidak dapat dipakai sebagai tidak tersedia. Beri keterangan jelas tentang tujuan tautan eksternal. Gunakan label aksi yang terbaca, akses keyboard, serta urutan fokus yang masuk akal. Tooltip saja tidak cukup menjelaskan tanggal atau tautan yang tidak tersedia kepada semua pembaca.
Jaga kejujuran tanggal dan konteks percakapan
Jika timestamp pembuatan yang dapat dipakai ada, tampilkan makna dan formatnya secara konsisten. Jika tidak, tulis Tanggal tidak tersedia. Jangan menyalin timestamp posting induk ke komentar: kedua konten tersebut tidak harus dibuat bersamaan. Tanggal pengambilan yang dicatat aplikasi menjelaskan pengambilan, bukan usia diskusi asal.
Jika parent_id atau link_id tersedia, pengelompokan lokal dapat menghubungkan rekaman yang sudah ada di hasil. Kehadirannya tidak memulihkan leluhur yang hilang, membentuk utas lengkap, atau menyediakan filter baru. API saat ini tidak mengekspos filter parent_id maupun link_id. Kartu dapat mengakui konteks yang hilang tanpa membangun percakapan palsu.
Letakkan kontrol daftar di luar adaptor kartu
Paginasi tingkat daftar harus membaca pagination.has_more dan mematuhi batas halaman. Jangan mengaktifkan atau mematikan Tampilkan lagi hanya karena pagination.relation adalah eq atau gte: relasi itu menjelaskan total, bukan kontrol kelanjutan. Total berupa batas bawah atau tidak diketahui juga bukan bukti bahwa rekaman yang terlihat tidak valid.
Array data kosong yang berhasil merupakan status kosong daftar, bukan kartu galat; tetap dikenai satu kredit pengambilan. Pada tinjauan fixture yang diusulkan, sertakan judul panjang, teks hilang, tanggal hilang, tautan tak dapat dipakai, dan jenis tak dikenal, lalu periksa perilaku tata letak di layar sempit. Ini pemeriksaan untuk implementasi Anda nanti, bukan pengujian yang sudah dilakukan panduan ini. Lihat /id/#field-notes untuk umur sumber dan desain status.
