Membuat widget sederhana

Mencoba cara Compose
Jetpack Compose adalah toolkit UI yang direkomendasikan untuk Android. Pelajari cara membuat widget menggunakan API gaya Compose.
Jetpack Glance →

Widget aplikasi adalah tampilan aplikasi mini yang dapat disematkan di aplikasi lain—seperti layar utama—dan menerima update berkala. Tampilan ini disebut sebagai widget dalam antarmuka pengguna, dan Anda dapat memublikasikannya dengan penyedia widget aplikasi (atau penyedia widget). Komponen aplikasi yang menyimpan widget lain disebut host widget aplikasi (atau host widget). Gambar 1 menunjukkan contoh widget musik:

Contoh widget musik
Gambar 1. Contoh widget musik.

Dokumen ini menjelaskan cara memublikasikan widget menggunakan penyedia widget. Untuk mengetahui detail tentang cara membuat AppWidgetHost Anda sendiri untuk menghosting widget aplikasi, lihat Membuat host widget.

Untuk mengetahui informasi tentang cara mendesain widget, lihat Ringkasan widget aplikasi.

Komponen widget

Untuk membuat widget, Anda memerlukan komponen dasar berikut:

AppWidgetProviderInfo objek
Menjelaskan metadata untuk widget, seperti tata letak widget, frekuensi update, dan AppWidgetProvider class. AppWidgetProviderInfo adalah ditentukan dalam XML, seperti yang dijelaskan dalam dokumen ini.
AppWidgetProvider class
Menentukan metode dasar yang memungkinkan Anda berinteraksi secara terprogram dengan widget. Melalui metode ini, Anda akan menerima siaran saat widget diupdate, diaktifkan, dinonaktifkan, atau dihapus. Anda mendeklarasikan AppWidgetProvider dalam manifes lalu menerapkannya, seperti yang dijelaskan dalam dokumen ini.
Tata letak tampilan
Menentukan tata letak awal untuk widget. Tata letak ditentukan dalam XML, seperti yang dijelaskan dalam dokumen ini.

Gambar 2 menunjukkan bagaimana komponen ini sesuai dengan alur pemrosesan widget aplikasi secara keseluruhan.

Alur pemrosesan widget aplikasi
Gambar 2. Alur pemrosesan widget aplikasi.

Jika widget Anda memerlukan konfigurasi pengguna, terapkan aktivitas konfigurasi widget aplikasi. Aktivitas ini memungkinkan pengguna mengubah setelan widget—misalnya, zona waktu untuk widget jam.

Kami juga merekomendasikan peningkatan berikut: tata letak widget yang fleksibel, peningkatan lain-lain, widget lanjutan, widget koleksi, dan membuat host widget.

Mendeklarasikan XML AppWidgetProviderInfo

Menentukan setelan metadata (seperti ukuran sel default, batasan pengubahan ukuran, dan frekuensi update) sama persis di seluruh widget berbasis Tampilan tradisional dan Glance.

Untuk mempelajari cara menentukan dan mengonfigurasi file XML metadata, lihat bagian Mendeklarasikan XML AppWidgetProviderInfo yang mengutamakan Compose dalam dokumentasi Glance.

Menggunakan class AppWidgetProvider untuk menangani siaran widget

Mekanisme penerima siaran platform, filter deklarasi manifes, dan loop peristiwa siklus proses disatukan di bawah platform. Dalam pengembangan yang mengutamakan Compose, siaran ini diatur menggunakan wrapper GlanceAppWidgetReceiver.

Untuk memahami cara mendaftarkan penerima dalam manifes dan menerapkan penggantian siklus proses yang kompatibel dengan Hilt, lihat bagian Menggunakan class AppWidgetProvider yang mengutamakan Compose untuk menangani siaran dalam dokumentasi Glance.

Membuat tata letak widget

Anda harus menentukan tata letak awal untuk widget Anda dalam XML dan menyimpannya dalam direktori res/layout/ project. Lihat Panduan desain untuk mengetahui detail selengkapnya.

Membuat tata letak widget cukup mudah jika Anda memahami tata letak. Namun, perlu diketahui bahwa tata letak widget didasarkan pada RemoteViews, yang tidak mendukung setiap jenis tata letak atau widget tampilan. Anda tidak dapat menggunakan tampilan kustom atau sub-class tampilan yang didukung oleh RemoteViews.

RemoteViews juga mendukung ViewStub, yang merupakan View tidak terlihat berukuran nol yang dapat digunakan untuk memperluas resource tata letak sesuai keinginan pada waktu proses.

Dukungan untuk perilaku stateful

Android 12 menambahkan dukungan untuk perilaku stateful menggunakan komponen yang ada berikut:

Widget tetap stateless. Aplikasi Anda harus menyimpan status dan mendaftar peristiwa perubahan status.

Contoh widget daftar belanja yang menampilkan perilaku stateful
Gambar 3. Contoh perilaku stateful.

Contoh kode berikut menunjukkan cara menerapkan komponen ini.

Kotlin

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
        R.id.my_checkbox,
        RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

Java

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));

Sediakan dua tata letak: satu menargetkan perangkat yang menjalankan Android 12 atau yang lebih tinggi di res/layout-v31, dan yang lain menargetkan Android 11 atau yang lebih rendah di folder res/layout default.

Menerapkan sudut bulat

Menghitung latar belakang luar dan radius proporsional dalam adalah standar dan dibagikan. Dalam pengembangan yang mengutamakan Compose, hal ini dapat ditetapkan secara dinamis di Kotlin bersama dengan resource tema kustom.

Untuk menerapkan radius sudut atau menyiapkan gaya dinamis untuk perangkat Android lama, lihat bagian Menerapkan sudut bulat yang mengutamakan Compose dalam dokumentasi Glance.