Menambahkan pratinjau yang dibuat ke alat pilih widget

Pratinjau widget yang dihasilkan memungkinkan Anda membuat pratinjau yang dinamis dan dipersonalisasi untuk widget yang secara akurat mencerminkan tampilannya di layar utama pengguna. Pratinjau ini disediakan melalui push API, yang berarti aplikasi Anda menyediakan pratinjau kapan saja selama siklus prosesnya tanpa menerima permintaan eksplisit dari host widget.

Panduan ini membahas cara menyediakan pratinjau untuk widget berbasis Glance. Jika widget Anda diimplementasikan dengan RemoteViews, lihat Menambahkan pratinjau ke pemilih widget.

Untuk meningkatkan pengalaman pemilih widget aplikasi Anda untuk widget Glance, berikan pratinjau widget yang dihasilkan menggunakan GlanceAppWidget.providePreview di perangkat Android 15 dan yang lebih tinggi, dan tentukan previewImage untuk versi yang lebih rendah, dan sebagai penggantian di Android 15+ jika pratinjau yang dihasilkan tidak tersedia.

Untuk mengetahui informasi selengkapnya, lihat Memperkaya aplikasi Anda dengan widget dan live update di YouTube.

Menyiapkan aplikasi untuk pratinjau widget yang dihasilkan

Untuk menampilkan pratinjau widget yang dihasilkan di perangkat Android 15 atau yang lebih tinggi, tetapkan nilai compileSdk ke 35 atau yang lebih tinggi terlebih dahulu di file build.gradle modul untuk mengaktifkan pratinjau yang dihasilkan di pemilih widget.

Kemudian, aplikasi dapat menggunakan setWidgetPreview di GlanceAppWidgetManager. Untuk mencegah penyalahgunaan dan mengurangi masalah kesehatan sistem, setWidgetPreview adalah API dengan pembatasan kapasitas. Batas defaultnya adalah sekitar dua panggilan per jam.

Membuat pratinjau yang diperbarui dengan Jetpack Glance

Untuk widget yang dibuat dengan Jetpack Glance, lakukan hal berikut:

  1. Ganti fungsi GlanceAppWidget.providePreview untuk menyediakan konten composable untuk pratinjau. Seperti yang Anda lakukan di provideGlance, muat data aplikasi dan teruskan ke composable konten widget, agar pratinjau menampilkan data yang akurat. Tidak seperti provideGlance, ini adalah komposisi tunggal tanpa rekomposisi atau efek.

  2. Panggil GlanceAppWidgetManager.setWidgetPreviews untuk membuat dan memublikasikan pratinjau.

Tidak ada callback dari sistem untuk memberikan pratinjau, sehingga aplikasi Anda harus memutuskan kapan harus memanggil setWidgetPreviews. Strategi update bergantung pada kasus penggunaan widget Anda:

  • Jika widget memiliki informasi statis atau merupakan tindakan cepat, tetapkan pratinjau saat aplikasi pertama kali diluncurkan.
  • Anda dapat menyetel pratinjau setelah aplikasi memiliki data; misalnya, setelah login pengguna atau penyiapan awal.
  • Anda dapat menyiapkan tugas berkala untuk memperbarui pratinjau pada ritme yang dipilih.

Memecahkan masalah pratinjau yang dihasilkan

Masalah umum adalah setelah Anda membuat pratinjau, gambar, ikon, atau composable lainnya mungkin tidak ada dalam gambar pratinjau, relatif terhadap ukuran penempatan widget. Ukuran penempatan ini ditentukan oleh targetCellWidth dan targetCellHeight jika ditentukan, atau oleh minWidth dan minHeight dalam file info penyedia widget aplikasi.

Hal ini terjadi karena Android, secara default, hanya merender composable yang terlihat pada ukuran minimum widget. Dengan kata lain, Android menetapkan previewSizeMode ke SizeMode.Single secara default. Fungsi ini menggunakan android:minHeight dan android:minWidth dalam XML info penyedia widget aplikasi untuk menentukan composable yang akan digambar.

Untuk memperbaikinya, ganti previewSizeMode di GlanceAppWidget dan tetapkan ke SizeMode.Responsive, yang memberikan kumpulan nilai DpSize. Hal ini memberi tahu Android semua ukuran tata letak yang perlu dirender untuk pratinjau, yang memastikan semua elemen ditampilkan dengan benar.

Mengoptimalkan untuk faktor bentuk tertentu. Berikan satu atau dua ukuran mulai dari minimum dan mengikuti titik henti sementara widget Anda. Tentukan setidaknya satu previewImage untuk mendukung versi Android yang lebih rendah. Anda dapat menemukan nilai DP minimum yang sesuai untuk berbagai ukuran petak di panduan desain widget.

Mendukung versi Android yang lebih rendah

Untuk menampilkan pratinjau widget di perangkat yang menjalankan Android 14 dan yang lebih rendah, atau saat pratinjau yang dihasilkan tidak tersedia di Android 15 dan yang lebih tinggi, tentukan atribut previewImage.

Jika Anda mengubah tampilan widget, perbarui gambar pratinjau.

Sebelumnya
Mengaktifkan konfigurasi widget
Berikutnya
Menyematkan widget Sekilas dalam aplikasi