Meningkatkan kualitas widget Anda

Halaman ini menyertakan detail untuk peningkatan widget opsional yang tersedia mulai Android 12 (API level 31). Fitur ini bersifat opsional, tetapi mudah diterapkan dan meningkatkan pengalaman widget pengguna Anda.

Gunakan warna dinamis

Mulai di Android 12, widget dapat menggunakan warna tema perangkat untuk tombol, latar belakang, dan komponen lainnya. Cara ini memberikan transisi dan konsistensi yang lebih lancar di berbagai widget.

Ada dua cara untuk mendapatkan warna dinamis:

• Gunakan tema default sistem (@android:style/Theme.DeviceDefault.DayNight) di tata letak root.

• Gunakan tema Material 3 (Theme.Material3.DynamicColors.DayNight) dari library Komponen Material untuk Android, yang tersedia mulai dari Komponen Material untuk Android v1.6.0.

Setelah tema ditetapkan di tata letak root, Anda dapat menggunakan atribut warna umum di root atau turunannya untuk mengambil warna dinamis.

Beberapa contoh atribut warna yang dapat Anda gunakan adalah sebagai berikut:

• ?attr/primary
• ?attr/primaryContainer
• ?attr/onPrimary
• ?attr/onPrimaryContainer

Pada contoh berikut yang menggunakan tema Material 3, warna tema perangkat adalah "ungu". Warna aksen dan latar belakang widget disesuaikan untuk mode terang dan gelap, seperti yang ditunjukkan pada gambar 1 dan 2.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="?attr/colorPrimaryContainer"
  android:theme="@style/Theme.Material3.DynamicColors.DayNight">

  <ImageView
    ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />

    <!-- Other widget content. -->

</LinearLayout>

Gambar 1. Widget dalam tema terang.

Gambar 2. Widget dalam tema gelap.

Tips: Sebaiknya gunakan tema Material 3 untuk mengikuti pedoman Desain Material demi konsistensi antara perangkat dan untuk kompatibilitas mundur.

Kompatibilitas mundur untuk warna dinamis

Warna dinamis hanya tersedia di perangkat yang menjalankan Android 12 atau yang lebih tinggi. Guna menyediakan tema kustom untuk versi yang lebih rendah, buat tema default dengan warna kustom dan penentu baru (values-v31) menggunakan atribut tema default.

Berikut adalah contoh penggunaan tema Material 3:

/values/styles.xml

<resources>
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    <!-- Override default colorBackground attribute with custom color. -->
    <item name="android:colorBackground">@color/my_background_color</item>

    <!-- Add other colors/attributes. -->

  </style>
</resources>

/values-v31/styles.xml

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

/layout/my_widget_layout.xml

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

Catatan: Lihat Gaya dan Tema untuk panduan mendalam tentang cara menangani berbagai gaya, warna, atribut, dan tema.

Mengaktifkan dukungan suara

Action Aplikasi memungkinkan Asisten Google menampilkan widget sebagai respons terhadap perintah suara pengguna yang relevan. Dengan mengonfigurasi widget untuk merespons intent bawaan (BII), aplikasi Anda dapat secara proaktif menampilkan widget di platform Asisten seperti Android dan Android Auto. Pengguna memiliki opsi untuk menyematkan widget yang ditampilkan oleh Asisten ke peluncur mereka, yang mendorong interaksi di masa mendatang.

Misalnya, Anda dapat mengonfigurasi widget ringkasan olahraga untuk aplikasi olahraga guna memenuhi perintah suara pengguna yang memicu BII GET_EXERCISE_OBSERVATION. Asisten akan secara proaktif menampilkan widget Anda saat pengguna memicu BII ini dengan membuat permintaan seperti, "Ok Google, berapa mil yang saya tempuh minggu ini di ExampleApp?"

Ada puluhan BII yang mencakup beberapa kategori interaksi pengguna, sehingga hampir semua aplikasi Android dapat meningkatkan widget mereka untuk suara. Untuk memulai, lihat Mengintegrasikan Action Aplikasi dengan widget Android.

Mengoptimalkan pengalaman alat pilih widget aplikasi

Android 12 memungkinkan Anda menambahkan pratinjau widget yang diskalakan dan deskripsi widget. Android 15 memungkinkan Anda meningkatkan pengalaman alat pilih widget untuk aplikasi dengan pratinjau widget yang dihasilkan.

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

Menambahkan pratinjau widget yang dihasilkan ke alat pilih widget

Aplikasi harus menetapkan nilai compileSdk ke 35 atau yang lebih baru dalam file build.gradle modul agar dapat menyediakan RemoteViews ke alat pilih widget di perangkat Android 15 atau yang lebih baru. Artinya, aplikasi dapat memperbarui konten di pemilih agar lebih mewakili apa yang dilihat pengguna.

