Oluşturulan widget önizlemeleri, widget'larınız için dinamik ve kişiselleştirilmiş önizlemeler oluşturmanıza olanak tanır. Bu önizlemeler, widget'larınızın kullanıcının ana ekranında nasıl görüneceğini doğru şekilde yansıtır. Bu önizlemeler, push API aracılığıyla sağlanır. Yani uygulamanız, widget ana makinesinden açık bir istek almadan yaşam döngüsü boyunca herhangi bir noktada önizleme sağlar.
Bu kılavuzda, Glance tabanlı widget'lar için önizlemelerin nasıl sağlanacağı açıklanmaktadır. Widget'ınız RemoteViews ile uygulanıyorsa Widget seçicinize önizleme ekleme başlıklı makaleyi inceleyin.
Glance widget'ları için uygulamanızın widget seçici deneyimini iyileştirmek amacıyla Android 15 ve sonraki sürümlerde GlanceAppWidget.providePreview kullanarak oluşturulmuş bir widget önizlemesi sağlayın. Daha önceki sürümlerde ve oluşturulmuş bir önizleme kullanılamıyorsa Android 15 ve sonraki sürümlerde yedek olarak previewImage belirtin.
Daha fazla bilgi için YouTube'daki Uygulamanızı canlı güncellemeler ve widget'larla zenginleştirme başlıklı makaleyi inceleyin.
Uygulamanızı oluşturulan widget önizlemeleri için ayarlama
Android 15 veya sonraki sürümlerin yüklü olduğu cihazlarda Oluşturulan Widget Önizlemeleri'ni göstermek için öncelikle modül build.gradle dosyasında compileSdk değerini 35 veya sonraki bir sürüme ayarlayarak widget seçiciye RemoteViews sağlayabilmeniz gerekir.
Uygulamalar daha sonra setWidgetPreview özelliğini GlanceAppWidgetManager içinde kullanabilir. Kötüye kullanımı önlemek ve sistem sağlığıyla ilgili endişeleri azaltmak için setWidgetPreview, sıklık sınırlaması olan bir API'dir. Varsayılan sınır saatte yaklaşık iki görüşmedir.
Jetpack Glance ile güncellenmiş önizleme oluşturma
Jetpack Glance ile oluşturulan widget'lar için aşağıdakileri yapın:
Önizleme için composable içerik sağlamak üzere
GlanceAppWidget.providePreviewişlevini geçersiz kılın.provideGlance'da yaptığınız gibi, uygulamanızın verilerini yükleyin ve önizlemenin doğru verileri göstermesi için bu verileri widget'ın içerik composable'ına iletin.provideGlance'ın aksine, bu tek bir kompozisyondur ve yeniden kompozisyon veya efekt içermez.Önizlemeyi oluşturup yayınlamak için
GlanceAppWidgetManager.setWidgetPreviewsişlevini çağırın.
Sistemden önizleme sağlamak için geri arama yapılmaz. Bu nedenle, uygulamanız setWidgetPreviews ne zaman arama yapacağına karar vermelidir. Güncelleme stratejisi, widget'ınızın kullanım alanına bağlıdır:
- Widget'ta statik bilgiler varsa veya hızlı işlem widget'ıysa uygulama ilk kez başlatıldığında önizlemeyi ayarlayın.
- Uygulamanızda veri bulunduktan sonra (ör. kullanıcı oturum açtıktan veya ilk kurulum yapıldıktan sonra) önizlemeyi ayarlayabilirsiniz.
- Önizlemeleri belirli bir sıklıkta güncelleyecek şekilde periyodik bir görev ayarlayabilirsiniz.
Oluşturulan önizlemelerle ilgili sorunları giderme
Sık karşılaşılan bir sorun, önizleme oluşturduktan sonra widget'ın bırakma boyutuna göre önizleme resminde resimlerin, simgelerin veya diğer composable'ların eksik olmasıdır. Bu bırakma boyutu, belirtilmişse targetCellWidth ve targetCellHeight, belirtilmemişse uygulama widget'ı sağlayıcı bilgi dosyasındaki minWidth ve minHeight tarafından tanımlanır.
Bunun nedeni, Android'in varsayılan olarak yalnızca widget'ın minimum boyutunda görünen composable'ları oluşturmasıdır. Yani Android, previewSizeMode değerini varsayılan olarak SizeMode.Single olarak ayarlar. Hangi composable'ların çizileceğini belirlemek için uygulama widget'ı sağlayıcı bilgisi XML'sinde android:minHeight ve android:minWidth kullanılır.
Bu sorunu düzeltmek için GlanceAppWidget dosyanızda previewSizeMode değerini geçersiz kılın ve SizeMode.Responsive olarak ayarlayın. Böylece bir dizi DpSize değeri sağlamış olursunuz. Bu, Android'e önizleme için oluşturması gereken tüm düzen boyutlarını bildirir ve tüm öğelerin doğru şekilde gösterilmesini sağlar.
Belirli form faktörleri için optimizasyon yapın. Minimum boyuttan başlayarak ve widget'ınızın ayrılma noktalarını takip ederek bir veya iki boyut sağlayın. previewImage Geriye dönük uyumluluk için en az bir tane belirtin. Farklı ızgara boyutları için uygun minimum DP değerlerini widget tasarım kılavuzunda bulabilirsiniz.
Widget önizlemeleriyle geriye dönük uyumluluk
Android 15'ten önceki sürümlerin yüklü olduğu cihazlarda widget seçicilerin widget'ınızın önizlemelerini göstermesine izin vermek veya Android 15'ten sonraki sürümlerde oluşturulan önizlemeler için yedek olarak previewImage özelliğini belirtin.
Widget'ın görünümünü değiştirirseniz önizleme resmini güncelleyin.