Crea modificatori personalizzati

Compose fornisce molti modificatori per i comportamenti comuni, ma puoi anche creare i tuoi modificatori personalizzati.

I modificatori hanno più parti:

• Una factory di modifica
  • Si tratta di una funzione di estensione di Modifier, che fornisce un'API idiomatica per il modificatore e consente di collegare facilmente i modificatori. La factory di modificatori produce gli elementi di modificatore utilizzati da Compose per modificare l'interfaccia utente.
• Un elemento modificatore
  • Qui puoi implementare il comportamento del modificatore.

Esistono diversi modi per implementare un modificatore personalizzato, a seconda della funzionalità necessaria. Spesso, il modo più semplice per implementare un modificatore personalizzato è implementare una factory di modificatori personalizzati che combini altre factory di modificatori già definite. Se hai bisogno di un comportamento più personalizzato, implementa l'elemento modificatore utilizzando le API Modifier.Node, che sono di livello inferiore, ma offrono maggiore flessibilità.

Concatenare i modificatori esistenti

Spesso è possibile creare modificatori personalizzati semplicemente utilizzando quelli esistenti. Ad esempio, Modifier.clip() viene implementato utilizzando il modificatore graphicsLayer. Questa strategia utilizza gli elementi modificatori esistenti e tu fornisci la tua factory di modificatori personalizzati.

Prima di implementare il tuo modificatore personalizzato, controlla se puoi utilizzare la stessa strategia.

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

In alternativa, se ripeti spesso lo stesso gruppo di modificatori, puoi inserirli in un modificatore personalizzato:

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

Creare un modificatore personalizzato utilizzando una fabbrica di modificatori composibili

Puoi anche creare un modificatore personalizzato utilizzando una funzione componibile per passare valori a un modificatore esistente. Questa è nota come una factory di modificatori componibili.

Nota: nelle versioni precedenti di Compose sconsigliavamo questo approccio e suggerivamo di utilizzare composed {} tramite una regola lint. Ora che composed {} non è consigliato, la regola lint è stata rimossa.

L'utilizzo di una fabbrica di modificatori composibili per creare un modificatore consente anche di utilizzare API di composizione di livello superiore, come animate*AsState e altre API di animazione basate su stato di composizione. Ad esempio, lo snippet seguente mostra un modificatore che anima una variazione di alpha quando è attivato/disattivato:

@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

Avviso: quando crei modificatori personalizzati, non interrompere la catena di modificatori. Devi sempre fare riferimento a this, altrimenti tutti i modificatori aggiunti in precedenza verranno eliminati. Puoi utilizzare this then Modifier come nell'esempio precedente o implicitamente utilizzando return graphicsLayer { this.alpha = alpha }.

Se il modificatore personalizzato è un metodo di utilità per fornire valori predefiniti da un CompositionLocal, il modo più semplice per implementarlo è utilizzare una factory di modificatori composibili:

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

Questo approccio presenta alcune limitazioni, descritte di seguito.

I valori CompositionLocal vengono risolti nel sito di chiamata della factory del modificatore

Quando crei un modificatore personalizzato utilizzando una fabbrica di modificatori composibili, i valori locali della composizione prendono il valore dall'albero della composizione in cui vengono creati, non utilizzati. Ciò può portare a risultati inaspettati. Ad esempio, prendi l'esempio di modificatore locale di composizione riportato sopra, implementato in modo leggermente diverso utilizzando una funzione componibile:

@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

Se non è questo il funzionamento previsto per il modificatore, utilizza un Modifier.Node personalizzato, poiché i valori locali della composizione verranno risoluti correttamente nel sito di utilizzo e possono essere sollevati in sicurezza.

I modificatori delle funzioni componibili non vengono mai ignorati

I modificatori di factory composable non vengono mai ignorati perché le funzioni composable con valori restituiti non possono essere ignorate. Ciò significa che la funzione di modifica verrà richiamata a ogni ricompozione, il che può essere costoso se la ricompozione avviene spesso.

I modificatori delle funzioni componibili devono essere chiamati all'interno di una funzione componibile

Come tutte le funzioni composable, un modificatore di factory composable deve essere chiamato dall'interno della composizione. Ciò limita la posizione in cui un modificatore può essere sollevato, poiché non può mai essere sollevato dalla composizione. In confronto, le fabbriche di modificatori non componibili possono essere rimosse dalle funzioni componibili per consentire un riutilizzo più facile e migliorare le prestazioni:

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

Implementare il comportamento del modificatore personalizzato utilizzando Modifier.Node

Modifier.Node è un'API di livello inferiore per la creazione di modificatori in Compose. Si tratta della stessa API in cui Compose implementa i propri modificatori ed è il modo più efficiente per creare modificatori personalizzati.