Aplikasi dapat menggunakan metode AppWidgetManager, setWidgetPreview, dan getWidgetPreview untuk memperbarui tampilan widget dengan informasi terbaru dan yang dipersonalisasi.

Membuat pratinjau yang diperbarui dengan Jetpack Glance

Glance.compose menjalankan satu komposisi, sehingga tidak ada fungsi penangguhan, alur, atau panggilan asinkron serupa yang digunakan dalam isi composable Anda. Sebagai gantinya, Anda harus menggunakan data konstan.

Contoh berikut menggunakan Jetpack Glance untuk membuat pratinjau yang diperbarui. 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,
    ExampleAppWidget().compose(
        context = appContext
    ),
)
AppWidgetSnippets.kt

Membuat pratinjau yang diperbarui tanpa Jetpack Glance

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

Mulai Android 12, pratinjau widget yang ditampilkan di alat pilih widget bersifat skalabel. 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 membuat tata letak pratinjau yang akurat, lihat bagian berikut di halaman ini.

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

Pendekatan yang direkomendasikan untuk membuat pratinjau yang akurat

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>

Gambar 3. Pratinjau widget yang secara default muncul dalam area 3x3, tetapi dapat muat dalam area 3x1 karena tata letak XML-nya.

Untuk menampilkan pratinjau yang akurat, Anda dapat langsung memberikan tata letak widget yang sebenarnya dengan nilai default dengan menyelesaikan langkah-langkah berikut:

• Menetapkan android:text="@string/my_widget_item_fake_1" untuk elemen TextView.

  Catatan: Nilai yang ditetapkan menggunakan tag tools, seperti tools:text="@string/my_wdiget_item_fake_1", tidak ditampilkan dalam pratinjau.

• Menetapkan gambar atau ikon default atau placeholder, seperti android:src="@drawable/my_widget_icon", untuk komponen ImageView.

Tanpa nilai default, pratinjau mungkin menampilkan nilai yang salah atau kosong. Manfaat penting dari pendekatan ini adalah Anda dapat menyediakan konten pratinjau yang dilokalkan.

Untuk pendekatan yang direkomendasikan bagi pratinjau lebih kompleks yang berisi ListView, GridView, atau StackView, lihat Membuat pratinjau akurat yang menyertakan item dinamis untuk mengetahui detailnya.

Kompatibilitas mundur dengan pratinjau widget yang skalabel

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

Jika Anda mengubah tampilan widget, perbarui gambar pratinjau.

Menambahkan nama ke widget

Widget harus memiliki nama unik saat ditampilkan di pemilih widget.

Nama widget dimuat dari atribut label dari elemen receiver widget dalam file AndroidManifest.xml.

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

Menambahkan deskripsi untuk widget Anda

Mulai Android 12, berikan deskripsi untuk alat pilih widget yang akan ditampilkan untuk widget Anda.

Gambar 4. Pemilih widget contoh yang menampilkan widget dan deskripsinya.

Berikan deskripsi untuk widget Anda menggunakan atribut description dari elemen <appwidget-provider>:

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

Catatan: Buat ringkas. Tidak ada batas karakter, tetapi representasi dan ruang yang tersedia untuk deskripsi mungkin berbeda bergantung pada perangkat.

Anda dapat menggunakan atribut descriptionRes di versi Android sebelumnya, tetapi akan diabaikan oleh alat pilih widget.

Mengaktifkan transisi yang lebih lancar

Di Android 12, peluncur memberikan transisi yang lebih lancar saat pengguna meluncurkan aplikasi Anda dari widget.

Untuk mengaktifkan transisi yang telah ditingkatkan ini, gunakan @android:id/background atau android.R.id.background untuk mengidentifikasi elemen latar belakang Anda:

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

Peringatan: Hindari penggunaan trampolin siaran. Mulai Android 12, aplikasi masih dapat meluncurkan aktivitas dari layanan atau penerima siaran jika dimulai dari PendingIntent klik widget. Namun, animasi aplikasi baru tidak digunakan untuk aplikasi yang diluncurkan dari layanan atau penerima siaran, yang menyebabkan pengalaman pengguna yang buruk.

Aplikasi Anda dapat menggunakan @android:id/background di Android versi sebelumnya tanpa mengalami error, tetapi akan diabaikan.

Menggunakan modifikasi runtime RemoteView

Mulai dari Android 12, Anda dapat memanfaatkan beberapa metode RemoteViews yang menyediakan modifikasi runtime atribut RemoteViews. Lihat referensi RemoteViews API untuk mengetahui daftar lengkap metode yang ditambahkan.

Contoh kode berikut menunjukkan cara menggunakan beberapa metode ini.

Kotlin

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList())

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)

Java

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList());

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);