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.
Uygulamanızın widget seçici deneyimini iyileştirmek için Android 15 ve sonraki sürümlerde oluşturulmuş bir widget önizlemesi, Android 12 ile Android 14 arasındaki cihazlarda ölçeklendirilmiş bir widget önizlemesi (previewLayout belirterek) ve önceki sürümlerde previewImage sağlayın.
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 Önizlemelerini göstermek için öncelikle modül build.gradle dosyasında compileSdk değerini 35 veya sonraki bir sürüme ayarlayın. Böylece widget seçiciye RemoteViews sağlayabilirsiniz.
Uygulamalar daha sonra setWidgetPreview öğesini GlanceAppWidgetManager veya AppWidgetManager 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 çağrıdır.
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çeriği 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österdiğinden emin olmak için 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ın setWidgetPreviews ne zaman arama yapacağına karar vermesi gerekir. 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 tarafından, 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 previewSizeMode değerini GlanceAppWidget içinde geçersiz kılın ve SizeMode.Responsive olarak ayarlayarak bir dizi DpSize değeri sağlayın. 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 kesme noktalarını takip ederek 1 veya 2 boyut sağlayın. Geriye dönük uyumluluk için en az bir resim belirtin. Farklı ızgara boyutları için uygun minimum DP değerlerini widget tasarım kılavuzunda bulabilirsiniz.
Jetpack Glance olmadan güncellenmiş önizleme oluşturma
RemoteViews özelliğini Glance olmadan kullanabilirsiniz. Aşağıdaki örnekte bir XML
widget düzen kaynağı yüklenir ve önizleme olarak ayarlanır. setWidgetPreview öğesinin bu snippet'te yöntem olarak gösterilmesi için 35 veya sonraki bir compileSdk derleme ayarı gerekir.
AppWidgetManager.getInstance(appContext).setWidgetPreview(
ComponentName(
appContext,
ExampleAppWidgetReceiver::class.java
),
AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
RemoteViews("com.example", R.layout.widget_preview)
)
Widget seçiciye ölçeklenebilir widget önizlemeleri ekleme
Android 12'den itibaren, widget seçicide gösterilen widget önizlemesi ölçeklenebilir. Bu düzeni, widget'ın varsayılan boyutuna ayarlanmış bir XML düzeni olarak sağlarsınız. Daha önce, widget önizlemesi statik bir çizilebilir kaynaktı. Bu durum, bazı durumlarda önizlemelerin, widget'lar ana ekrana eklendiğinde nasıl göründüğünü doğru şekilde yansıtmamasına neden oluyordu.
Ölçeklenebilir widget önizlemeleri uygulamak için appwidget-provider öğesinin previewLayout özelliğini kullanarak bunun yerine bir XML düzeni sağlayın:
<appwidget-provider
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
Gerçekçi varsayılan veya test değerleriyle, gerçek widget'la aynı düzeni kullanmanızı öneririz. Çoğu uygulama aynı previewLayout ve initialLayout değerlerini kullanır. Doğru önizleme düzenleri oluşturmayla ilgili rehberlik için bu sayfadaki aşağıdaki bölüme bakın.
Uygulamanızın, kullanıcının cihazı previewLayout özelliğini desteklemediğinde previewImage özelliğini kullanabilmesi için hem previewLayout hem de previewImage özelliklerini belirtmenizi öneririz. previewLayout özelliği, previewImage özelliğine göre önceliklidir.
Widget önizlemeleriyle geriye dönük uyumluluk
Android 11 (API düzeyi 30) veya önceki sürümlerdeki widget seçicilerin widget'ınızın önizlemelerini göstermesine ya da oluşturulan önizlemeler için yedek olarak izin vermek üzere previewImage özelliğini belirtin.
Widget'ın görünümünü değiştirirseniz önizleme resmini güncelleyin.
Dinamik öğeler içeren doğru önizlemeler oluşturma
Bu bölümde, koleksiyon görünümü olan bir widget'ın widget önizlemesinde birden fazla öğeyi görüntülemek için önerilen yaklaşım açıklanmaktadır. Koleksiyon görünümü, ListView, GridView veya StackView kullanan bir widget'tır. Bu durum, oluşturulan widget önizlemeleri için geçerli değildir.
Widget'ınız bu görünümlerden birini kullanıyorsa gerçek widget düzenini doğrudan sağlayarak ölçeklenebilir bir önizleme oluşturmak, widget önizlemesinde öğe gösterilmediğinde deneyimi olumsuz etkiler. Bunun nedeni, koleksiyon görünümü verilerinin çalışma zamanında dinamik olarak ayarlanması ve Şekil 1'de gösterilen resme benzemesidir.
Koleksiyon görünümleri içeren widget'ların önizlemelerinin widget seçicide düzgün şekilde gösterilmesi için yalnızca önizleme için ayrılmış ayrı bir düzen dosyası kullanmanızı öneririz. Bu ayrı düzen dosyası aşağıdakileri içermelidir:
- Gerçek widget düzeni.
- Sahte öğeler içeren bir yer tutucu koleksiyon görünümü. Örneğin, birkaç sahte liste öğesi içeren bir yer tutucu
LinearLayoutsağlayarakListViewöğesini taklit edebilirsiniz.
ListView için bir örnek göstermek üzere ayrı bir düzen dosyasıyla başlayın:
// res/layout/widget_preview.xml
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="@drawable/widget_background"
android:orientation="vertical">
// Include the actual widget layout that contains ListView.
<include
layout="@layout/widget_view"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
// The number of fake items you include depends on the values you provide
// for minHeight or targetCellHeight in the AppWidgetProviderInfo
// definition.
<TextView android:text="@string/fake_item1"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginVertical="?attr/appWidgetInternalPadding" />
<TextView android:text="@string/fake_item2"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginVertical="?attr/appWidgetInternalPadding" />
</LinearLayout>
AppWidgetProviderInfo meta verilerinin previewLayout özelliğini sağlarken önizleme düzeni dosyasını belirtin. initialLayout özelliği için gerçek widget düzenini belirtmeye devam edersiniz ve çalışma zamanında RemoteViews oluştururken gerçek widget düzenini kullanırsınız.
<appwidget-provider
previewLayout="@layout/widget_previe"
initialLayout="@layout/widget_view" />
Karmaşık liste öğeleri
Önceki bölümdeki örnekte, liste öğeleri TextView nesneleri olduğundan sahte liste öğeleri sağlanmaktadır. Öğeler karmaşık düzenlere sahipse sahte öğeler sağlamak daha karmaşık olabilir.
widget_list_item.xml içinde tanımlanan ve iki TextView nesnesinden oluşan bir liste öğesini ele alalım:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="wrap_content">
<TextView android:id="@id/title"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="@string/fake_title" />
<TextView android:id="@id/content"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="@string/fake_content" />
</LinearLayout>
Sahte liste öğeleri sağlamak için düzeni birden çok kez ekleyebilirsiniz ancak bu durumda her liste öğesi aynı olur. Benzersiz liste öğeleri sağlamak için aşağıdaki adımları uygulayın:
Metin değerleri için bir özellik grubu oluşturun:
<resources> <attr name="widgetTitle" format="string" /> <attr name="widgetContent" format="string" /> </resources>Metni ayarlamak için aşağıdaki özellikleri kullanın:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="wrap_content"> <TextView android:id="@id/title" android:layout_width="match_parent" android:layout_height="wrap_content" android:text="?widgetTitle" /> <TextView android:id="@id/content" android:layout_width="match_parent" android:layout_height="wrap_content" android:text="?widgetContent" /> </LinearLayout>Önizleme için gereken sayıda stil oluşturun. Her stildeki değerleri yeniden tanımlayın:
<resources> <style name="Theme.Widget.ListItem"> <item name="widgetTitle"></item> <item name="widgetContent"></item> </style> <style name="Theme.Widget.ListItem.Preview1"> <item name="widgetTitle">Fake Title 1</item> <item name="widgetContent">Fake content 1</item> </style> <style name="Theme.Widget.ListItem.Preview2"> <item name="widgetTitle">Fake title 2</item> <item name="widgetContent">Fake content 2</item> </style> </resources>Önizleme düzenindeki sahte öğelere stilleri uygulayın:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="wrap_content" ...> <include layout="@layout/widget_view" ... /> <include layout="@layout/widget_list_item" android:theme="@style/Theme.Widget.ListItem.Preview1" /> <include layout="@layout/widget_list_item" android:theme="@style/Theme.Widget.ListItem.Preview2" /> </LinearLayout>