Nota: esiste un'altra API per la creazione di modificatori personalizzati, composed {}. Questa API non è più consigliata a causa dei problemi di rendimento che ha creato. Modifier.Node è stato progettato per offrire un rendimento molto superiore rispetto ai modificatori composti. Per ulteriori dettagli sui problemi relativi ai modificatori composti, consulta la presentazione Compose Modifiers Deep Dive (Approfondimento sui modificatori composti) dell'Android Dev Summit.

Implementare un modificatore personalizzato utilizzando Modifier.Node

L'implementazione di un modificatore personalizzato utilizzando Modifier.Node prevede tre parti:

• Un'implementazione di Modifier.Node che contiene la logica e lo stato del modificatore.
• Un ModifierNodeElement che crea e aggiorna le istanze dei nodi di modifica.
• Una factory di modifica facoltativa come descritto sopra.

I tipi di ModifierNodeElement sono stateless e a ogni ricostituzione vengono allocate nuove istanze, mentre i tipi di Modifier.Node possono essere stateful e sopravvivere a più ricostruzioni e possono persino essere riutilizzati.

La sezione seguente descrive ogni parte e mostra un esempio di creazione di un modificatore personalizzato per disegnare un cerchio.

Modifier.Node

L'implementazione di Modifier.Node (in questo esempio, CircleNode) implementa la funzionalità del modificatore personalizzato.

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

In questo esempio, viene disegnato il cerchio con il colore passato alla funzione del modificatore.

Un nodo implementa Modifier.Node e zero o più tipi di nodi. Esistono diversi tipi di nodi in base alla funzionalità richiesta dal modificatore. L'esempio riportato sopra deve essere in grado di disegnare, quindi implementa DrawModifierNode, che consente di eseguire l'override del metodo draw.

I tipi disponibili sono i seguenti:

Nodo	Utilizzo	Link di esempio
LayoutModifierNode	Un Modifier.Node che modifica la misurazione e la disposizione dei contenuti a capo.	Esempio
DrawModifierNode	Un Modifier.Node che viene visualizzato nello spazio del layout.	Esempio
CompositionLocalConsumerModifierNode	L'implementazione di questa interfaccia consente a Modifier.Node di leggere le variabili locali della composizione.	Esempio
SemanticsModifierNode	Un Modifier.Node che aggiunge una coppia chiave/valore di semantica da utilizzare per i test, l'accessibilità e casi d'uso simili.	Esempio
PointerInputModifierNode	Un Modifier.Node che riceve PointerInputChanges.	Esempio
ParentDataModifierNode	Un Modifier.Node che fornisce dati al layout principale.	Esempio
LayoutAwareModifierNode	Un Modifier.Node che riceve i callback onMeasured e onPlaced.	Esempio
GlobalPositionAwareModifierNode	Un Modifier.Node che riceve un onGloballyPositioned callback con il LayoutCoordinates finale del layout quando la posizione globale dei contenuti potrebbe essere cambiata.	Esempio
ObserverModifierNode	I Modifier.Node che implementano ObserverNode possono fornire la propria implementazione di onObservedReadsChanged che verrà chiamata in risposta alle modifiche agli oggetti snapshot letti all'interno di un blocco observeReads.	Esempio
DelegatingNode	Un Modifier.Node in grado di delegare il lavoro ad altre istanze Modifier.Node. Ciò può essere utile per combinare più implementazioni di nodi in una sola.	Esempio
TraversableNode	Consente alle classi Modifier.Node di risalire/scendere nella struttura ad albero dei nodi per trovare classi dello stesso tipo o per una determinata chiave.	Esempio

I nodi vengono invalidati automaticamente quando viene chiamato l'aggiornamento sull'elemento corrispondente. Poiché il nostro esempio è un DrawModifierNode, ogni volta che viene chiamato l'aggiornamento sull'elemento, il nodo attiva un nuovo disegno e il relativo colore viene aggiornato correttamente. È possibile disattivare l'invalidazione automatica come descritto di seguito.

ModifierNodeElement

Un ModifierNodeElement è una classe immutabile che contiene i dati per creare o aggiornare il modificatore personalizzato:

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

Le implementazioni di ModifierNodeElement devono sostituire i seguenti metodi:

1. create: questa è la funzione che esegue l'inizializzazione del nodo modificatore. Viene chiamato per creare il nodo quando il modificatore viene applicato per la prima volta. In genere, questo equivale a creare il nodo e a configurarlo con i parametri passati alla factory del modificatore.
2. update: questa funzione viene chiamata ogni volta che questo modificatore viene fornito nello stesso punto in cui esiste già il nodo, ma una proprietà è cambiata. Questo è determinato dal metodo equals della classe. Il nodo modificatore creato precedentemente viene inviato come parametro alla chiamata update. A questo punto, devi aggiornare le proprietà dei nodi in modo che corrispondano ai parametri aggiornati. La possibilità di riutilizzare i nodi in questo modo è fondamentale per i guadagni in termini di prestazioni offerti da Modifier.Node. Pertanto, devi aggiornare il nodo esistente anziché crearne uno nuovo nel metodo update. Nel nostro esempio di cerchio, il colore del nodo viene aggiornato.

