Membuat pengubah kustom

Compose menyediakan banyak pengubah untuk perilaku umum secara langsung, tetapi Anda juga dapat membuat pengubah kustom Anda sendiri.

Pengubah memiliki beberapa bagian:

• Factory pengubah
  • Ini adalah fungsi ekstensi di Modifier, yang menyediakan API idiomatis untuk pengubah Anda dan memungkinkan pengubah ditautkan dengan mudah. Factory pengubah menghasilkan elemen pengubah yang digunakan oleh Compose untuk mengubah UI Anda.
• Elemen pengubah
  • Di sinilah Anda dapat menerapkan perilaku pengubah.

Ada beberapa cara untuk menerapkan pengubah kustom, bergantung pada fungsi yang diperlukan. Sering kali, cara termudah untuk menerapkan pengubah kustom adalah hanya dengan menerapkan factory pengubah kustom yang menggabungkan factory pengubah lain yang telah ditentukan. Jika Anda memerlukan lebih banyak perilaku kustom, terapkan elemen pengubah menggunakan Modifier.Node API, yang merupakan level lebih rendah tetapi memberikan lebih banyak fleksibilitas.

Menautkan pengubah yang ada

Biasanya, Anda dapat membuat pengubah kustom hanya dengan menggunakan pengubah yang ada. Misalnya, Modifier.clip() diimplementasikan menggunakan pengubah graphicsLayer. Strategi ini menggunakan elemen pengubah yang ada, dan Anda menyediakan factory pengubah kustom Anda sendiri.

Sebelum menerapkan pengubah kustom Anda sendiri, lihat apakah Anda dapat menggunakan strategi yang sama.

fun Modifier.clip(shape: Shape) = graphicsLayer(shape = shape, clip = true)
CustomModifierSnippets.kt

Atau, jika Anda sering mengulangi grup pengubah yang sama, Anda dapat menggabungkannya ke dalam pengubah Anda sendiri:

fun Modifier.myBackground(color: Color) = padding(16.dp)
    .clip(RoundedCornerShape(8.dp))
    .background(color)
CustomModifierSnippets.kt

Membuat pengubah kustom menggunakan factory pengubah composable

Anda juga dapat membuat pengubah kustom menggunakan fungsi composable untuk meneruskan nilai ke pengubah yang ada. Ini dikenal sebagai factory pengubah composable.

Catatan: Dalam versi Compose sebelumnya, kami merekomendasikan pendekatan ini dan disarankan menggunakan composed {} melalui aturan lint. Setelah composed {} tidak direkomendasikan, aturan lint telah dihapus.

Menggunakan factory pengubah composable untuk membuat pengubah juga memungkinkan penggunaan API compose tingkat yang lebih tinggi, seperti animate*AsState dan Compose API animasi yang didukung status lainnya. Misalnya, cuplikan berikut menunjukkan pengubah yang menganimasikan perubahan alfa saat diaktifkan/dinonaktifkan:

@Composable
fun Modifier.fade(enable: Boolean): Modifier {
    val alpha by animateFloatAsState(if (enable) 0.5f else 1.0f)
    return this then Modifier.graphicsLayer { this.alpha = alpha }
}
CustomModifierSnippets.kt

Peringatan: Saat membuat pengubah kustom, jangan memutuskan rantai pengubah. Anda harus selalu mereferensikan this. Jika tidak, pengubah yang ditambahkan sebelumnya akan dihapus. Anda dapat menggunakan this then Modifier seperti dalam contoh sebelumnya atau secara implisit menggunakan return graphicsLayer { this.alpha = alpha }.

Jika pengubah kustom Anda adalah metode praktis untuk memberikan nilai default dari CompositionLocal, cara termudah untuk menerapkannya adalah dengan menggunakan factory pengubah composable:

@Composable
fun Modifier.fadedBackground(): Modifier {
    val color = LocalContentColor.current
    return this then Modifier.background(color.copy(alpha = 0.5f))
}
CustomModifierSnippets.kt

Pendekatan ini memiliki beberapa batasan yang dijelaskan di bawah.

Nilai CompositionLocal di-resolve di lokasi panggilan factory pengubah

Saat membuat pengubah kustom menggunakan factory pengubah composable, lokalitas komposisi mengambil nilai dari hierarki komposisi tempatnya dibuat, bukan digunakan. Hal ini dapat menyebabkan hasil yang tidak diharapkan. Misalnya, ambil contoh pengubah lokal komposisi di atas, yang diterapkan sedikit berbeda menggunakan fungsi composable:

