Tata letak widget kanonis

Buat tata letak widget yang efektif dengan mengidentifikasi konten inti Anda terlebih dahulu. Tata letak Anda menentukan cara informasi dan elemen interaktif disusun dalam widget Anda. Android menawarkan beberapa tata letak bawaan untuk toolbar, teks, daftar, dan widget jenis petak untuk menyederhanakan proses ini.

Teks

Tata letak teks sangat ideal untuk menampilkan informasi yang ringkas. Tingkatkan daya tarik visual widget Anda dengan menyertakan gambar bersama teks jika perlu.

Hanya teks

Ideal untuk judul, pembaruan status, deskripsi singkat, atau skenario apa pun di mana satu baris teks secara efektif menyampaikan pesan.

Teks dan gambar

Sertakan gambar untuk menambah dampak visual. Untuk mengetahui informasi selengkapnya, lihat Titik henti sementara untuk mempelajari cara menyesuaikan tata letak ini untuk berbagai ukuran layar.

Toolbar

Gunakan tata letak toolbar untuk memberi pengguna akses cepat ke tugas yang sering digunakan di aplikasi Anda, dalam tata letak fleksibel yang beradaptasi di berbagai ukuran widget.

Toolbar Penelusuran

Tata letak toolbar penelusuran sengaja didesain untuk memfokuskan perhatian pada penelusuran sebagai tindakan utama di toolbar. Tombol praktis tambahan dapat memberikan akses cepat ke fungsi yang sering digunakan.

Toolbar

Toolbar menampilkan branding aplikasi yang diikuti dengan tombol untuk tugas yang paling sering digunakan, yang ideal untuk setelan yang dapat diaktifkan atau link tugas. Saat mengubah ukuran, opsi yang kurang umum digunakan dapat disembunyikan untuk menampilkan tindakan yang lebih umum. Gunakan Titik henti sementara untuk menambahkan tombol baru yang dapat diketuk dengan ukuran minimum 48 dp jika ada ruang.

Daftar

Gunakan tata letak daftar untuk mengatur beberapa item dalam format yang jelas dan mudah dipindai. Fitur ini ideal untuk judul berita, daftar tugas, atau pesan. Susun konten ke dalam daftar terstruktur yang mudah dibaca. Pilih presentasi dalam bentuk penampung atau tanpa penampung berdasarkan kebutuhan konten Anda.

Daftar teks dan gambar

Daftar teks dan gambar yang dapat dipindai sangat cocok untuk menampilkan beberapa jenis konten, seperti judul berita, playlist dengan gambar album, atau pesan.

Checklist

Tata letak checklist sangat cocok untuk menampilkan tugas, menyediakan target ketuk yang jelas bagi pengguna untuk menandai item sebagai selesai dengan cepat.

Daftar tindakan

Menyediakan pengelompokan kontrol intuitif dengan daftar tindakan, yang status visual aktif/nonaktifnya memberikan masukan langsung tentang status item.

Gambar full bleed

Tata letak ini ideal untuk menampilkan gambar imersif dan penuh di Android 17 dan yang lebih tinggi. Tata letak ini menggunakan scroll yang menyentak untuk memastikan setiap elemen turunan selaras sempurna dengan tinggi penampung widget.

Petak

Menampilkan gambar dalam petak yang ringkas, fleksibel, dan kaya visual dengan label opsional. Gunakan kolom dan baris yang beradaptasi dengan berbagai ukuran layar.

Image only

Buat galeri gambar yang dapat di-scroll dan berdampak visual menggunakan petak khusus gambar. Baris dan kolom otomatis menyesuaikan dengan berbagai ukuran layar untuk presentasi yang optimal.

Gambar dan teks

Anda juga dapat menyertakan label dan deskripsi teks, yang memperkaya konten petak gambar dengan konteks dan informasi tambahan.

Contoh kode

Tabel berikut memetakan setiap tata letak kanonis ke implementasi Jetpack Glance yang sesuai di repositori GitHub Contoh Platform Android.

Tata letak kanonis File referensi Panduan
Tata Letak Daftar Tindakan
  • Tangani tindakan item daftar dengan callback tindakan Glance dan pastikan pembaruan status yang tepat.
Tata Letak Daftar Periksa
  • Terapkan pengalihan status kotak centang menggunakan parameter tindakan atau callback untuk memperbarui item koleksi.
  • Gunakan callback tindakan Glance, seperti `actionRunCallback`, `ActionCallback(actionParametersOf(...))`, atau `actionStartActivity(...)`, untuk parameter `onClick` widget guna menangani peristiwa klik seperti mengetuk kotak centang.
Tata Letak Toolbar Ekspresif
  • Hindari error impor `ColorProvider`: impor `androidx.glance.unit.ColorProvider` dan gunakan `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Gunakan `GlanceModifier.background(Color)` secara langsung untuk warna latar belakang solid, bukan `ColorProvider`.
Tata Letak Petak Gambar
  • Gunakan warna solid (`GlanceModifier.background`) atau drawable lokal untuk item gambar, kecuali jika library pemuatan gambar dikonfigurasi atau diminta.
Tata Letak Daftar Teks Gambar
  • Kasus penggunaan umum: feed berita, daftar artikel, histori latihan fisik, feed pesan, dan daftar thumbnail vertikal.
  • Seimbangkan tinggi baris daftar dan pemangkasan teks saat menggabungkan gambar thumbnail dengan teks utama/sekunder.
Tata Letak Teks Panjang
  • Jika Anda mengalikan nilai `Dp`, seperti `2 * padding`, impor `androidx.compose.ui.unit.times`.
  • Ikuti aturan ukuran: pastikan dimensi dari `dimens.xml` digunakan untuk penskalaan padding dan tipografi.
Tata Letak Toolbar Penelusuran
  • Hindari error impor `ColorProvider`: impor `androidx.glance.unit.ColorProvider` dan gunakan `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Gunakan `GlanceModifier.background(Color)` secara langsung untuk warna latar belakang solid, bukan ColorProvider.
Tata Letak Gambar Full Bleed / Scrolling Cepat
  • Setel `verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)` di LazyColumn untuk Snap Scrolling.
  • Jika Anda menerapkan scrolling cepat, Glance 1.3.0-alpha02 atau yang lebih tinggi, SDK kompilasi 37 (Baklava) atau yang lebih tinggi, dan Plugin Android Gradle (AGP) 9.1.0 atau yang lebih tinggi diperlukan.
  • Tetapkan `override val sizeMode: SizeMode = SizeMode.Exact` di class penyedia widget.
Tata Letak Toolbar Standar
  • Lihat Pemecahan masalah untuk menghindari error impor `ColorProvider`: gunakan `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Gunakan `GlanceModifier.background(Color)` secara langsung untuk warna latar belakang solid, bukan `ColorProvider`.
Tata Letak Teks dengan Gambar
  • Ikuti aturan penetapan ukuran tata letak responsif untuk mengakomodasi teks dan gambar secara berdampingan atau bertumpuk berdasarkan dimensi widget yang tersedia.