Mem-build UI dengan Glance

Halaman ini menjelaskan cara menangani ukuran dan menyediakan tata letak yang fleksibel dan responsif dengan Glance, menggunakan komponen Glance yang ada.

Gunakan Box, Column, dan Row

Glance memiliki tiga tata letak composable utama:

• Box: Menempatkan elemen di atas elemen lainnya. Hal ini berarti RelativeLayout.

• Column: Menempatkan elemen satu per satu di sumbu vertikal. Ini diterjemahkan menjadi LinearLayout dengan orientasi vertikal.

• Row: Menempatkan elemen satu per satu di sumbu horizontal. Hal ini berarti LinearLayout dengan orientasi horizontal.

Glance mendukung objek Scaffold. Tempatkan composable Column, Row, dan Box dalam objek Scaffold tertentu.

Gambar 1. Contoh tata letak dengan Column, Row, dan Box.

Poin Penting: Glance menyediakan pendekatan modern untuk mem-build widget aplikasi menggunakan Compose, tetapi dibatasi oleh batasan AppWidgets dan RemoteViews. Oleh karena itu, Glance menggunakan composable yang berbeda dari UI Jetpack Compose.

Setiap composable ini memungkinkan Anda menentukan perataan vertikal dan horizontal kontennya serta batasan lebar, tinggi, bobot, atau padding menggunakan pengubah. Selain itu, setiap turunan dapat menentukan pengubahnya untuk mengubah ruang dan penempatan di dalam induk.

Contoh berikut menunjukkan cara membuat Row yang mendistribusikan turunannya secara merata secara horizontal, seperti yang terlihat pada Gambar 1:

Row(modifier = GlanceModifier.fillMaxWidth().padding(16.dp)) {
    val modifier = GlanceModifier.defaultWeight()
    Text("first", modifier)
    Text("second", modifier)
    Text("third", modifier)
}
GlanceSnippets.kt

Row mengisi lebar maksimum yang tersedia, dan karena setiap turunan memiliki bobot yang sama, mereka berbagi ruang yang tersedia secara merata. Anda dapat menentukan bobot, ukuran, padding, atau perataan yang berbeda untuk menyesuaikan tata letak dengan kebutuhan Anda.

Catatan: Glance menerjemahkan composable-nya menjadi Views yang sebenarnya, menggunakan pengubah dan parameter yang ditentukan untuk membuat tampilan yang mendasarinya. Oleh karena itu, konsep Android View yang sama (seperti bobot) berlaku saat mem-build composable tertentu dengan Glance.

Menggunakan tata letak yang dapat di-scroll

Cara lain untuk menyediakan konten yang responsif adalah dengan membuatnya dapat di-scroll. Hal ini dapat dilakukan dengan composable LazyColumn. Composable ini memungkinkan Anda menentukan kumpulan item yang akan ditampilkan di dalam container yang dapat di-scroll di widget aplikasi.

Cuplikan berikut menunjukkan berbagai cara untuk menentukan item di dalam LazyColumn.

Anda dapat memberikan jumlah item:

// Remember to import Glance Composables
// import androidx.glance.appwidget.layout.LazyColumn

LazyColumn {
    items(10) { index: Int ->
        Text(
            text = "Item $index",
            modifier = GlanceModifier.fillMaxWidth()
        )
    }
}
GlanceSnippets.kt

Menyediakan item satu per satu:

LazyColumn {
    item {
        Text("First Item")
    }
    item {
        Text("Second Item")
    }
}
GlanceSnippets.kt

Berikan daftar atau array item:

LazyColumn {
    items(peopleNameList) { name ->
        Text(name)
    }
}
GlanceSnippets.kt

Anda juga dapat menggunakan kombinasi contoh sebelumnya:

LazyColumn {
    item {
        Text("Names:")
    }
    items(peopleNameList) { name ->
        Text(name)
    }

    // or in case you need the index:
    itemsIndexed(peopleNameList) { index, person ->
        Text("$person at index $index")
    }
}
GlanceSnippets.kt

