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 ideal untuk menampilkan informasi ringkas. Tingkatkan daya tarik visual widget Anda dengan menyertakan gambar bersama teks jika perlu.

Hanya teks

Cocok untuk judul, status terbaru, deskripsi singkat, atau skenario apa pun yang memerlukan satu baris teks untuk menyampaikan pesan secara efektif.

Teks dan gambar

Sertakan gambar untuk memberikan dampak visual tambahan. 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 dirancang untuk menarik fokus ke 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/dinonaktifkan 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. Hal ini ideal untuk judul berita, daftar tugas, atau pesan. Mengatur konten ke dalam daftar terstruktur yang mudah dibaca. Pilih antara presentasi dalam 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 yang intuitif dengan daftar tindakan, tempat status aktif/nonaktif visual menawarkan masukan langsung tentang status item.

Gambar penuh

Ideal untuk menampilkan gambar imersif tanpa tepi di Android 17 dan yang lebih tinggi, tata letak ini menggunakan scroll snap 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. Menggunakan 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
  • Menangani tindakan item daftar dengan callback tindakan Glance dan memastikan update status yang tepat.
Tata Letak Daftar Periksa
  • Terapkan pengalihan status kotak centang menggunakan parameter tindakan atau callback untuk memperbarui item koleksi.
  • Gunakan callback tindakan Sekilas, 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, 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 padding dan penskalaan 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 scroll snap, 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.