Tworzenie modyfikatorów niestandardowych

Compose udostępnia wiele modyfikatorów dostępnych od razu po zainstalowaniu, ale możesz też tworzyć własne modyfikatory niestandardowe.

Modyfikatory mają kilka części:

• Modyfikator fabryczny
  • To funkcja rozszerzenia w Modifier, która udostępnia idiomatyczny interfejs API dla modyfikatora i umożliwia łatwe łańcuchowe łączenie modyfikatorów. Fabryka modyfikatorów generuje elementy modyfikatorów używane przez Compose do modyfikowania interfejsu użytkownika.
• Element modyfikujący
  • Tutaj możesz zaimplementować działanie modyfikatora.

W zależności od potrzebnej funkcjonalności modyfikator niestandardowy można zaimplementować na kilka sposobów. Często najłatwiejszym sposobem wdrożenia niestandardowego modyfikatora jest wdrożenie niestandardowej fabryki modyfikatorów, która łączy ze sobą inne zdefiniowane już fabryki modyfikatorów. Jeśli potrzebujesz bardziej niestandardowego zachowania, zaimplementuj element modyfikatora za pomocą interfejsów Modifier.Node API, które są interfejsami niższego poziomu, ale zapewniają większą elastyczność.

Łączenie dotychczasowych modyfikatorów

Często można tworzyć modyfikatory niestandardowe, korzystając tylko z dotychczasowych modyfikatorów. Na przykład Modifier.clip() jest implementowane za pomocą modyfikatora graphicsLayer. Ta strategia korzysta z dotychczasowych elementów modyfikatora, a Ty musisz podać własną fabrykę modyfikatorów niestandardowych.

Zanim wdrożysz własny modyfikator niestandardowy, sprawdź, czy nie możesz użyć tej samej strategii.

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

Jeśli zauważysz, że często powtarzasz tę samą grupę modyfikatorów, możesz je umieścić w ramach własnego modyfikatora:

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

Tworzenie niestandardowego modyfikatora za pomocą fabryki modyfikatorów złożonych

Możesz też utworzyć niestandardowy modyfikator, używając funkcji składanej, aby przekazywać wartości do istniejącego modyfikatora. Jest to tzw. fabryka modyfikatorów składanych.

Uwaga: w poprzednich wersjach Compose zalecaliśmy unikanie tego podejścia i zamiast tego używanie reguły lint composed {}. Ponieważ composed {} nie jest już zalecane, reguła lint została usunięta.

Korzystanie z fabryki modyfikatorów do tworzenia modyfikatorów umożliwia też używanie interfejsów do tworzenia na wyższym poziomie, takich jak animate*AsState i inne interfejsy API do animowania na podstawie stanu. Na przykład ten fragment kodu pokazuje modyfikator, który animuje zmianę wartości alfa po włączeniu lub wyłączeniu:

@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

Ostrzeżenie: podczas tworzenia niestandardowych modyfikatorów nie przerywaj łańcucha modyfikatorów. Musisz zawsze odwoływać się do this, w przeciwnym razie wszystkie wcześniej dodane modyfikatory zostaną pominięte. Możesz użyć this then Modifier, tak jak w poprzednim przykładzie, lub użyć return graphicsLayer { this.alpha = alpha } w sposób domyślny.

Jeśli modyfikator niestandardowy jest wygodną metodą na podawanie wartości domyślnych z poziomu CompositionLocal, najprostszym sposobem na jego wdrożenie jest użycie modułowej fabryki modyfikatorów:

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

Takie podejście ma jednak pewne ograniczenia, które opisujemy poniżej.

Wartości CompositionLocal są rozwiązywane w miejscu wywołania fabryki modyfikatorów.

Podczas tworzenia modyfikatora niestandardowego za pomocą fabryki modyfikatorów kompozytowych składowe lokalne pobierają wartość z drzewa kompozycji, w której zostały utworzone, a nie z kompozycji, w której są używane. Może to prowadzić do nieoczekiwanych wyników. Weźmy na przykład kompozycję z lokalnym modyfikatorem z powyższego przykładu, która została zaimplementowana nieco inaczej za pomocą funkcji kompozytowej:

@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

Jeśli nie chcesz, aby modyfikator działał w taki sposób, użyj zamiast tego modyfikatora niestandardowego Modifier.Node, ponieważ lokalne wartości kompozycji zostaną poprawnie rozwiązane w miejscu użycia i można je bezpiecznie podnosić.

Modyfikatory funkcji typu „composable” nigdy nie są pomijane.

Modyfikatory fabryk składanych nigdy nie są pominane, ponieważ składane funkcje, które zwracają wartości, nie mogą być pomijane. Oznacza to, że funkcja modyfikatora będzie wywoływana przy każdym przekształceniu, co może być kosztowne, jeśli będzie się ono często powtarzać.

Zmienne funkcji typu „composable” muszą być wywoływane w ramach funkcji typu „composable”

Podobnie jak wszystkie funkcje kompozytowe, modyfikator fabryki kompozytowej musi być wywoływany z poziomu kompozycji. Ogranicza to miejsce, do którego może zostać przeniesiony modyfikator, ponieważ nigdy nie może zostać przeniesiony poza kompozycję. Z kolei fabryki modyfikatorów, które nie są kompozytowe, można wyodrębnić z funkcji kompozytowych, aby ułatwić ich ponowne użycie i poprawić wydajność:

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

Implementowanie niestandardowego zachowania modyfikatora za pomocą Modifier.Node

Modifier.Node to interfejs API niższego poziomu do tworzenia modyfikatorów w Compose. Jest to ten sam interfejs API, w którym Compose wdraża własne modyfikatory. Jest to też najbardziej wydajny sposób tworzenia niestandardowych modyfikatorów.

Uwaga: do tworzenia niestandardowych modyfikatorów służy inny interfejs API: composed {}. Ten interfejs API nie jest już zalecany ze względu na problemy z wydajnością. Modifier.Node został zaprojektowany od podstaw tak, aby zapewniać znacznie większą wydajność niż składowane modyfikatory. Więcej informacji o problemach z modyfikatorami złożonymi znajdziesz w wykładzie Compose Modifiers Deep Dive (w języku angielskim) na konferencji Android Dev Summit.

Implementowanie niestandardowego modyfikatora za pomocą Modifier.Node

Implementacja niestandardowego modyfikatora za pomocą węzła Modifier.Node składa się z 3 części:

• Implementacja Modifier.Node, która zawiera logikę i stan modyfikatora.
• ModifierNodeElement, który tworzy i aktualizuje instancje węzła modyfikatora.
• Opcjonalna fabryka modyfikatorów opisana powyżej.

Klasy ModifierNodeElement są stanowe i przy każdej rekompozycji przydzielane są nowe instancje, natomiast klasy Modifier.Node mogą być stanowe i przetrwają przez wiele rekompozycji, a nawet można je ponownie wykorzystać.

W następnej sekcji opisujemy poszczególne części i pokazujemy przykład tworzenia niestandardowego modyfikatora do rysowania okręgu.

Modifier.Node

Implementacja Modifier.Node (w tym przykładzie CircleNode) realizuje funkcjonalność niestandardowego modyfikatora.

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

W tym przykładzie rysuje okrąg o kolorze przekazanym funkcji modyfikatora.

Węzeł implementuje Modifier.Node oraz co najmniej 1 typ węzła. Istnieją różne typy węzłów, które zależą od funkcji wymaganych przez modyfikator. Przykład powyżej musi mieć możliwość rysowania, więc implementuje interfejs DrawModifierNode, który pozwala mu zastąpić metodę draw().

Dostępne typy:

Węzeł	Wykorzystanie	Link do przykładu
LayoutModifierNode	Modifier.Node, który zmienia sposób pomiaru i układ zawiniętych treści.	Przykład
DrawModifierNode	Modifier.Node, który wpisuje się w przestrzeń układu.	Przykład
CompositionLocalConsumerModifierNode	Dzięki wdrożeniu tego interfejsu aplikacja Modifier.Node może odczytywać lokalne wartości kompozycji.	Przykład
SemanticsModifierNode	Modifier.Node, który dodaje pary klucz-wartość do użycia w przypadku testowania, dostępności i podobnych zastosowań.	Przykład
PointerInputModifierNode	Modifier.Node, który odbiera zdarzenie PointerInputChanges.	Przykład
ParentDataModifierNode	Modifier.Node, który przekazuje dane do układu nadrzędnego.	Przykład
LayoutAwareModifierNode	Modifier.Node, który otrzymuje wywołania zwrotne onMeasured i onPlaced.	Przykład
GlobalPositionAwareModifierNode	Modifier.Node, który otrzymuje wywołanie zwrotne onGloballyPositioned z ostatecznym LayoutCoordinates układu, gdy może się zmienić globalne położenie treści.	Przykład
ObserverModifierNode	Modifier.Node, które implementują ObserverNode, mogą udostępnić własną implementację funkcji onObservedReadsChanged, która będzie wywoływana w odpowiedzi na zmiany obiektów zrzutu odczytanych w bloku observeReads.	Przykład
DelegatingNode	Modifier.Node, który może delegować zadania do innych instancji Modifier.Node. Może to być przydatne, gdy chcesz połączyć kilka implementacji węzłów w jedną.	Przykład
TraversableNode	Umożliwia elementom klasy Modifier.Node przechodzenie w górę i w dół po drzewie węzłów w przypadku elementów klasy tego samego typu lub określonego klucza.	Przykład

Po wywołaniu metody update w odpowiednim elemencie węzły są automatycznie unieważniane. Ponieważ nasz przykład to DrawModifierNode, za każdym razem, gdy wywoływana jest aktualizacja elementu, węzeł powoduje ponowne rysowanie i poprawne aktualizowanie koloru. Możesz zrezygnować z automatycznego unieważniania, jak opisano poniżej.

ModifierNodeElement

ModifierNodeElement to niezmienna klasa, która przechowuje dane potrzebne do utworzenia lub zaktualizowania niestandardowego modyfikatora:

// 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

Implementacje ModifierNodeElement muszą zastąpić te metody:

1. create: to funkcja, która tworzy instancję węzła modyfikatora. Jest on wywoływany, aby utworzyć węzeł, gdy modyfikator zostanie zastosowany po raz pierwszy. Zwykle oznacza to utworzenie węzła i skonfigurowanie go za pomocą parametrów przekazanych fabryce modyfikatorów.
2. update: ta funkcja jest wywoływana, gdy ten modyfikator jest podany w tym samym miejscu, w którym węzeł już istnieje, ale zmieniła się jakaś właściwość. Jest ona określana przez metodę equals klasy. Utworzony wcześniej węzeł modyfikatora jest wysyłany jako parametr do wywołania update. W tym momencie powinieneś zaktualizować właściwości węzłów, aby odpowiadały one zaktualizowanym parametrom. Możliwość ponownego użycia węzłów w ten sposób jest kluczowa dla wzrostu wydajności, jaki zapewnia Modifier.Node. Dlatego musisz zaktualizować istniejący węzeł, a nie tworzyć nowego za pomocą metody update. W naszym przykładzie kółko zmienia kolor.

Dodatkowo implementacje ModifierNodeElement muszą też implementować equals i hashCode. update zostanie wywołany tylko wtedy, gdy porównanie z poprzednim elementem zwróci wartość false.

Ostrzeżenie: funkcja ModifierNodeElement musi prawidłowo implementować funkcje equals i hashCode, a nie polegać na równości instancji. Bez tego węzeł modyfikatora będzie aktualizowany niepotrzebnie i będzie działać nieefektywnie. Aby to zrobić automatycznie, użyj klasy danych.

W przykładzie powyżej do tego celu użyto klasy danych. Te metody służą do sprawdzania, czy węzeł wymaga aktualizacji. Jeśli element ma właściwości, które nie wpływają na to, czy węzeł musi zostać zaktualizowany, lub jeśli chcesz uniknąć klas danych ze względu na zgodność binarną, możesz ręcznie zaimplementować equals i hashCode, np. element modyfikatora wypełnienia.

