Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Membangun host widget

Layar utama Android, yang tersedia di sebagian besar perangkat yang didukung Android, memungkinkan pengguna menyematkan widget aplikasi (atau widget) untuk akses cepat ke konten. Jika Anda membuat pengganti layar utama atau aplikasi serupa, Anda juga dapat mengizinkan pengguna menyematkan widget dengan mengimplementasikan AppWidgetHost. Hal ini bukanlah sesuatu yang perlu dilakukan oleh sebagian besar aplikasi, tetapi jika Anda membuat host sendiri, penting untuk memahami kewajiban kontrak yang disetujui host secara implisit.

Halaman ini berfokus pada tanggung jawab yang terlibat dalam penerapan AppWidgetHost kustom. Untuk contoh spesifik cara mengimplementasikan AppWidgetHost, lihat kode sumber untuk layar utama Android LauncherAppWidgetHost.

Berikut adalah ringkasan class dan konsep utama yang terlibat dalam penerapan AppWidgetHost kustom:

Host widget aplikasi: AppWidgetHost menyediakan interaksi dengan layanan AppWidget untuk aplikasi yang menyematkan widget di UI-nya. AppWidgetHost harus memiliki ID yang unik dalam paket host itu sendiri. ID ini tetap ada di semua penggunaan host. ID biasanya merupakan nilai hardcode yang Anda tetapkan di aplikasi.
ID widget aplikasi: setiap instance widget diberi ID unik pada saat pengikatan. Lihat bindAppWidgetIdIfAllowed() dan, untuk mengetahui detail selengkapnya, lihat bagian Mengikat widget berikut. Host mendapatkan ID unik menggunakan allocateAppWidgetId(). ID ini tetap ada selama masa aktif widget hingga dihapus dari host. Setiap status khusus host—seperti ukuran dan lokasi widget—harus dipertahankan oleh paket hosting dan dikaitkan dengan ID widget aplikasi.
Tampilan host widget aplikasi: anggap AppWidgetHostView sebagai frame yang menggabungkan widget setiap kali perlu ditampilkan. Widget dikaitkan dengan AppWidgetHostView setiap kali widget di-inflate oleh host.
- Secara default, sistem akan membuat AppWidgetHostView, tetapi host dapat membuat subclass AppWidgetHostView-nya sendiri dengan memperluasnya.
- Mulai Android 12 (API level 31), AppWidgetHostView memperkenalkan metode setColorResources() dan resetColorResources() untuk menangani warna yang kelebihan beban secara dinamis. Host bertanggung jawab untuk menyediakan warna ke metode ini.
Paket opsi: AppWidgetHost menggunakan paket opsi untuk menyampaikan informasi ke AppWidgetProvider tentang cara widget ditampilkan—misalnya, daftar rentang ukuran—dan apakah widget berada di layar kunci atau layar utama. Informasi ini memungkinkan AppWidgetProvider menyesuaikan konten dan tampilan widget berdasarkan cara dan tempat widget ditampilkan. Anda dapat menggunakan updateAppWidgetOptions() dan updateAppWidgetSize() untuk mengubah paket widget. Kedua metode ini memicu callback onAppWidgetOptionsChanged() ke AppWidgetProvider.

Mengikat widget

Saat pengguna menambahkan widget ke host, proses yang disebut binding akan terjadi. Binding mengacu pada pengaitan ID widget aplikasi tertentu dengan host tertentu dan AppWidgetProvider tertentu.

Binding API juga memungkinkan host menyediakan UI kustom untuk binding. Untuk menggunakan proses ini, aplikasi Anda harus mendeklarasikan izin BIND_APPWIDGET dalam manifes host:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

Namun, ini hanyalah langkah pertama. Saat runtime, pengguna harus secara eksplisit memberikan izin ke aplikasi Anda agar dapat menambahkan widget ke host. Untuk menguji apakah aplikasi Anda memiliki izin untuk menambahkan widget, gunakan metode bindAppWidgetIdIfAllowed(). Jika bindAppWidgetIdIfAllowed() menampilkan false, aplikasi Anda harus menampilkan dialog yang meminta pengguna untuk memberikan izin: "izinkan" untuk penambahan widget saat ini, atau "selalu izinkan" untuk mencakup semua penambahan widget di masa mendatang.

Cuplikan berikut menunjukkan contoh cara menampilkan dialog:

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.provider)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)Host.kt

Host harus memeriksa apakah widget yang ditambahkan pengguna memerlukan konfigurasi. Untuk mengetahui informasi selengkapnya, lihat Memungkinkan pengguna mengonfigurasi widget aplikasi.

Tanggung jawab penyelenggara

Anda dapat menentukan sejumlah setelan konfigurasi untuk widget menggunakan metadata AppWidgetProviderInfo. Anda dapat mengambil opsi konfigurasi ini, yang dibahas secara lebih mendetail di bagian berikut, dari objek AppWidgetProviderInfo yang terkait dengan penyedia widget.

Semua host memiliki tanggung jawab berikut:

Saat menambahkan widget, alokasikan ID widget seperti yang dijelaskan sebelumnya. Saat widget dihapus dari host, panggil deleteAppWidgetId() untuk membatalkan alokasi ID widget.
Saat menambahkan widget, periksa apakah aktivitas konfigurasi perlu diluncurkan. Biasanya, host perlu meluncurkan aktivitas konfigurasi widget jika ada dan tidak ditandai sebagai opsional dengan menentukan flag configuration_optional dan reconfigurable. Lihat Mengupdate widget dari aktivitas konfigurasi untuk mengetahui detailnya. Langkah ini diperlukan untuk banyak widget sebelum dapat ditampilkan.

Catatan: Tangani kasus tidak biasa saat aktivitas konfigurasi tidak ditampilkan atau selesai dengan error.
Widget menentukan lebar dan tinggi default dalam metadata AppWidgetProviderInfo. Nilai ini ditentukan dalam sel—mulai Android 12, jika targetCellWidth dan targetCellHeight ditentukan—atau dp jika hanya minWidth dan minHeight yang ditentukan. Lihat Atribut ukuran widget.

Pastikan widget ditata dengan setidaknya jumlah dp ini. Misalnya, banyak host menyelaraskan ikon dan widget dalam petak. Dalam skenario ini, secara default, host menambahkan widget menggunakan jumlah minimum sel yang memenuhi batasan minWidth dan minHeight.

Tips tentang pendekatan Anda

Selain persyaratan yang tercantum di bagian sebelumnya, perhatikan tips berikut:

Paket opsi dapat berisi List<SizeF> yang berisi daftar kemungkinan ukuran dalam dp yang dapat diambil oleh instance widget. Jumlah ukuran yang disediakan bergantung pada implementasi host. Host biasanya menyediakan dua ukuran untuk ponsel—potret dan lanskap—dan empat ukuran untuk perangkat foldable.

Ada batas MAX_INIT_VIEW_COUNT (16) untuk jumlah RemoteViews berbeda yang dapat diberikan AppWidgetProvider ke RemoteViews. Karena objek AppWidgetProvider memetakan objek RemoteViews ke setiap ukuran di List<SizeF>, jangan berikan lebih dari MAX_INIT_VIEW_COUNT ukuran.

Saat widget menentukan atribut maxResizeWidth dan maxResizeHeight dalam dp, sebaiknya widget yang menggunakan setidaknya salah satu atribut ini tidak melebihi ukuran yang ditentukan oleh atribut.

Referensi lainnya

Lihat dokumentasi referensi Glance.