Inoltre, le implementazioni di ModifierNodeElement devono implementare anche equals e hashCode. update viene chiamato solo se un confronto di uguaglianza con l'elemento precedente restituisce false.

Avviso: ModifierNodeElement deve implementare equals e hashCode correttamente e non fare affidamento sull'uguaglianza delle istanze. In caso contrario, il nodo del modificatore verrà aggiornato inutilmente e avrà un rendimento scadente. Utilizza una classe di dati per ottenere questo risultato automaticamente.

L'esempio riportato sopra utilizza una classe di dati per ottenere questo risultato. Questi metodi vengono utilizzati per verificare se un nodo deve essere aggiornato o meno. Se l'elemento ha proprietà che non contribuiscono a stabilire se un nodo deve essere aggiornato o se vuoi evitare le classi di dati per motivi di compatibilità binaria, puoi implementare manualmente equals e hashCode, ad esempio l'elemento modificatore di spaziatura.

Factory di modificatori

Questa è la superficie dell'API pubblica del modificatore. La maggior parte delle implementazioni crea semplicemente l'elemento modificatore e lo aggiunge alla catena di modificatori:

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

Esempio completo

Queste tre parti si combinano per creare il modificatore personalizzato per disegnare un cerchio utilizzando le 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

Situazioni comuni che utilizzano Modifier.Node

Quando crei modificatori personalizzati con Modifier.Node, ecco alcune situazioni comuni che potresti incontrare.

Nessun parametro

Se il modificatore non ha parametri, non deve mai essere aggiornato e, inoltre, non deve essere una classe di dati. Ecco un esempio di implementazione di un modificatore che applica una quantità fissa di spaziatura interna a un 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

Fare riferimento ai dati locali sulla composizione

I modificatori Modifier.Node non osservano automaticamente le modifiche agli oggetti dello stato di Compose, come CompositionLocal. Il vantaggio dei modificatori Modifier.Node rispetto ai modificatori appena creati con una fabbrica composable è che possono leggere il valore della composizione locale da dove viene utilizzato il modificatore nell'albero dell'interfaccia utente, non dove viene allocato il modificatore, utilizzando currentValueOf.

Tuttavia, le istanze dei nodi modificatori non osservano automaticamente le modifiche dello stato. Per reagire automaticamente alla modifica di un parametro locale della composizione, puoi leggere il suo valore corrente all'interno di un ambito:

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

Questo esempio osserva il valore di LocalContentColor per disegnare uno sfondo in base al suo colore. Poiché ContentDrawScope osserva le modifiche dell'istantanea, viene ridisegnato automaticamente quando cambia il valore di LocalContentColor:

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

Per reagire alle modifiche dello stato al di fuori di un ambito e aggiornare automaticamente il modificatore, utilizza un ObserverModifierNode.

Ad esempio, Modifier.scrollable utilizza questa tecnica per osservare le variazioni in LocalDensity. Di seguito è riportato un esempio semplificato:

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

Modificatore di animazione

Le implementazioni di Modifier.Node hanno accesso a un coroutineScope. In questo modo è possibile utilizzare le API Compose Animatable. Ad esempio, questo snippet modifica il valore CircleNode riportato sopra in modo che venga visualizzato e nascosto ripetutamente:

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

Condivisione dello stato tra i modificatori mediante la delega

I modificatori Modifier.Node possono delegare ad altri nodi. Esistono molti casi d'uso per questo, ad esempio l'estrazione di implementazioni comuni tra diversi modificatori, ma può essere utilizzato anche per condividere lo stato comune tra i modificatori.

Ad esempio, un'implementazione di base di un nodo modificatore cliccabile che condivide i dati di interazione:

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

Disattivare l'invalidazione automatica dei nodi

I nodi Modifier.Node vengono invalidati automaticamente quando le chiamate ModifierNodeElement corrispondenti vengono aggiornate. A volte, in un modificatore più complesso, potresti scegliere di disattivare questo comportamento per avere un controllo più granulare sul momento in cui il modificatore invalida le fasi.

Questo può essere particolarmente utile se il modificatore personalizzato modifica sia il layout sia il disegno. La disattivazione dell'invalidazione automatica ti consente di invalidare il disegno solo quando cambiano le proprietà relative al disegno, come color, e non invalidare il layout. In questo modo, puoi migliorare il rendimento del modificatore.

Di seguito è riportato un esempio ipotetico con un modificatore che ha un lambda color, size e onClick come proprietà. Questo modificatore invalida solo ciò che è obbligatorio e ignora qualsiasi invalidazione non obbligatoria:

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