Fabryka modyfikatorów

To jest publiczna strona interfejsu API modyfikatora. Większość implementacji po prostu tworzy element modyfikatora i dodaje go do łańcucha modyfikatorów:

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

Pełny przykład

Te 3 elementy tworzą niestandardowy modyfikator do rysowania koła za pomocą interfejsów API Modifier.Node:

// 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

Typowe sytuacje, w których używany jest element Modifier.Node

Podczas tworzenia modyfikatorów niestandardowych za pomocą funkcji Modifier.Node możesz napotkać kilka typowych sytuacji.

Zero parametrów

Jeśli modyfikator nie ma parametrów, nigdy nie trzeba go aktualizować, a dodatkowo nie musi być klasą danych. Oto przykładowa implementacja modyfikatora, który stosuje stały odstęp do kompozytu:

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

Odwoływanie się do lokalizacji w kompozycji

Modyfikatory Modifier.Node nie rejestrują automatycznie zmian stanu obiektów Compose, takich jak CompositionLocal. Zaletą modyfikatorów Modifier.Node w porównaniu z modyfikatorami utworzonymi za pomocą fabryki kompozytowej jest to, że mogą one odczytywać wartość kompozycji lokalnej z miejsca, w którym modyfikator jest używany w drzewie interfejsu użytkownika, a nie z miejsca, w którym jest przypisany, za pomocą currentValueOf.

Jednak instancje węzła modyfikatora nie rejestrują automatycznie zmian stanu. Aby automatycznie reagować na zmiany w kompozycji lokalnej, możesz odczytać jej bieżącą wartość w zakresie:

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

W tym przykładzie obserwujemy wartość LocalContentColor, aby narysować tło na podstawie jego koloru. Funkcja ContentDrawScope reaguje na zmiany w migawkach, więc automatycznie przerysowuje się, gdy zmienia się wartość LocalContentColor:

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

Aby reagować na zmiany stanu poza zakresem i automatycznie aktualizować modyfikator, użyj ObserverModifierNode.

Na przykład funkcja Modifier.scrollable korzysta z tej metody do obserwowania zmian w danych LocalDensity. Poniżej przedstawiamy uproszczony przykład:

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

Modyfikator animacji

Implementacje Modifier.Node mają dostęp do zasobu coroutineScope. Pozwala to na korzystanie z interfejsów API Compose Animatable. Ten fragment kodu modyfikuje CircleNode z powyższego przykładu, aby efekt płynnego pojawiania się i znikania był powtarzany:

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

Udostępnianie stanu między modyfikatorami za pomocą delegowania

Modifier.Node modyfikatory mogą delegować do innych węzłów. Ma ono wiele zastosowań, takich jak wyodrębnianie wspólnych implementacji w różnych modyfikatorach, ale można go też używać do udostępniania wspólnego stanu w różnych modyfikatorach.

Oto przykład podstawowej implementacji klikalnego węzła modyfikatora, który udostępnia dane interakcji:

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

Rezygnacja z automatycznego unieważniania węzła

Modifier.Node są automatycznie nieważne, gdy ich odpowiadające im wywołania ModifierNodeElement zostaną zaktualizowane. Czasami w przypadku bardziej złożonego modyfikatora możesz chcieć zrezygnować z tego zachowania, aby uzyskać większą kontrolę nad tym, kiedy modyfikator unieważnia fazy.

Może to być szczególnie przydatne, jeśli modyfikator niestandardowy modyfikuje zarówno układ, jak i rysowanie. Wyłączenie automatycznego unieważniania pozwala unieważnić tylko draw, gdy zmieniają się tylko właściwości związane z draw, np. color, a nie unieważniać układu. Może to zwiększyć skuteczność modyfikatora.

Poniżej przedstawiamy hipotetyczny przykład modyfikatora z właściwościami color, size i lambda onClick. Ten modyfikator unieważnia tylko wymagane elementy i pomija nieprawidłowe elementy:

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