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.
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. Android 15 ve sonraki sürümlerde, bunlar bir aktarma API'si aracılığıyla sağlanır. Bu, uygulamanızın, yaşam döngüsü boyunca herhangi bir noktada, widget barındırıcıdan açık bir istek almadan önizleme sağladığı anlamına gelir.
Daha fazla bilgi için YouTube'daki Uygulamanızı canlı güncellemeler ve widget'larla zenginleştirme başlıklı makaleyi inceleyin.
Oluşturulan önizlemeleri ekleme
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, AppWidgetManager içinde setWidgetPreview özelliğini 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.
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.
Aşağıdaki örnekte bir XML widget düzeni kaynağı yüklenir ve bu kaynak ö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)
)
Ö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 drawable 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şturma hakkında bilgi edinmek için Dinamik öğeler içeren doğru önizlemeler oluşturma başlıklı makaleyi inceleyin.
Uygulamanız, kullanıcının cihazı previewLayout özelliğini desteklemiyorsa previewImage özelliğini kullanmaya geri dönebilmesi için hem previewLayout hem de previewImage özelliklerini belirtmenizi öneririz. previewLayout özelliği, previewImage özelliğine göre önceliklidir.
Geriye dönük uyumluluk için statik widget önizlemeleri ekleme
Android 11 (API düzeyi 30) veya önceki sürümlerdeki widget seçicilerin widget'ınızın önizlemelerini göstermesine ya da ölçeklenebilir ö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.
Bu özellik, setWidgetPreview kullanarak bir önizleme oluşturmadıysanız oluşturulan önizlemeler için yedek olarak da kullanılır.
Dinamik öğeler içeren doğru önizlemeler oluşturma
Bu bölümde, koleksiyon görünümü olan bir widget'ın (yani ListView, GridView veya StackView kullanan bir widget) widget önizlemesinde birden fazla öğeyi görüntülemek için önerilen yaklaşım açıklanmaktadır. Bu, oluşturulan önizlemeler için değil, ölçeklenebilir widget önizlemeleri için geçerlidir.
Widget'ınız bu görünümlerden birini kullanıyorsa gerçek widget düzenini doğrudan previewLayout içinde sağlayarak ölçeklenebilir bir önizleme oluşturmak, widget önizlemesinde öğe gösterilmediğinde deneyimi olumsuz etkileyebilir. 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 ve çalışma zamanında RemoteViews oluştururken gerçek widget düzenini kullanmaya devam edersiniz.
<appwidget-provider
previewLayout="@layout/widget_preview"
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 bu ö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>