@Composable
fun Modifier.myBackground(): Modifier {
    val color = LocalContentColor.current
    return this then Modifier.background(color.copy(alpha = 0.5f))
}

@Composable
fun MyScreen() {
    CompositionLocalProvider(LocalContentColor provides Color.Green) {
        // Background modifier created with green background
        val backgroundModifier = Modifier.myBackground()

        // LocalContentColor updated to red
        CompositionLocalProvider(LocalContentColor provides Color.Red) {

            // Box will have green background, not red as expected.
            Box(modifier = backgroundModifier)
        }
    }
}
CustomModifierSnippets.kt

Jika pengubah tidak berfungsi seperti yang Anda harapkan, gunakan Modifier.Node kustom, karena lokal komposisi akan di-resolve dengan benar di situs penggunaan dan dapat diangkat dengan aman.

Pengubah fungsi composable tidak pernah dilewati

Pengubah factory composable tidak pernah dilewati karena fungsi composable yang memiliki nilai yang ditampilkan tidak dapat dilewati. Ini berarti fungsi pengubah akan dipanggil pada setiap rekomposisi, yang mungkin mahal jika sering direkomposisi.

Pengubah fungsi composable harus dipanggil dalam fungsi composable

Seperti semua fungsi composable, pengubah factory composable harus dipanggil dari dalam komposisi. Ini membatasi tempat pengubah dapat diangkat, karena pengubah tidak dapat diangkat dari komposisi. Sebagai perbandingan, factory pengubah non-composable dapat diangkat dari fungsi composable untuk memungkinkan penggunaan kembali yang lebih mudah dan meningkatkan performa:

val extractedModifier = Modifier.background(Color.Red) // Hoisted to save allocations

@Composable
fun Modifier.composableModifier(): Modifier {
    val color = LocalContentColor.current.copy(alpha = 0.5f)
    return this then Modifier.background(color)
}

@Composable
fun MyComposable() {
    val composedModifier = Modifier.composableModifier() // Cannot be extracted any higher
}
CustomModifierSnippets.kt

Menerapkan perilaku pengubah kustom menggunakan Modifier.Node

Modifier.Node adalah API level yang lebih rendah untuk membuat pengubah di Compose. Ini adalah API yang sama dengan yang digunakan Compose untuk mengimplementasikan pengubahnya sendiri dan merupakan cara yang paling berperforma untuk membuat pengubah kustom.

Catatan: Ada API lain untuk membuat pengubah kustom, composed {}. API ini tidak lagi direkomendasikan karena masalah performa yang ditimbulkannya. Modifier.Node dirancang dari awal agar memiliki performa yang jauh lebih baik daripada pengubah yang disusun. Untuk detail selengkapnya tentang masalah dengan pengubah yang tersusun, lihat pembicaraan Android Dev Summit Mendalami Pengubah Compose.

Mengimplementasikan pengubah kustom menggunakan Modifier.Node

Ada tiga bagian dalam menerapkan pengubah kustom menggunakan Modifier.Node:

• Implementasi Modifier.Node yang menyimpan logika dan status pengubah Anda.
• ModifierNodeElement yang membuat dan memperbarui instance node pengubah.
• Factory pengubah opsional seperti yang dijelaskan di atas.

Class ModifierNodeElement bersifat stateless dan instance baru dialokasikan setiap rekomposisi, sedangkan class Modifier.Node dapat bersifat stateful dan akan tetap ada di beberapa rekomposisi, dan bahkan dapat digunakan kembali.

Bagian berikut menjelaskan setiap bagian dan menunjukkan contoh pembuatan pengubah kustom untuk menggambar lingkaran.

Modifier.Node

Implementasi Modifier.Node (dalam contoh ini, CircleNode) menerapkan fungsi pengubah kustom Anda.

// Modifier.Node
private class CircleNode(var color: Color) : DrawModifierNode, Modifier.Node() {
    override fun ContentDrawScope.draw() {
        drawCircle(color)
    }
}
CustomModifierSnippets.kt

Dalam contoh ini, fungsi ini menggambar lingkaran dengan warna yang diteruskan ke fungsi pengubah.

Node mengimplementasikan Modifier.Node serta nol atau beberapa jenis node. Ada berbagai jenis node berdasarkan fungsi yang diperlukan pengubah Anda. Contoh di atas harus dapat menggambar, sehingga mengimplementasikan DrawModifierNode, yang memungkinkannya mengganti metode gambar.

