Membuat widget aplikasi dengan Glance

Bagian berikut menjelaskan cara membuat widget aplikasi dasar dengan Glance.

Mendeklarasikan AppWidget di Manifes

Setelah menyelesaikan langkah-langkah penyiapan, deklarasikan AppWidget dan metadatanya di aplikasi Anda.

1. Perluas penerima AppWidget dari GlanceAppWidgetReceiver:

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
       override val glanceAppWidget: GlanceAppWidget = TODO("Create GlanceAppWidget")
   }
   GlanceSnippets.kt

2. Daftarkan penyedia widget aplikasi di file AndroidManifest.xml dan file metadata terkait:

       <receiver android:name=".glance.MyReceiver"
       android:exported="true">
       <intent-filter>
           <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
       </intent-filter>
       <meta-data
           android:name="android.appwidget.provider"
           android:resource="@xml/my_app_widget_info" />
   </receiver>
   AndroidManifest.xml
   

Menambahkan metadata AppWidgetProviderInfo

Selanjutnya, ikuti panduan Membuat widget untuk membuat dan menentukan info widget aplikasi di file @xml/my_app_widget_info.

Satu-satunya perbedaan untuk Glance adalah tidak ada XML initialLayout, tetapi Anda harus menentukannya. Anda dapat menggunakan tata letak pemuatan standar yang disediakan di library:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/glance_default_loading_layout">
</appwidget-provider>
my_app_widget_info.xml

Mendeklarasikan XML AppWidgetProviderInfo

Objek AppWidgetProviderInfo menentukan kualitas penting widget Anda. Tentukan AppWidgetProviderInfo di file resource metadata XML (res/xml/my_app_widget_info.xml) di dalam elemen <appwidget-provider>:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/glance_default_loading_layout"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

Atribut ukuran widget

Layar utama default menentukan posisi widget dalam jendelanya berdasarkan petak sel yang memiliki tinggi dan lebar yang ditentukan. Sebagian besar layar utama hanya memungkinkan widget mengambil ukuran yang merupakan kelipatan bilangan bulat dari sel petak—misalnya, dua sel secara horizontal dengan tiga sel secara vertikal.

Atribut ukuran widget memungkinkan Anda menentukan ukuran default untuk widget dan memberikan batas bawah dan atas pada ukuran widget. Dalam konteks ini, ukuran default widget adalah ukuran yang diambil widget saat pertama kali ditambahkan ke layar utama.

Tabel berikut menjelaskan atribut <appwidget-provider> yang berkaitan dengan ukuran widget:

Contoh

Untuk mengilustrasikan pengaruh atribut dalam tabel sebelumnya terhadap ukuran widget, asumsikan spesifikasi berikut:

• Sel petak memiliki lebar 30 dp dan tinggi 50 dp.
• Spesifikasi atribut berikut disediakan:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

Mulai Android 12:

Gunakan atribut targetCellWidth dan targetCellHeight sebagai ukuran default widget.

Ukuran widget adalah 2x2 secara default. Ukuran widget dapat diubah menjadi 2x1 atau hingga 4x3.

Android 11 dan yang lebih rendah:

Gunakan atribut minWidth dan minHeight untuk menghitung ukuran default widget.

Lebar default = Math.ceil(80 / 30) = 3

Tinggi default = Math.ceil(80 / 50) = 2

Ukuran widget adalah 3x2 secara default. Ukuran widget dapat diubah menjadi 2x1 atau hingga layar penuh.

Atribut widget tambahan

Tabel berikut menjelaskan atribut <appwidget-provider> yang berkaitan dengan kualitas selain ukuran widget.

Menentukan GlanceAppWidget

1. Buat class baru yang memperluas dari GlanceAppWidget dan mengganti metode provideGlance. Ini adalah metode tempat Anda dapat memuat data yang diperlukan untuk merender widget:

   class MyAppWidget : GlanceAppWidget() {
   
       override suspend fun provideGlance(context: Context, id: GlanceId) {
   
           // In this method, load data needed to render the AppWidget.
           // Use `withContext` to switch to another thread for long running
           // operations.
   
           provideContent {
               // create your AppWidget here
               Text("Hello World")
           }
       }
   }
   GlanceSnippets.kt

2. Buat instance di glanceAppWidget pada GlanceAppWidgetReceiver Anda:

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
   
       // Let MyAppWidgetReceiver know which GlanceAppWidget to use
       override val glanceAppWidget: GlanceAppWidget = MyAppWidget()
   }
   GlanceSnippets.kt

Anda kini telah mengonfigurasi AppWidget menggunakan Glance.

Menggunakan class GlanceAppWidgetReceiver untuk menangani siaran widget

Widget koordinat GlanceAppWidgetReceiver menyiarkan dan update status platform dengan memperluas AppWidgetProvider yang mendasarinya. Class ini menerima peristiwa platform saat widget Anda diupdate, dihapus, diaktifkan, atau dinonaktifkan, dan menerjemahkannya ke dalam permintaan siklus proses Compose.

Mendeklarasikan widget di manifes

Deklarasikan subclass class GlanceAppWidgetReceiver sebagai penerima siaran di file AndroidManifest.xml:

<receiver android:name="ExampleAppWidgetReceiver"
          android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/my_app_widget_info" />
</receiver>

