Menambahkan pratinjau ke alat pilih widget

Untuk meningkatkan pengalaman alat pilih widget aplikasi Anda, berikan pratinjau widget yang dibuat 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 sebelumnya.

Pratinjau widget yang dibuat memungkinkan Anda membuat pratinjau dinamis dan dipersonalisasi untuk widget yang secara akurat mencerminkan tampilannya di layar utama pengguna. Untuk Android 15 dan yang lebih tinggi, pratinjau ini disediakan melalui push API, yang berarti aplikasi Anda memberikan 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 dibuat

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

Aplikasi dapat menggunakan setWidgetPreview di AppWidgetManager. Untuk mencegah penyalahgunaan dan mengurangi masalah kesehatan sistem, setWidgetPreview adalah API yang dibatasi kapasitasnya. 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 pembaruan bergantung pada kasus penggunaan widget Anda:

  • Jika widget memiliki informasi statis atau merupakan tindakan cepat, tetapkan pratinjau saat aplikasi pertama kali diluncurkan.
  • Anda dapat menetapkan 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 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)
)
AppWidgetSnippets.kt

Menambahkan pratinjau widget yang skalabel

Mulai Android 12, pratinjau widget yang ditampilkan di alat pilih 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 menampilkan widget secara akurat saat ditambahkan ke layar utama.

Untuk menerapkan pratinjau widget yang skalabel, gunakan atribut previewLayout dari elemen appwidget-provideruntuk 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 membuat tata letak pratinjau yang akurat, lihat Membuat pratinjau akurat yang menyertakan item dinamis.

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

Menambahkan pratinjau widget statis untuk kompatibilitas mundur

Untuk mengizinkan alat pilih widget di Android 11 (API level 30) atau yang lebih rendah 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 penggantian untuk pratinjau yang dibuat 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 dibuat.

Jika widget Anda menggunakan salah satu tampilan ini, membuat pratinjau yang skalabel dengan memberikan 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 di gambar 1.

Agar pratinjau widget dengan tampilan koleksi ditampilkan dengan benar di alat pilih 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 koleksi placeholder dengan item palsu. Misalnya, Anda dapat meniru ListView dengan menyediakan LinearLayout placeholder dengan beberapa item daftar palsu.

Untuk mengilustrasikan contoh untuk 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 yang kompleks

Contoh di bagian sebelumnya memberikan item daftar palsu, karena item daftar adalah TextView objek. Memberikan item palsu bisa lebih rumit jika itemnya 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 memberikan 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 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>