Perhatikan bahwa cuplikan sebelumnya tidak menentukan itemId. Menentukan itemId membantu meningkatkan performa dan mempertahankan posisi scroll melalui daftar dan update appWidget dari Android 12 dan yang lebih baru (misalnya, saat menambahkan atau menghapus item dari daftar). Contoh berikut menunjukkan cara menentukan itemId:

items(
    items = peopleList,
    itemId = { person -> person.id.hashCode().toLong() }) { person ->
    Text(person.name)
}
GlanceSnippets.kt

Catatan: Glance menerjemahkan LazyColumn menjadi ListView dengan terjemahan item yang disediakan. Oleh karena itu, batasan dan pembatasan yang sama untuk koleksi RemoteViews juga berlaku. Batasan ini tidak berlaku jika Anda menggunakan Snap Scrolling, yang menggunakan Remote Compose, bukan RemoteViews.

Scroll Cepat

Scroll snap adalah animasi yang memungkinkan konten yang dapat di-scroll untuk diposisikan ke bagian atas penampung widget.

Video 1. Sisi kiri menampilkan item daftar yang tidak diposisikan secara pas saat di-scroll, sedangkan sisi kanan diposisikan secara pas.

Untuk menerapkan scroll snap, pastikan Anda memenuhi kondisi berikut:

• Update dependensi Glance Anda ke 1.3.0-alpha02 atau yang lebih tinggi.
• Tetapkan compileSdk ke 37 atau yang lebih tinggi, karena scroll snap didukung di perangkat yang menjalankan Android 17 dan yang lebih tinggi.
• Konfigurasikan LazyColumn Anda dengan VerticalScrollMode. Jika perangkat mendukung scroll snap, gunakan SnapScrollMatchHeight. Jika tidak, gunakan Normal.

Catatan: SnapScrollMatchHeight dirancang untuk saat setiap elemen turunan cocok dengan tinggi container induk, seperti pada gambar full bleed. Untuk memastikan bahwa tinggi yang diteruskan dari LocalSize.current ke SnapScrollMatchHeight secara akurat mencerminkan ruang yang tersedia di layar utama pengguna, gunakan SizeMode.Exact jika tidak, LocalSize.current akan menggunakan dimensi minimum yang ditentukan dalam XML metadata AppWidget Anda. Untuk mengetahui informasi selengkapnya, lihat Menentukan SizeMode.

Jika Anda menggunakan scroll snap dengan gambar, lihat Tata Letak Kanonis gambar bleed penuh.

@Composable
fun SnapScrollLayout() {
    val height = LocalSize.current.height
    val items = listOf(
        ColorItem(Color.Red, "Red"),
        ColorItem(Color.Yellow, "Yellow"),
        ColorItem(Color.Blue, "Blue")
    )

    val scrollMode = if (Build.VERSION.SDK_INT >= 37) {
        VerticalScrollMode.SnapScrollMatchHeight(height)
    } else {
        VerticalScrollMode.Normal
    }

    LazyColumn(
        verticalScrollMode = scrollMode
    ) {
        items(items) { item ->
            ColorCard(item, height)
        }
    }
}

@Composable
private fun ColorCard(item: ColorItem, height: Dp) {
    Box(
        modifier = GlanceModifier
            .background(item.color)
            .fillMaxWidth()
            .height(height),
        contentAlignment = Alignment.Center
    ) {
        Text(
            text = item.name,
            modifier = GlanceModifier.background(Color.White)
        )
    }
}
GlanceSnippets.kt

Menentukan SizeMode

Ukuran AppWidget dapat berbeda bergantung pada perangkat, pilihan pengguna, atau peluncur, jadi penting untuk menyediakan tata letak yang fleksibel seperti yang dijelaskan di halaman Menyediakan tata letak widget yang fleksibel. Glance menyederhanakan hal ini dengan definisi SizeMode dan nilai LocalSize. Bagian berikut menjelaskan ketiga mode tersebut.