Elemen <receiver> memerlukan atribut android:name yang menentukan class penerima. Penerima harus menerima tindakan siaran ACTION_APPWIDGET_UPDATE di dalam <intent-filter>.

Elemen <meta-data> harus mengidentifikasi namanya sebagai android.appwidget.provider, dan atribut android:resource harus mengarah ke resource metadata XML AppWidgetProviderInfo (@xml/my_app_widget_info).

Menerapkan class GlanceAppWidgetReceiver

Di Glance, Anda memperluas GlanceAppWidgetReceiver , bukan AppWidgetProvider secara langsung. Terapkan dengan menautkan penerima ke instance GlanceAppWidget. Callback utama yang tersedia di GlanceAppWidgetReceiver beroperasi sebagai berikut:

• onUpdate(): Diganti secara otomatis oleh Glance untuk menjalankan update komposisi. Jika Anda mengganti onUpdate secara manual, Anda harus memanggil super.onUpdate agar Glance dapat berhasil meluncurkan thread komposisi.
• onAppWidgetOptionsChanged(): Dipanggil saat widget pertama kali ditempatkan atau diubah ukurannya. Glance membaca item paket opsi di balik layar sehingga tata letak Anda menyesuaikan dengan lancar berdasarkan dimensi runtime.
• onDeleted(Context, IntArray): Dipanggil setiap kali instance widget tertentu dihapus oleh pengguna.
• onEnabled(Context): Dipicu saat instance pertama widget Anda berhasil dibuat. Sangat baik untuk menjalankan migrasi global.
• onDisabled(Context): Dipanggil saat instance penyedia aktif terakhir dihapus.
• onReceive(Context, Intent): Mencegat setiap siaran platform sebelum metode callback tertentu. Anda harus memastikan bahwa logika penerima kustom yang Anda tulis memanggil super.onReceive(context, intent) dan tidak boleh memanggil goAsync sendiri karena Glance otomatis merutekan pekerjaan secara asinkron.

Menerima intent siaran widget

Di balik layar, GlanceAppWidgetReceiver memfilter dan menangani intent siaran widget platform dasar berikut:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

Membuat UI

Cuplikan berikut menunjukkan cara membuat UI:

/* Import Glance Composables
 In the event there is a name clash with the Compose classes of the same name,
 you may rename the imports per https://kotlinlang.org/docs/packages.html#imports
 using the `as` keyword.

import androidx.glance.Button
import androidx.glance.layout.Column
import androidx.glance.layout.Row
import androidx.glance.text.Text
*/
class MyAppWidget : GlanceAppWidget() {

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // Load data needed to render the AppWidget.
        // Use `withContext` to switch to another thread for long running
        // operations.

        provideContent {
            // create your AppWidget here
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        Column(
            modifier = GlanceModifier.fillMaxSize(),
            verticalAlignment = Alignment.Top,
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp))
            Row(horizontalAlignment = Alignment.CenterHorizontally) {
                Button(
                    text = "Home",
                    onClick = actionStartActivity<MyActivity>()
                )
                Button(
                    text = "Work",
                    onClick = actionStartActivity<MyActivity>()
                )
            }
        }
    }
}
GlanceSnippets.kt

Contoh kode sebelumnya melakukan hal berikut:

• Di tingkat atas Column, item ditempatkan secara vertikal satu demi satu.
• Column memperluas ukurannya agar sesuai dengan ruang yang tersedia (melalui GlanceModifier dan menyejajarkan kontennya ke atas (verticalAlignment) serta memusatkannya secara horizontal (horizontalAlignment).
• Konten Column ditentukan menggunakan lambda. Urutannya penting.
  • Item pertama di Column adalah komponen Text dengan padding 12.dp.
  • Item kedua adalah Row, tempat item ditempatkan secara horizontal satu demi satu, dengan dua Buttons yang dipusatkan secara horizontal (horizontalAlignment). Tampilan akhir bergantung pada ruang yang tersedia. Gambar berikut adalah contoh tampilannya:

Anda dapat mengubah nilai perataan atau menerapkan nilai pengubah yang berbeda (seperti padding) untuk mengubah penempatan dan ukuran komponen. Lihat dokumentasi referensi untuk mengetahui daftar lengkap komponen, parameter, dan pengubah yang tersedia untuk setiap class.

Menerapkan sudut bulat

Android 12 memperkenalkan parameter sistem untuk menyesuaikan radius sudut widget aplikasi Anda secara dinamis:

• system_app_widget_background_radius: Menentukan radius sudut penampung latar belakang widget (tidak boleh lebih besar dari 28 dp).
• Radius dalam: Untuk mencegah kliping konten, hitung radius proporsional untuk konten dalam Anda berdasarkan garis luar latar belakang sistem: systemRadiusValue - widgetPadding

Di Glance, Anda dapat menerapkan properti ukuran radius sudut secara dinamis dalam komposisi menggunakan GlanceModifier.cornerRadius(android.R.dimen.system_app_widget_background_radius).

Untuk kompatibilitas mundur di perangkat yang menjalankan Android 11 (level API 30) atau yang lebih rendah, terapkan atribut kustom dan penggantian resource tema kustom:

• /values/attrs.xml

  <resources>
  <attr name="backgroundRadius" format="dimension" />
  </resources>
  

• /values/styles.xml

  <resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
  </resources>
  

• /values-31/styles.xml

  <resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
  </resources>
  

• /drawable/my_widget_background.xml

  <shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  </shape>