Jenis yang tersedia adalah sebagai berikut:

Node	Penggunaan	Contoh Link
LayoutModifierNode	Modifier.Node yang mengubah cara konten gabungannya diukur dan ditata.	Contoh
DrawModifierNode	Modifier.Node yang menggambar ke dalam ruang tata letak.	Contoh
CompositionLocalConsumerModifierNode	Dengan menerapkan antarmuka ini, Modifier.Node Anda dapat membaca lokal komposisi.	Contoh
SemanticsModifierNode	Modifier.Node yang menambahkan kunci/nilai semantik untuk digunakan dalam pengujian, aksesibilitas, dan kasus penggunaan serupa.	Contoh
PointerInputModifierNode	Modifier.Node yang menerima PointerInputChanges.	Contoh
ParentDataModifierNode	Modifier.Node yang menyediakan data ke tata letak induk.	Contoh
LayoutAwareModifierNode	Modifier.Node yang menerima callback onMeasured dan onPlaced.	Contoh
GlobalPositionAwareModifierNode	Modifier.Node yang menerima callback onGloballyPositioned dengan LayoutCoordinates akhir tata letak saat posisi global konten mungkin telah berubah.	Contoh
ObserverModifierNode	Modifier.Node yang mengimplementasikan ObserverNode dapat menyediakan implementasi onObservedReadsChanged-nya sendiri yang akan dipanggil sebagai respons terhadap perubahan pada objek snapshot yang dibaca dalam blok observeReads.	Contoh
DelegatingNode	Modifier.Node yang dapat mendelegasikan pekerjaan ke instance Modifier.Node lainnya. Hal ini dapat berguna untuk menyusun beberapa implementasi node menjadi satu.	Contoh
TraversableNode	Memungkinkan class Modifier.Node menjelajahi pohon node ke atas/bawah untuk class dengan jenis yang sama atau untuk kunci tertentu.	Contoh

Node otomatis menjadi tidak valid saat update dipanggil pada elemen yang sesuai. Karena contoh kita adalah DrawModifierNode, setiap kali update dipanggil pada elemen, node akan memicu gambar ulang dan warnanya akan diperbarui dengan benar. Anda dapat memilih untuk tidak ikut pembatalan validasi otomatis seperti yang dijelaskan di bawah.

ModifierNodeElement

ModifierNodeElement adalah class yang tidak dapat diubah yang menyimpan data untuk membuat atau memperbarui pengubah kustom Anda:

// ModifierNodeElement
private data class CircleElement(val color: Color) : ModifierNodeElement<CircleNode>() {
    override fun create() = CircleNode(color)

    override fun update(node: CircleNode) {
        node.color = color
    }
}
CustomModifierSnippets.kt

Implementasi ModifierNodeElement harus mengganti metode berikut:

1. create: Ini adalah fungsi yang membuat instance node pengubah. Ini dipanggil untuk membuat node saat pengubah Anda pertama kali diterapkan. Biasanya, hal ini berarti membuat node dan mengonfigurasinya dengan parameter yang diteruskan ke factory pengubah.
2. update: Fungsi ini dipanggil setiap kali pengubah ini disediakan di tempat yang sama dengan node yang sudah ada, tetapi properti telah berubah. Hal ini ditentukan oleh metode class equals. Node pengubah yang sebelumnya dibuat dikirim sebagai parameter ke panggilan update. Pada tahap ini, Anda harus memperbarui properti node agar sesuai dengan parameter yang diperbarui. Kemampuan node untuk digunakan kembali dengan cara ini adalah kunci untuk peningkatan performa yang dihasilkan Modifier.Node; oleh karena itu, Anda harus mengupdate node yang ada, bukan membuat node baru dalam metode update. Dalam contoh lingkaran, warna node diperbarui.

Selain itu, implementasi ModifierNodeElement juga harus menerapkan equals dan hashCode. update hanya akan dipanggil jika perbandingan yang sama dengan elemen sebelumnya menampilkan nilai salah.

Peringatan: ModifierNodeElement Anda harus menerapkan equals dan hashCode dengan benar dan tidak bergantung pada kesetaraan instance. Tanpa ini, node pengubah Anda akan diperbarui secara tidak perlu dan berperforma buruk. Gunakan class data untuk melakukannya secara otomatis.