SizeMode.Single

SizeMode.Single adalah mode default. Hal ini menunjukkan bahwa hanya satu jenis konten yang disediakan; yaitu, meskipun ukuran AppWidget yang tersedia berubah, ukuran konten tidak berubah.

class MyAppWidget : GlanceAppWidget() {

    override val sizeMode = SizeMode.Single

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // ...

        provideContent {
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        // Size will be the minimum size or resizable
        // size defined in the App Widget metadata
        val size = LocalSize.current
        // ...
    }
}
GlanceSnippets.kt

Saat menggunakan mode ini, pastikan:

• Nilai metadata ukuran minimum dan maksimum ditentukan dengan benar berdasarkan ukuran konten.
• Konten cukup fleksibel dalam rentang ukuran yang diharapkan.

Secara umum, Anda harus menggunakan mode ini jika:

a) AppWidget memiliki ukuran tetap, atau b) kontennya tidak berubah saat diubah ukurannya.

SizeMode.Responsive

Mode ini setara dengan menyediakan tata letak responsif, yang memungkinkan GlanceAppWidget menentukan kumpulan tata letak responsif yang dibatasi oleh ukuran tertentu. Untuk setiap ukuran yang ditentukan, konten dibuat dan dipetakan ke ukuran tertentu saat AppWidget dibuat atau diperbarui. Sistem kemudian memilih yang paling sesuai berdasarkan ukuran yang tersedia.

Catatan: Ukuran yang paling pas adalah salah satu dari DpSize yang disediakan yang sesuai dengan kotak pembatas yang tersedia dengan distorsi minimal. Jika tidak ada yang sesuai, yang terkecil akan digunakan.

Misalnya, di tujuan AppWidget, Anda dapat menentukan tiga ukuran dan kontennya:

class MyAppWidget : GlanceAppWidget() {

    companion object {
        private val SMALL_SQUARE = DpSize(100.dp, 100.dp)
        private val HORIZONTAL_RECTANGLE = DpSize(250.dp, 100.dp)
        private val BIG_SQUARE = DpSize(250.dp, 250.dp)
    }

    override val sizeMode = SizeMode.Responsive(
        setOf(
            SMALL_SQUARE,
            HORIZONTAL_RECTANGLE,
            BIG_SQUARE
        )
    )

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // ...

        provideContent {
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        // Size will be one of the sizes defined above.
        val size = LocalSize.current
        Column {
            if (size.height >= BIG_SQUARE.height) {
                Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp))
            }
            Row(horizontalAlignment = Alignment.CenterHorizontally) {
                Button()
                Button()
                if (size.width >= HORIZONTAL_RECTANGLE.width) {
                    Button("School")
                }
            }
            if (size.height >= BIG_SQUARE.height) {
                Text(text = "provided by X")
            }
        }
    }
}
GlanceSnippets.kt

Pada contoh sebelumnya, metode provideContent dipanggil tiga kali dan dipetakan ke ukuran yang ditentukan.

• Dalam panggilan pertama, ukuran dievaluasi menjadi 100x100. Konten tidak menyertakan tombol tambahan, serta teks atas dan bawah.
• Dalam panggilan kedua, ukuran dievaluasi menjadi 250x100. Konten menyertakan tombol tambahan, tetapi tidak menyertakan teks atas dan bawah.
• Dalam panggilan ketiga, ukuran dievaluasi ke 250x250. Kontennya mencakup tombol tambahan dan kedua teks.

SizeMode.Responsive adalah kombinasi dari dua mode lainnya, dan memungkinkan Anda menentukan konten responsif dalam batas yang telah ditentukan. Secara umum, mode ini berperforma lebih baik dan memungkinkan transisi yang lebih lancar saat AppWidget diubah ukurannya.

