Widget seçicinize önizleme ekleme

Uygulamanızın widget seçici deneyimini iyileştirmek için Android 15 ve sonraki sürümlerin yüklü olduğu cihazlarda oluşturulmuş bir widget önizlemesi, Android 12 ila Android 14 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 kullanıcının ana ekranında nasıl görüneceğini doğru bir şekilde yansıtır. Android 15 ve sonraki sürümlerde, push API aracılığıyla sağlanır. Yani uygulamanız, widget ana makinesinden açık bir istek almadan yaşam döngüsünün herhangi bir noktasında önizlemeyi sağlar.

Daha fazla bilgi için YouTube'da Uygulamanızı canlı haberler ve widget'larla zenginleştirme başlıklı videoyu izleyin.

Oluşturulan önizlemeleri ekleme

Oluşturulan widget önizlemelerini Android 15 veya sonraki sürümlerin yüklü olduğu cihazlarda göstermek için önce modülün build.gradle dosyasında compileSdk değerini 35 veya sonraki bir sürüme ayarlayarak widget seçiciye RemoteViews sağlayabilme özelliğini etkinleştirin.

Uygulamalar AppWidgetManager'da setWidgetPreview 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 aramadır.

Sistemden önizleme sağlamak için bir geri çağırma yoktur. Bu nedenle, uygulamanız setWidgetPreviews yöntemini ne zaman çağıracağına karar vermelidir. Güncelleme stratejisi, widget'ınızın kullanım alanına bağlıdır:

  • Widget'ta statik bilgiler varsa veya widget hızlı işlemse uygulama ilk başlatıldığında önizlemeyi ayarlayın.
  • Uygulamanızda veri olduğunda (ör. kullanıcı oturum açtıktan veya ilk kurulumdan sonra) önizlemeyi ayarlayabilirsiniz.
  • Önizlemeleri seçilen bir sıklıkta güncelleyecek periyodik bir görev ayarlayabilirsiniz.

Aşağıdaki örnekte, bir XML widget düzeni kaynağı yüklenir ve önizleme olarak ayarlanır. setWidgetPreview yönteminin bu snippet'te gösterilmesi için compileSdk derleme ayarının 35 veya daha yeni bir sürüm olması 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. Bunu, widget'ın varsayılan boyutuna ayarlanmış bir XML düzeni olarak sağlarsınız. Önceden widget önizlemesi statik bir çizilebilir kaynak olduğundan bazı durumlarda widget'ların ana ekrana eklendiklerinde nasıl göründüğünü doğru şekilde yansıtmayan önizlemeler gösteriliyordu.

Ölçeklenebilir widget önizlemeleri uygulamak için appwidget-provider öğesinin previewLayout özelliğini kullanarak XML düzeni sağlayın:

<appwidget-provider
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

Gerçek widget ile aynı düzeni kullanmanızı ve gerçekçi varsayılan veya test değerleri kullanmanızı öneririz. Çoğu uygulama aynı previewLayout ve initialLayout kullanır. Doğru önizleme düzenleri oluşturma konusunda rehberlik için Dinamik öğeler içeren doğru önizlemeler oluşturma başlıklı makaleyi inceleyin.

Kullanıcının cihazı previewLayout özelliğini desteklemiyorsa uygulamanızın previewImage özelliğini kullanabilmesi 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östermesini sağlamak ya da ölçeklenebilir önizlemeler için yedek olarak previewImage özelliğini belirtin.

Widget'ın görünümünü değiştirirseniz önizleme resmini güncelleyin.

Bu özellik, setWidgetPreview kullanarak bir önizleme ayarlamadıysanız oluşturulan önizlemeler için yedek olarak da kullanılır.

Dinamik öğeler içeren doğru önizlemeler oluşturma

Şekil 1: Liste öğesi göstermeyen bir widget önizlemesi.

Bu bölümde, koleksiyon görünümü içeren bir widget'ın (yani ListView, GridView veya StackView kullanan bir widget'ın) widget önizlemesinde birden fazla öğe göstermek 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 doğrudan previewLayout içinde gerçek widget düzenini sağlayarak ölçeklenebilir bir önizleme oluşturmak, widget önizlemesinde öğe gösterilmediğinde deneyimi olumsuz etkileyebilir. Bu durum, koleksiyon görünümü verilerinin çalışma zamanında dinamik olarak ayarlanması nedeniyle oluşur ve Şekil 1'de gösterilen resme benzer.

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 tasarlanmış ayrı bir düzen dosyası kullanmanızı öneririz. Bu ayrı düzen dosyası şunları 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 LinearLayout sağlayarak ListView öğesini taklit edebilirsiniz.

ListView örneğini göstermek için 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 eder ve çalışma zamanında RemoteViews oluştururken gerçek widget düzenini kullanırsınız.

<appwidget-provider
    previewLayout="@layout/widget_preview"
    initialLayout="@layout/widget_view" />

Karmaşık liste öğeleri

Önceki bölümdeki örnekte, liste öğeleri TextView nesneleri olduğu için sahte liste öğeleri sağlanmıştı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, her liste öğesinin aynı olmasına neden olur. Benzersiz liste öğeleri sağlamak için aşağıdaki adımları uygulayın:

  1. Metin değerleri için bir özellik grubu oluşturun:

    <resources>
    <attr name="widgetTitle" format="string" />
    <attr name="widgetContent" format="string" />
</resources>

  2. Metni ayarlamak için şu ö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>

  3. Ö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>

  4. Ö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>