Contoh di atas menggunakan class data untuk mencapai ini. Metode ini digunakan untuk memeriksa apakah node perlu diupdate atau tidak. Jika elemen memiliki properti yang tidak berkontribusi pada apakah node perlu diperbarui, atau Anda ingin menghindari class data karena alasan kompatibilitas biner, Anda dapat menerapkan equals dan hashCode secara manual, misalnya elemen pengubah padding.

Factory pengubah

Ini adalah platform API publik pengubah Anda. Sebagian besar implementasi hanya membuat elemen pengubah dan menambahkannya ke rantai pengubah:

// Modifier factory
fun Modifier.circle(color: Color) = this then CircleElement(color)
CustomModifierSnippets.kt

Contoh lengkap

Ketiga bagian ini bersatu untuk membuat pengubah kustom guna menggambar lingkaran menggunakan Modifier.Node API:

// Modifier factory
fun Modifier.circle(color: Color) = this then CircleElement(color)

// ModifierNodeElement
private data class CircleElement(val color: Color) : ModifierNodeElement<CircleNode>() {
    override fun create() = CircleNode(color)

    override fun update(node: CircleNode) {
        node.color = color
    }
}

// Modifier.Node
private class CircleNode(var color: Color) : DrawModifierNode, Modifier.Node() {
    override fun ContentDrawScope.draw() {
        drawCircle(color)
    }
}
CustomModifierSnippets.kt

Situasi umum yang menggunakan Modifier.Node

Saat membuat pengubah kustom dengan Modifier.Node, berikut adalah beberapa situasi umum yang mungkin Anda alami.

Parameter nol

Jika pengubah tidak memiliki parameter, pengubah tidak perlu diperbarui dan, lebih lanjut, tidak perlu berupa class data. Berikut adalah contoh implementasi pengubah yang menerapkan jumlah padding tetap ke composable:

fun Modifier.fixedPadding() = this then FixedPaddingElement

data object FixedPaddingElement : ModifierNodeElement<FixedPaddingNode>() {
    override fun create() = FixedPaddingNode()
    override fun update(node: FixedPaddingNode) {}
}

class FixedPaddingNode : LayoutModifierNode, Modifier.Node() {
    private val PADDING = 16.dp

    override fun MeasureScope.measure(
        measurable: Measurable,
        constraints: Constraints
    ): MeasureResult {
        val paddingPx = PADDING.roundToPx()
        val horizontal = paddingPx * 2
        val vertical = paddingPx * 2

        val placeable = measurable.measure(constraints.offset(-horizontal, -vertical))

        val width = constraints.constrainWidth(placeable.width + horizontal)
        val height = constraints.constrainHeight(placeable.height + vertical)
        return layout(width, height) {
            placeable.place(paddingPx, paddingPx)
        }
    }
}
CustomModifierSnippets.kt

Mereferensikan lokal komposisi

Pengubah Modifier.Node tidak otomatis mengamati perubahan pada objek status Compose, seperti CompositionLocal. Keuntungan pengubah Modifier.Node dibandingkan pengubah yang baru saja dibuat dengan factory composable adalah pengubah tersebut dapat membaca nilai komposisi lokal dari tempat pengubah digunakan dalam hierarki UI Anda, bukan tempat pengubah dialokasikan, menggunakan currentValueOf.

Namun, instance node pengubah tidak otomatis mengamati perubahan status. Untuk bereaksi secara otomatis terhadap perubahan lokal komposisi, Anda dapat membaca nilai saat ini di dalam cakupan:

• DrawModifierNode: ContentDrawScope
• LayoutModifierNode: MeasureScope & IntrinsicMeasureScope
• SemanticsModifierNode: SemanticsPropertyReceiver

Contoh ini mengamati nilai LocalContentColor untuk menggambar latar belakang berdasarkan warnanya. Karena ContentDrawScope mengamati perubahan snapshot, ini akan otomatis menggambar ulang saat nilai LocalContentColor berubah:

class BackgroundColorConsumerNode :
    Modifier.Node(),
    DrawModifierNode,
    CompositionLocalConsumerModifierNode {
    override fun ContentDrawScope.draw() {
        val currentColor = currentValueOf(LocalContentColor)
        drawRect(color = currentColor)
        drawContent()
    }
}
CustomModifierSnippets.kt

Untuk bereaksi terhadap perubahan status di luar cakupan dan otomatis memperbarui pengubah, gunakan ObserverModifierNode.

Misalnya, Modifier.scrollable menggunakan teknik ini untuk mengamati perubahan di LocalDensity. Contoh sederhana ditampilkan di bawah ini:

class ScrollableNode :
    Modifier.Node(),
    ObserverModifierNode,
    CompositionLocalConsumerModifierNode {

    // Place holder fling behavior, we'll initialize it when the density is available.
    val defaultFlingBehavior = DefaultFlingBehavior(splineBasedDecay(UnityDensity))

    override fun onAttach() {
        updateDefaultFlingBehavior()
        observeReads { currentValueOf(LocalDensity) } // monitor change in Density
    }

    override fun onObservedReadsChanged() {
        // if density changes, update the default fling behavior.
        updateDefaultFlingBehavior()
    }

    private fun updateDefaultFlingBehavior() {
        val density = currentValueOf(LocalDensity)
        defaultFlingBehavior.flingDecay = splineBasedDecay(density)
    }
}
CustomModifierSnippets.kt

Menganimasikan pengubah

Implementasi Modifier.Node memiliki akses ke coroutineScope. Hal ini memungkinkan penggunaan Compose Animatable API. Misalnya, cuplikan ini mengubah CircleNode dari atas untuk memudar dan muncul berulang kali:

class CircleNode(var color: Color) : Modifier.Node(), DrawModifierNode {
    private val alpha = Animatable(1f)

    override fun ContentDrawScope.draw() {
        drawCircle(color = color, alpha = alpha.value)
        drawContent()
    }

    override fun onAttach() {
        coroutineScope.launch {
            alpha.animateTo(
                0f,
                infiniteRepeatable(tween(1000), RepeatMode.Reverse)
            ) {
            }
        }
    }
}
CustomModifierSnippets.kt

Membagikan status antar-pengubah menggunakan delegasi

Pengubah Modifier.Node dapat mendelegasikan ke node lain. Ada banyak kasus penggunaan untuk hal ini, seperti mengekstrak implementasi umum di berbagai pengubah, tetapi juga dapat digunakan untuk berbagi status umum dengan seluruh pengubah.

Misalnya, penerapan dasar node pengubah yang dapat diklik yang membagikan data interaksi:

class ClickableNode : DelegatingNode() {
    val interactionData = InteractionData()
    val focusableNode = delegate(
        FocusableNode(interactionData)
    )
    val indicationNode = delegate(
        IndicationNode(interactionData)
    )
}
CustomModifierSnippets.kt

Memilih untuk tidak ikut pembatalan validasi otomatis node

Modifier.Node node otomatis dibatalkan saat ModifierNodeElement node terkait memanggil update. Terkadang, dalam pengubah yang lebih kompleks, Anda mungkin ingin menonaktifkan perilaku ini untuk memiliki kontrol yang lebih terperinci tentang kapan pengubah Anda membatalkan fase.

Hal ini dapat sangat berguna jika pengubah kustom Anda mengubah tata letak dan gambar. Dengan memilih tidak ikut pembatalan validasi otomatis, Anda hanya dapat membatalkan validasi gambar jika hanya properti terkait gambar, seperti color, yang berubah, dan tidak membatalkan validasi tata letak. Tindakan ini dapat meningkatkan performa pengubah.

Contoh hipotesis ini ditampilkan di bawah dengan pengubah yang memiliki lambda color, size, dan onClick sebagai properti. Pengubah ini hanya membatalkan validasi yang diperlukan, dan melewati pembatalan validasi yang tidak diperlukan:

class SampleInvalidatingNode(
    var color: Color,
    var size: IntSize,
    var onClick: () -> Unit
) : DelegatingNode(), LayoutModifierNode, DrawModifierNode {
    override val shouldAutoInvalidate: Boolean
        get() = false

    private val clickableNode = delegate(
        ClickablePointerInputNode(onClick)
    )

    fun update(color: Color, size: IntSize, onClick: () -> Unit) {
        if (this.color != color) {
            this.color = color
            // Only invalidate draw when color changes
            invalidateDraw()
        }

        if (this.size != size) {
            this.size = size
            // Only invalidate layout when size changes
            invalidateMeasurement()
        }

        // If only onClick changes, we don't need to invalidate anything
        clickableNode.update(onClick)
    }

    override fun ContentDrawScope.draw() {
        drawRect(color)
    }

    override fun MeasureScope.measure(
        measurable: Measurable,
        constraints: Constraints
    ): MeasureResult {
        val size = constraints.constrain(size)
        val placeable = measurable.measure(constraints)
        return layout(size.width, size.height) {
            placeable.place(0, 0)
        }
    }
}
CustomModifierSnippets.kt