Catatan: Tata letak responsif diperkenalkan di Android 12. Sebelum Android 12, composable dipanggil untuk setiap ukuran yang dapat menampilkan widget aplikasi (mirip dengan SizeMode.Exact). Untuk setiap ukuran, tampilan terbaik akan dipilih, yaitu tampilan terbesar yang sesuai dengan ruang yang tersedia, atau tampilan terkecil jika tidak ada yang sesuai.

Tabel berikut menunjukkan nilai ukuran, bergantung pada SizeMode dan ukuran AppWidget yang tersedia:

Ukuran yang tersedia	105 x 110	203 x 112	72 x 72	203 x 150
SizeMode.Single	110 x 110	110 x 110	110 x 110	110 x 110
SizeMode.Exact	105 x 110	203 x 112	72 x 72	203 x 150
SizeMode.Responsive	80 x 100	80 x 100	80 x 100	150 x 120
* Nilai persisnya hanya untuk tujuan demo.

SizeMode.Exact

SizeMode.Exact setara dengan menyediakan tata letak yang tepat, yang meminta konten GlanceAppWidget setiap kali ukuran AppWidget yang tersedia berubah (misalnya, saat pengguna mengubah ukuran AppWidget di layar utama).

Misalnya, di widget tujuan, tombol tambahan dapat ditambahkan jika lebar yang tersedia lebih besar dari nilai tertentu.

class MyAppWidget : GlanceAppWidget() {

    override val sizeMode = SizeMode.Exact

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // ...

        provideContent {
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        // Size will be the size of the AppWidget
        val size = LocalSize.current
        Column {
            Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp))
            Row(horizontalAlignment = Alignment.CenterHorizontally) {
                Button()
                Button()
                if (size.width > 250.dp) {
                    Button("School")
                }
            }
        }
    }
}
GlanceSnippets.kt

Mode ini memberikan fleksibilitas yang lebih besar daripada mode lainnya, tetapi memiliki beberapa peringatan:

• AppWidget harus dibuat ulang sepenuhnya setiap kali ukuran berubah. Hal ini dapat menyebabkan masalah performa dan lompatan UI saat kontennya kompleks.
• Ukuran yang tersedia mungkin berbeda bergantung pada implementasi peluncur. Misalnya, jika peluncur tidak menyediakan daftar ukuran, ukuran minimum yang mungkin akan digunakan.
• Di perangkat pra-Android 12, logika penghitungan ukuran mungkin tidak berfungsi dalam semua situasi.

Secara umum, Anda harus menggunakan mode ini jika SizeMode.Responsive tidak dapat digunakan (yaitu, sekumpulan kecil tata letak responsif tidak memungkinkan).

Akses materi

Gunakan LocalContext.current untuk mengakses resource Android apa pun, seperti yang ditunjukkan dalam contoh berikut:

LocalContext.current.getString(R.string.glance_title)
GlanceSnippets.kt

Sebaiknya berikan ID resource secara langsung untuk mengurangi ukuran objek RemoteViews akhir dan mengaktifkan resource dinamis, seperti warna dinamis.

Composable dan metode menerima resource menggunakan "penyedia", seperti ImageProvider, atau menggunakan metode overload seperti GlanceModifier.background(R.color.blue). Contoh:

Column(
    modifier = GlanceModifier.background(R.color.default_widget_background)
) { /**...*/ }

Image(
    provider = ImageProvider(R.drawable.ic_logo),
    contentDescription = "My image",
)
GlanceSnippets.kt

Menangani teks

Glance 1.1.0 menyertakan API untuk menyetel gaya teks Anda. Tetapkan gaya teks menggunakan atribut fontSize, fontWeight, atau fontFamily dari class TextStyle.

fontFamily mendukung semua font sistem, seperti yang ditunjukkan dalam contoh berikut, tetapi font kustom di aplikasi tidak didukung:

Text(
    style = TextStyle(
        fontWeight = FontWeight.Bold,
        fontSize = 18.sp,
        fontFamily = FontFamily.Monospace
    ),
    text = "Example Text"
)
GlanceSnippets.kt

