Menambahkan pratinjau ke alat pilih widget

Untuk meningkatkan pengalaman pemilih 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 yang dinamis dan 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 widget dan live update di YouTube.

Menambahkan pratinjau yang dihasilkan

Untuk menampilkan Pratinjau Widget yang Dibuat di perangkat Android 15 atau yang lebih baru, tetapkan nilai compileSdk ke 35 atau yang lebih baru terlebih dahulu di file build.gradle modul agar dapat memberikan RemoteViews ke pemilih widget

Aplikasi dapat menggunakan setWidgetPreview di AppWidgetManager. Untuk mencegah penyalahgunaan dan mengurangi masalah kesehatan sistem, setWidgetPreview adalah API dengan pembatasan kapasitas. Batas defaultnya adalah sekitar dua panggilan per jam.

Tidak ada callback dari sistem untuk memberikan pratinjau, sehingga 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 pertama kali diluncurkan.
  • Anda dapat menyetel pratinjau setelah aplikasi memiliki data; misalnya, setelah login pengguna atau penyiapan awal.
  • Anda dapat menyiapkan tugas berkala untuk memperbarui pratinjau pada ritme yang dipilih.

Contoh berikut memuat resource tata letak widget XML dan menetapkannya 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)
)

Menambahkan pratinjau widget yang skalabel

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

Untuk menerapkan pratinjau widget yang skalabel, gunakan atribut previewLayout dari elemen appwidget-provider untuk menyediakan 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 Membuat pratinjau akurat yang menyertakan item dinamis.

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

Menambahkan pratinjau widget statis untuk kompatibilitas mundur

Agar pemilih widget di Android 11 (API level 30) atau yang lebih rendah dapat menampilkan pratinjau widget Anda, atau sebagai penggantian untuk pratinjau yang skalabel, tentukan atribut previewImage.

Jika Anda mengubah tampilan widget, perbarui gambar pratinjau.

Atribut ini juga digunakan sebagai pengganti 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 skalabel, bukan pratinjau yang dihasilkan.

Jika widget Anda menggunakan salah satu tampilan ini, membuat pratinjau yang skalabel dengan menyediakan tata letak widget yang sebenarnya secara langsung di previewLayout dapat menurunkan 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 koleksi ditampilkan dengan benar di pemilih widget, sebaiknya pertahankan file tata letak terpisah yang ditetapkan hanya untuk pratinjau. File tata letak terpisah ini harus menyertakan hal berikut:

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

Untuk mengilustrasikan contoh ListView, mulai 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 yang sebenarnya untuk atribut initialLayout dan menggunakan tata letak widget yang sebenarnya saat membuat RemoteViews saat runtime.

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

Item daftar yang kompleks

Contoh di bagian sebelumnya memberikan item daftar palsu, karena item daftar adalah objek TextView. Mungkin akan lebih rumit untuk menyediakan item palsu jika item tersebut adalah 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 yang unik, ikuti langkah-langkah berikut:

  1. Buat kumpulan atribut untuk nilai teks:

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

  2. Gunakan atribut ini untuk menetapkan 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 di 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>