Menambahkan pratinjau yang dibuat ke alat pilih widget

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

Untuk meningkatkan pengalaman alat pilih widget aplikasi Anda, 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.

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

Menyiapkan aplikasi untuk pratinjau widget yang dibuat

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 kemudian dapat menggunakan setWidgetPreview di GlanceAppWidgetManager atau AppWidgetManager. Untuk mencegah penyalahgunaan dan mengurangi masalah kesehatan sistem, setWidgetPreview adalah API dengan batas kapasitas. Batas defaultnya adalah sekitar dua panggilan per jam.

Membuat pratinjau yang diperbarui dengan Jetpack Glance

Untuk widget yang dibuat dengan Jetpack Glance, lakukan hal berikut:

  1. Ganti fungsi GlanceAppWidget.providePreview untuk menyediakan konten composable untuk pratinjau. Seperti yang Anda lakukan di provideGlance, muat data aplikasi Anda dan teruskan ke composable konten widget, untuk memastikan pratinjau menampilkan data yang akurat. Tidak seperti provideGlance, ini adalah komposisi tunggal tanpa rekomposisi atau efek.

  2. Panggil GlanceAppWidgetManager.setWidgetPreviews untuk membuat dan memublikasikan pratinjau.

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.

Memecahkan Masalah Pratinjau yang Dibuat

Masalah umum adalah setelah Anda membuat pratinjau, gambar, ikon, atau composable lainnya mungkin hilang dari gambar pratinjau, relatif terhadap ukuran pelepasan widget. Ukuran drop ini ditentukan oleh targetCellWidth dan targetCellHeight jika ditentukan, atau oleh minWidth dan minHeight dalam file info penyedia widget aplikasi.

Hal ini terjadi karena Android, secara default, hanya merender composable yang terlihat pada ukuran minimum widget. Dengan kata lain, Android menetapkan previewSizeMode ke SizeMode.Single secara default. Composable ini menggunakan android:minHeight dan android:minWidth dalam XML info penyedia widget aplikasi untuk menentukan composable mana yang akan digambar.

Untuk memperbaikinya, ganti previewSizeMode di GlanceAppWidget dan tetapkan ke SizeMode.Responsive, dengan memberikan serangkaian nilai DpSize. Hal ini memberi tahu Android semua ukuran tata letak yang perlu dirender untuk pratinjau, yang memastikan semua elemen ditampilkan dengan benar.

Mengoptimalkan untuk faktor bentuk tertentu. Berikan 1 atau 2 ukuran yang dimulai dari minimum dan mengikuti titik henti sementara widget Anda. Tentukan setidaknya satu gambar untuk kompatibilitas mundur. Anda dapat menemukan nilai DP minimum yang sesuai untuk berbagai ukuran petak di panduan desain widget.

Membuat pratinjau yang diperbarui tanpa Jetpack Glance

Anda dapat menggunakan RemoteViews tanpa Glance. 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 skalabel ke alat pilih widget

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 aktual, 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 bagian berikut di halaman ini.

Sebaiknya tentukan atribut previewLayout dan previewImage, agar aplikasi Anda dapat melakukan penggantian ke penggunaan previewImage jika perangkat pengguna tidak mendukung previewLayout. Atribut previewLayout lebih diprioritaskan daripada atribut previewImage.

Kompatibilitas mundur dengan pratinjau widget

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

Jika Anda mengubah tampilan widget, perbarui gambar pratinjau.

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 tidak berlaku untuk pratinjau widget yang dibuat.

Jika widget Anda menggunakan salah satu tampilan ini, membuat pratinjau yang dapat diskalakan dengan menyediakan tata letak widget yang sebenarnya secara langsung akan 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 koleksi 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_previe"
    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>
Sebelumnya
Membuat widget aplikasi dengan Glance
Berikutnya
Menangani error dengan Glance