Menambahkan tombol majemuk

Tombol majemuk diperkenalkan di Android 12. Glance mendukung kompatibilitas mundur untuk jenis tombol gabungan berikut:

• Switch
• CheckBox
• RadioButton

Setiap tombol gabungan ini menampilkan tampilan yang dapat diklik yang mewakili status "dicentang".

var isApplesChecked by remember { mutableStateOf(false) }
var isEnabledSwitched by remember { mutableStateOf(false) }
var isRadioChecked by remember { mutableIntStateOf(0) }

CheckBox(
    checked = isApplesChecked,
    onCheckedChange = { isApplesChecked = !isApplesChecked },
    text = "Apples"
)

Switch(
    checked = isEnabledSwitched,
    onCheckedChange = { isEnabledSwitched = !isEnabledSwitched },
    text = "Enabled"
)

RadioButton(
    checked = isRadioChecked == 1,
    onClick = { isRadioChecked = 1 },
    text = "Checked"
)
GlanceSnippets.kt

Saat status berubah, lambda yang disediakan akan dipicu. Anda dapat menyimpan status yang dicentang, seperti yang ditunjukkan dalam contoh berikut:

class MyAppWidget : GlanceAppWidget() {

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        val myRepository = MyRepository.getInstance()

        provideContent {
            val scope = rememberCoroutineScope()

            val saveApple: (Boolean) -> Unit =
                { scope.launch { myRepository.saveApple(it) } }
            MyContent(saveApple)
        }
    }

    @Composable
    private fun MyContent(saveApple: (Boolean) -> Unit) {

        var isAppleChecked by remember { mutableStateOf(false) }

        Button(
            text = "Save",
            onClick = { saveApple(isAppleChecked) }
        )
    }
}
GlanceSnippets.kt

Anda juga dapat memberikan atribut colors ke CheckBox, Switch, dan RadioButton untuk menyesuaikan warnanya:

CheckBox(
    // ...
    colors = CheckboxDefaults.colors(
        checkedColor = ColorProvider(day = colorAccentDay, night = colorAccentNight),
        uncheckedColor = ColorProvider(day = Color.DarkGray, night = Color.LightGray)
    ),
    checked = isChecked,
    onCheckedChange = { isChecked = !isChecked }
)

Switch(
    // ...
    colors = SwitchDefaults.colors(
        checkedThumbColor = ColorProvider(day = Color.Red, night = Color.Cyan),
        uncheckedThumbColor = ColorProvider(day = Color.Green, night = Color.Magenta),
        checkedTrackColor = ColorProvider(day = Color.Blue, night = Color.Yellow),
        uncheckedTrackColor = ColorProvider(day = Color.Magenta, night = Color.Green)
    ),
    checked = isChecked,
    onCheckedChange = { isChecked = !isChecked },
    text = "Enabled"
)

RadioButton(
    // ...
    colors = RadioButtonDefaults.colors(
        checkedColor = ColorProvider(day = Color.Cyan, night = Color.Yellow),
        uncheckedColor = ColorProvider(day = Color.Red, night = Color.Blue)
    ),

    )
GlanceSnippets.kt

Catatan: Lihat contoh CompoundButtonAppWidget.kt untuk mengetahui contoh yang lebih mendetail.

Komponen tambahan

Glance 1.1.0 menyertakan rilis komponen tambahan, seperti yang dijelaskan dalam tabel berikut:

Nama	Gambar	Link referensi	Catatan tambahan
Tombol Terisi		Komponen
Tombol Garis Tepi		Komponen
Tombol Ikon		Komponen	Utama / Sekunder / Hanya ikon
Panel Judul		Komponen
Scaffold			Scaffold dan Panel judul berada dalam demo yang sama.

Untuk mengetahui informasi selengkapnya tentang spesifikasi desain, lihat desain komponen dalam kit desain ini di Figma.

Untuk mengetahui informasi selengkapnya tentang tata letak kanonis, buka Tata letak widget kanonis.