Menambahkan pratinjau yang dibuat ke alat pilih widget

Pratinjau widget yang dihasilkan memungkinkan Anda membuat pratinjau dinamis dan yang 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 memberikan pratinjau untuk widget berbasis Glance. Jika widget Anda diterapkan dengan RemoteViews, lihat Menambahkan pratinjau ke pemilih widget.

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

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

Menyiapkan aplikasi untuk pratinjau widget yang dibuat

Untuk menampilkan Pratinjau Widget yang Dibuat di perangkat Android 15 atau yang lebih baru, pertama-tama tetapkan nilai compileSdk ke 35 atau yang lebih baru dalam file build.gradle modul agar dapat memberikan RemoteViews ke alat pilih widget

Aplikasi kemudian dapat menggunakan setWidgetPreview di GlanceAppWidgetManager. Untuk mencegah penyalahgunaan dan mengurangi masalah kesehatan sistem, setWidgetPreview adalah API yang dibatasi kecepatan. 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 Anda dan teruskan ke composable konten widget, untuk membuat 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, jadi 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 diluncurkan pertama kali.
• Anda dapat menyetel pratinjau setelah aplikasi memiliki data; misalnya, setelah pengguna login atau penyiapan awal.
• Anda dapat menyiapkan tugas berkala untuk memperbarui pratinjau pada irama yang dipilih.

Memecahkan Masalah Pratinjau yang Dibuat

Masalah umum adalah setelah Anda membuat pratinjau, gambar, ikon, atau composable lainnya mungkin hilang dari gambar pratinjau, relatif terhadap ukuran pelepasan widget. Ukuran drop ini ditentukan oleh targetCellWidth dan targetCellHeight jika ditentukan, atau oleh minWidth dan minHeight di 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. Composable ini menggunakan android:minHeight dan android:minWidth dalam XML info penyedia widget aplikasi untuk menentukan composable mana yang akan digambar.

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

Mengoptimalkan faktor bentuk tertentu. Berikan satu atau dua ukuran yang dimulai dari minimum dan mengikuti titik henti sementara widget Anda. Tentukan setidaknya satu previewImage untuk kompatibilitas mundur. Anda dapat menemukan nilai DP minimum yang sesuai untuk berbagai ukuran petak di panduan desain widget.

Catatan: Pilih SizeMode.Exact daripada SizeMode.Responsive saat menentukan ukuran widget (bukan pratinjau). Lihat dokumentasi untuk mengetahui ringkasan SizeMode.

Kompatibilitas mundur dengan pratinjau widget

Untuk mengizinkan alat pilih widget di perangkat yang menjalankan versi lebih rendah dari Android 15 menampilkan pratinjau widget Anda, atau sebagai penggantian untuk Pratinjau yang dihasilkan di Android 15+, tentukan atribut previewImage.

Jika Anda mengubah tampilan widget, perbarui gambar pratinjau.