Membangun host widget

Layar beranda Android, yang tersedia di sebagian besar perangkat berbasis Android, memungkinkan sematan pengguna widget aplikasi (atau widget) untuk akses cepat ke konten. Jika Anda membuat penggantian layar utama atau Anda juga dapat mengizinkan pengguna menyematkan widget dengan menerapkan AppWidgetHost Ini bukanlah sesuatu yang perlu dilakukan oleh kebanyakan aplikasi, tetapi jika Anda membuat {i>host<i} sendiri, penting untuk memahami kewajiban kontrak yang disetujui oleh {i>host<i} secara implisit.

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

Berikut ini ringkasan kelas 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 {i>host<i} itu sendiri. ID ini tetap ada untuk semua penggunaan {i>host<i}. ID ini biasanya adalah nilai {i>hardcode<i} yang Anda tetapkan dalam aplikasi Anda.

  • ID widget aplikasi: setiap instance widget diberi ID unik pada saat itu dari binding. Lihat bindAppWidgetIdIfAllowed() dan, untuk detail selengkapnya, baca bagian Melakukan binding widget di halaman berikutnya. Tujuan host mendapatkan ID unik menggunakan allocateAppWidgetId() ID ini akan tetap ada selama masa pakai widget hingga dihapus dari {i>host<i}. Semua status khusus host—seperti ukuran dan lokasi widget — harus dipertahankan oleh paket hosting dan dikaitkan dengan ID widget aplikasi Anda.

  • Tampilan host widget aplikasi: pikirkan tentang AppWidgetHostView sebagai bingkai bahwa widget digabungkan setiap kali perlu ditampilkan. Widget adalah yang dikaitkan dengan AppWidgetHostView setiap kali widget di-inflate oleh {i>host<i}.

    • Secara default, sistem membuat AppWidgetHostView, tetapi host dapat membuat subclass AppWidgetHostView-nya sendiri dengan memperluasnya.
    • Mulai Android 12 (API level 31), AppWidgetHostView memperkenalkan tindakan setColorResources() dan resetColorResources() untuk menangani warna yang kelebihan beban secara dinamis. Host-nya adalah 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 ada di layar kunci atau layar utama. Informasi ini memungkinkan AppWidgetProvider menyesuaikan konten dan tampilan widget berdasarkan cara dan tempat data ditampilkan. Anda dapat menggunakan updateAppWidgetOptions() dan updateAppWidgetSize() untuk mengubah paket widget. Kedua metode ini memicu onAppWidgetOptionsChanged() callback ke AppWidgetProvider.

Melakukan binding widget

Saat pengguna menambahkan widget ke host, proses yang disebut binding akan terjadi. Pengikatan mengacu pada mengaitkan ID widget aplikasi tertentu dengan host tertentu, AppWidgetProvider spesifik.

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

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

Namun, ini hanyalah langkah pertama. Pada saat {i>runtime<i}, pengguna harus secara eksplisit memberikan izin akses ke aplikasi Anda untuk mengizinkan aplikasi menambahkan widget ke {i>host<i}. Untuk menguji apakah memiliki izin untuk menambahkan widget, gunakan bindAppWidgetIdIfAllowed() . Jika bindAppWidgetIdIfAllowed() menampilkan false, aplikasi Anda harus menampilkan dialog yang meminta pengguna untuk memberikan izin: "allow" untuk widget saat ini tambahan, atau "selalu izinkan" untuk mencakup semua penambahan widget di masa mendatang.

Cuplikan berikut menunjukkan contoh cara menampilkan dialog:

Kotlin

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

Java

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

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

Tanggung jawab host

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

Terlepas dari versi Android yang Anda targetkan, semua host memiliki tanggung jawab berikut:

  • Saat menambahkan widget, alokasikan ID widget seperti yang dijelaskan sebelumnya. Ketika seorang setelah widget dihapus dari host, panggil deleteAppWidgetId() untuk menghapus alokasi ID widget.

  • Saat menambahkan widget, periksa apakah aktivitas konfigurasi perlu diluncurkan. Biasanya, host perlu meluncurkan konfigurasi widget jika ada dan tidak ditandai sebagai opsional dengan menetapkan Tanda configuration_optional dan reconfigurable. Lihat Mengupdate widget dari aktivitas konfigurasi untuk mengetahui detailnya. Langkah ini diperlukan bagi banyak widget agar dapat ditampilkan.

  • Widget menentukan lebar dan tinggi default di AppWidgetProviderInfo {i>metadata<i}. Nilai-nilai ini ditentukan di dalam sel—mulai dari Android 12, jika targetCellWidth dan targetCellHeight adalah ditentukan—atau dp jika hanya minWidth dan minHeight yang ditentukan. Lihat Atribut ukuran widget.

    Pastikan widget ditata dengan minimal dp sebanyak ini. Sebagai misalnya, banyak {i>host<i} menyelaraskan ikon dan widget dalam {i>grid<i}. Dalam skenario ini, dengan secara {i>default<i}, {i>host<i} menambahkan widget menggunakan jumlah sel minimum yang memenuhi batasan minWidth dan minHeight.

Selain persyaratan yang tercantum di bagian sebelumnya, versi platform memperkenalkan fitur yang memberikan tanggung jawab baru pada {i>host<i}.

Menentukan pendekatan Anda berdasarkan versi Android yang ditargetkan

Android 12

Android 12 (level API 31) memaketkan List<SizeF> tambahan yang berisi daftar kemungkinan ukuran dalam dp yang dapat diambil instance widget dalam paket opsi. Jumlah ukuran yang diberikan bergantung pada penerapan host. Host biasanya menyediakan dua ukuran untuk ponsel—potret dan lanskap—serta empat ukuran untuk perangkat foldable.

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

Android 12 juga memperkenalkan maxResizeWidth dan maxResizeHeight dalam dp. Sebaiknya widget yang menggunakan minimal salah satu kriteria berikut atribut tidak melebihi ukuran yang ditentukan oleh atribut.

Referensi lainnya

  • Lihat dokumentasi referensi Glance.