Menambahkan pratinjau ke alat pilih widget

Untuk meningkatkan pengalaman alat pilih widget aplikasi, berikan pratinjau widget yang dihasilkan di perangkat Android 15 dan yang lebih baru, pratinjau widget yang diskalakan (dengan menentukan previewLayout) untuk perangkat Android 12 hingga Android 14, dan previewImage untuk versi yang lebih lama.

Pratinjau widget yang dihasilkan memungkinkan Anda membuat pratinjau dinamis dan yang dipersonalisasi untuk widget yang secara akurat mencerminkan tampilannya di layar utama pengguna. Untuk Android 15 dan yang lebih tinggi, pratinjau disediakan melalui push API, yang berarti aplikasi Anda menyediakan pratinjau kapan saja selama siklus prosesnya tanpa menerima permintaan eksplisit dari host widget.

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

Menambahkan pratinjau yang dihasilkan

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 dapat menggunakan setWidgetPreview di AppWidgetManager. Untuk mencegah penyalahgunaan dan mengurangi masalah kesehatan sistem, setWidgetPreview adalah API yang dibatasi kecepatan panggilannya. Batas defaultnya adalah sekitar dua panggilan per jam.

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.

Contoh berikut memuat resource tata letak widget XML dan menyetelnya sebagai pratinjau. Setelan build compileSdk 35 atau yang lebih baru diperlukan agar setWidgetPreview ditampilkan sebagai metode dalam cuplikan ini.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    RemoteViews("com.example", R.layout.widget_preview)
)
AppWidgetSnippets.kt

Menambahkan pratinjau widget yang skalabel

Mulai Android 12, pratinjau widget yang ditampilkan di pemilih widget dapat diskalakan. Anda menyediakannya sebagai tata letak XML yang disetel ke ukuran default widget. Sebelumnya, pratinjau widget adalah resource drawable statis yang dalam beberapa kasus menyebabkan pratinjau tidak menampilkan widget secara akurat saat ditambahkan ke layar utama.

Untuk menerapkan pratinjau widget skalabel, gunakan atribut previewLayout dari elemen appwidget-provider untuk memberikan tata letak XML:

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

Sebaiknya gunakan tata letak yang sama dengan widget sebenarnya, dengan nilai default atau pengujian yang realistis. Sebagian besar aplikasi menggunakan previewLayout dan initialLayout yang sama. Untuk panduan tentang cara membuat tata letak pratinjau yang akurat, lihat Membangun pratinjau akurat yang menyertakan item dinamis.

Sebaiknya tentukan atribut previewLayout dan previewImage, agar aplikasi Anda dapat menggunakan previewImage sebagai pengganti jika perangkat pengguna tidak mendukung previewLayout. Atribut previewLayout lebih diprioritaskan daripada atribut previewImage.

Menambahkan pratinjau widget statis untuk kompatibilitas mundur

Untuk mengizinkan alat pilih widget di Android 11 (level API 30) atau yang lebih rendah menampilkan pratinjau widget Anda, atau sebagai penggantian untuk pratinjau yang dapat diskalakan, tentukan atribut previewImage.

Jika Anda mengubah tampilan widget, perbarui gambar pratinjau.

Atribut ini juga digunakan sebagai penggantian untuk pratinjau yang dihasilkan jika Anda belum menetapkannya menggunakan setWidgetPreview.

Membuat pratinjau akurat yang menyertakan item dinamis

Gambar 1: Pratinjau widget yang tidak menampilkan item daftar.

Bagian ini menjelaskan pendekatan yang direkomendasikan untuk menampilkan beberapa item dalam pratinjau widget untuk widget dengan tampilan koleksi—yaitu, widget yang menggunakan ListView, GridView, atau StackView. Hal ini berlaku untuk pratinjau widget yang dapat diubah ukurannya, bukan pratinjau yang dibuat.

Jika widget Anda menggunakan salah satu tampilan ini, membuat pratinjau yang dapat diskalakan dengan menyediakan tata letak widget sebenarnya secara langsung di previewLayout dapat menurunkan kualitas pengalaman saat pratinjau widget tidak menampilkan item. Hal ini terjadi karena data tampilan koleksi ditetapkan secara dinamis saat runtime, dan terlihat mirip dengan gambar yang ditampilkan pada gambar 1.

Agar pratinjau widget dengan tampilan kumpulan ditampilkan dengan benar di pemilih widget, sebaiknya pertahankan file tata letak terpisah yang ditetapkan hanya untuk pratinjau. File tata letak terpisah ini harus mencakup hal berikut:

• Tata letak widget sebenarnya.
• Tampilan kumpulan placeholder dengan item palsu. Misalnya, Anda dapat meniru ListView dengan menyediakan placeholder LinearLayout dengan beberapa item daftar palsu.

Untuk mengilustrasikan contoh ListView, mulailah dengan file tata letak terpisah:

// 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>

Tentukan file tata letak pratinjau saat memberikan atribut previewLayout dari metadata AppWidgetProviderInfo. Anda tetap menentukan tata letak widget sebenarnya untuk atribut initialLayout dan menggunakan tata letak widget sebenarnya saat membuat RemoteViews saat runtime.

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

Item daftar kompleks

Contoh di bagian sebelumnya menyediakan item daftar palsu, karena item daftar adalah objek TextView. Penyediaan item palsu bisa lebih rumit jika itemnya memiliki tata letak yang kompleks.

Pertimbangkan item daftar yang ditentukan dalam widget_list_item.xml dan terdiri dari dua objek TextView:

<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>

Untuk menyediakan item daftar palsu, Anda dapat menyertakan tata letak beberapa kali, tetapi hal ini menyebabkan setiap item daftar menjadi identik. Untuk memberikan item daftar unik, ikuti langkah-langkah berikut:

1. Buat serangkaian atribut untuk nilai teks:

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

2. Gunakan atribut ini untuk menyetel teks:

   <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. Buat gaya sebanyak yang diperlukan untuk pratinjau. Tentukan ulang nilai di setiap gaya:

   <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. Terapkan gaya pada item palsu dalam tata letak pratinjau:

   <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>