Daten auf lokaler Ebene mit CompositionLocal

CompositionLocal ist ein Tool für Daten implizit durch die Komposition weitergeleitet werden. Auf dieser Seite erfahren Sie mehr darüber, was ein CompositionLocal ist, wie Sie einen eigenen CompositionLocal erstellen und ob ein CompositionLocal eine gute Lösung für Ihren Anwendungsfall ist.

Jetzt neu: CompositionLocal

Normalerweise fließen Daten in Compose als Parameter durch den UI-Baum hinunter zu jeder zusammensetzbaren Funktion. Dadurch wird das explizit sind. Dies kann jedoch umständlich für Daten sein, die sehr häufig und weit verbreitet, wie Farben oder Schriftstile. Weitere Informationen: Beispiel:

@Composable
fun MyApp() {
    // Theme information tends to be defined near the root of the application
    val colors = colors()
}

// Some composable deep in the hierarchy
@Composable
fun SomeTextLabel(labelText: String) {
    Text(
        text = labelText,
        color = colors.onPrimary // ← need to access colors here
    )
}
CompositionLocalSnippets.kt

Um zu unterstützen, dass die Farben nicht als explizite Parameterabhängigkeit an Mit der Option Compose AngeboteCompositionLocal können Sie zum Erstellen von benannten Objekten auf Baumebene, die implizit verwendet werden können, um Datenfluss durch den UI-Baum.

CompositionLocal-Elemente werden normalerweise mit einem Wert in einem bestimmten Knoten bereitgestellt des UI-Baums. Dieser Wert kann von den übergeordneten Funktionen verwendet werden, ohne dass CompositionLocal als Parameter in der zusammensetzbaren Funktion deklariert werden muss.

Im Hintergrund wird CompositionLocal verwendet. MaterialTheme ist Ein Objekt, das drei CompositionLocal-Instanzen bereitstellt: colorScheme, typography und shapes, sodass Sie sie später in einem beliebigen als Teil der Komposition. Das sind die Attribute LocalColorScheme, LocalShapes und LocalTypography, auf die Sie über die Attribute MaterialThemecolorScheme, shapes und typography zugreifen können.

@Composable
fun MyApp() {
    // Provides a Theme whose values are propagated down its `content`
    MaterialTheme {
        // New values for colorScheme, typography, and shapes are available
        // in MaterialTheme's content lambda.

        // ... content here ...
    }
}

// Some composable deep in the hierarchy of MaterialTheme
@Composable
fun SomeTextLabel(labelText: String) {
    Text(
        text = labelText,
        // `primary` is obtained from MaterialTheme's
        // LocalColors CompositionLocal
        color = MaterialTheme.colorScheme.primary
    )
}
CompositionLocalSnippets.kt

Eine CompositionLocal-Instanz ist auf einen Teil der Komposition beschränkt, sodass Sie können verschiedene Werte auf verschiedenen Ebenen der Baumstruktur bereitgestellt werden. Der current-Wert eines CompositionLocal entspricht dem Wert, der von einem übergeordneten Element in diesem Teil der Komposition am nächsten liegt.

Wenn Sie einem CompositionLocal einen neuen Wert zuweisen möchten, verwenden Sie die Funktion CompositionLocalProvider und ihre Infixfunktion provides, die einem CompositionLocal-Schlüssel einen value-Wert zuordnet. Die content-Lambda-Funktion der CompositionLocalProvider erhält den angegebenen Wert, wenn auf die current-Property der CompositionLocal zugegriffen wird. Wenn ein wird ein neuer Wert angegeben, setzt "Compose" Teile der Komposition neu zusammen, CompositionLocal.

Als Beispiel enthält die CompositionLocal-Datei LocalContentColor die bevorzugte Inhaltsfarbe für Text und damit sie sich von der aktuellen Hintergrundfarbe abhebt. Im Im folgenden Beispiel wird CompositionLocalProvider verwendet, für verschiedene Teile der Komposition.

@Composable
fun CompositionLocalExample() {
    MaterialTheme {
        // Surface provides contentColorFor(MaterialTheme.colorScheme.surface) by default
        // This is to automatically make text and other content contrast to the background
        // correctly.
        Surface {
            Column {
                Text("Uses Surface's provided content color")
                CompositionLocalProvider(LocalContentColor provides MaterialTheme.colorScheme.primary) {
                    Text("Primary color provided by LocalContentColor")
                    Text("This Text also uses primary as textColor")
                    CompositionLocalProvider(LocalContentColor provides MaterialTheme.colorScheme.error) {
                        DescendantExample()
                    }
                }
            }
        }
    }
}

@Composable
fun DescendantExample() {
    // CompositionLocalProviders also work across composable functions
    Text("This Text uses the error color now")
}
CompositionLocalSnippets.kt

Abbildung 1: Vorschau des CompositionLocalExample-Kompositionselements.

Im letzten Beispiel wurden die CompositionLocal-Instanzen intern von Material-Kompositen verwendet. So greifen Sie auf den aktuellen Wert einer CompositionLocal zu: Verwenden Sie die current Property. Im folgenden Beispiel wird der aktuelle Context-Wert des LocalContextCompositionLocal verwendet, der häufig in Android-Apps verwendet wird, um den Text zu formatieren:

@Composable
fun FruitText(fruitSize: Int) {
    // Get `resources` from the current value of LocalContext
    val resources = LocalContext.current.resources
    val fruitText = remember(resources, fruitSize) {
        resources.getQuantityString(R.plurals.fruit_title, fruitSize)
    }
    Text(text = fruitText)
}
CompositionLocalSnippets.kt

Eigenes CompositionLocal erstellen

CompositionLocal ist ein Tool zum impliziten Weitergeben von Daten durch die Komposition.

Ein weiteres wichtiges Signal für die Verwendung von CompositionLocal ist, dass der Parameter übergreifende und Zwischenschichten der Implementierung nicht wissen, vorhanden ist, da die Erkennung dieser Zwischenebenen den der zusammensetzbaren Funktion. Die Abfrage von Android-Berechtigungen was sich CompositionLocal unter der Haube bietet. Eine zusammensetzbare Media-Auswahl neue Funktionen für den Zugriff auf berechtigungsgeschützte Inhalte im ohne die API zu ändern und die Aufrufer der Media-Auswahl berücksichtigen Sie diesen zusätzlichen Kontext, der aus der Umgebung verwendet wird.

CompositionLocal ist jedoch nicht immer die beste Lösung. Mi. Vermeide eine zu häufige Verwendung von CompositionLocal, da dies einige Nachteile hat:

CompositionLocal erschwert es, das Verhalten eines komponierbaren Elements zu verstehen. Als erstellen implizite Abhängigkeiten, die Aufrufer von zusammensetzbaren Funktionen, die diese verwenden, um sicherzustellen, dass ein Wert für jeden CompositionLocal erfüllt ist.

Darüber hinaus gibt es möglicherweise keine eindeutige Datenquelle für diese Abhängigkeit, da sie können an einem beliebigen Teil der Komposition angepasst werden. Daher kann es schwieriger sein, die App zu debuggen, wenn ein Problem auftritt, da Sie sich durch die Komposition bewegen müssen, um zu sehen, wo der current-Wert angegeben wurde. Tools wie Suchen Nutzungen in der IDE oder im Compose layout Inspector (Layout-Inspektor verfassen), um genügend Informationen dieses Problem zu beheben.

Entscheiden, ob CompositionLocal verwendet werden soll

Unter bestimmten Bedingungen kann CompositionLocal eine gute Lösung für Ihren Anwendungsfall sein:

Ein CompositionLocal sollte einen guten Standardwert haben. Wenn kein Standardwert vorhanden ist müssen Sie garantieren, dass es für einen Entwickler außerordentlich schwierig ist, für den Fall, dass für CompositionLocal kein Wert angegeben ist. Wenn Sie keinen Standardwert angeben, kann dies zu Problemen und Frust beim Erstellen oder eine Vorschau einer zusammensetzbaren Funktion mit dieser CompositionLocal-Funktion ausführen, explizit angegeben werden.

Vermeiden Sie CompositionLocal für Konzepte, die nicht als baumbezogen oder auf Ebene der untergeordneten Hierarchie. Eine CompositionLocal ist sinnvoll, wenn sie potenziell von allen untergeordneten Elementen verwendet werden kann, nicht nur von einigen.

Wenn Ihr Anwendungsfall diese Anforderungen nicht erfüllt, sehen Sie sich die Abschnitt Alternativen, bevor Sie eine CompositionLocal

Ein Beispiel für eine unzulässige Vorgehensweise ist das Erstellen einer CompositionLocal, die den ViewModel eines bestimmten Bildschirms, sodass alle zusammensetzbaren Funktionen in diesem Bildschirm einen Verweis auf das ViewModel abzurufen, um eine Logik auszuführen. Das ist nicht empfehlenswert da nicht alle zusammensetzbaren Funktionen unter einem bestimmten UI-Baum Informationen zum ViewModel Es empfiehlt sich, den Composeables nur die Informationen zu übergeben, die sie benötigen, und dabei dem Muster zu folgen, dass der Status nach unten und Ereignisse nach oben fließen. Mit diesem Ansatz werden Ihre zusammensetzbaren Funktionen wiederverwendbar und leichter zu testen.

CompositionLocal erstellen

Es gibt zwei APIs zum Erstellen einer CompositionLocal:

  • compositionLocalOf: Wenn der Wert während der Neuzusammensetzung geändert wird, werden nur ungültig. den Inhalt, der seine current Wert.

  • staticCompositionLocalOf: Im Gegensatz zu compositionLocalOf sind Lesevorgänge einer staticCompositionLocalOf nicht von Compose verfolgt. Wenn Sie den Wert ändern, wird der Wert für content vollständig Lambda-Funktion, bei der das CompositionLocal zur Neuzusammensetzung bereitgestellt wird, nur die Stellen, an denen der current-Wert in der Zusammensetzung gelesen wird.

Wenn sich der für CompositionLocal angegebene Wert höchstwahrscheinlich nicht ändert oder sich nie ändert, verwenden Sie staticCompositionLocalOf, um Leistungsvorteile zu erzielen.

Das Designsystem einer App kann beispielsweise festlegen, wie Elemente mithilfe eines Schattens für die UI-Komponente hervorgehoben werden. Da die verschiedenen Ebenen der App im gesamten UI-Baum übernommen werden sollen, verwenden wir eine CompositionLocal. Da der Wert für CompositionLocal bedingt vom Systemthema abgeleitet wird, verwenden wir die compositionLocalOf API:

// LocalElevations.kt file

data class Elevations(val card: Dp = 0.dp, val default: Dp = 0.dp)

// Define a CompositionLocal global object with a default
// This instance can be accessed by all composables in the app
val LocalElevations = compositionLocalOf { Elevations() }
CompositionLocalSnippets.kt

Werte für CompositionLocal angeben

Das CompositionLocalProvider-kompositum bindet Werte an CompositionLocal-Instanzen für die angegebene Hierarchie. Wenn Sie einer CompositionLocal einen neuen Wert zuweisen möchten, verwenden Sie die Infixfunktion provides, um einen CompositionLocal-Schlüssel einem value zuzuweisen:

// MyActivity.kt file

class MyActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            // Calculate elevations based on the system theme
            val elevations = if (isSystemInDarkTheme()) {
                Elevations(card = 1.dp, default = 1.dp)
            } else {
                Elevations(card = 0.dp, default = 0.dp)
            }

            // Bind elevation as the value for LocalElevations
            CompositionLocalProvider(LocalElevations provides elevations) {
                // ... Content goes here ...
                // This part of Composition will see the `elevations` instance
                // when accessing LocalElevations.current
            }
        }
    }
}
CompositionLocalSnippets.kt

CompositionLocal nutzen

CompositionLocal.current gibt den Wert des nächstgelegenen CompositionLocalProvider zurück, der einen Wert für diesen CompositionLocal angibt:

@Composable
fun SomeComposable() {
    // Access the globally defined LocalElevations variable to get the
    // current Elevations in this part of the Composition
    MyCard(elevation = LocalElevations.current.card) {
        // Content
    }
}
CompositionLocalSnippets.kt

Alternativen in Betracht ziehen

CompositionLocal kann für manche Anwendungsfälle eine übermäßige Lösung sein. Wenn Ihr Anwendungsfall nicht die Kriterien erfüllt, die unter Verwendung CompositionLocal angezeigt wird, könnte eine andere Lösung wahrscheinlich besser sein die für Ihren Anwendungsfall geeignet sind.

Explizite Parameter übergeben

Es ist eine gute Angewohnheit, die Abhängigkeiten von Composeable-Komponenten explizit anzugeben. Wir empfehlen, Sie zusammensetzbare Funktionen nur das übergeben, was sie benötigen. Um die Entkopplung zu fördern, und Wiederverwendung von zusammensetzbaren Funktionen ist, sollte jede zusammensetzbare Funktion die geringste Menge an Informationen möglich sind.

@Composable
fun MyComposable(myViewModel: MyViewModel = viewModel()) {
    // ...
    MyDescendant(myViewModel.data)
}

// Don't pass the whole object! Just what the descendant needs.
// Also, don't  pass the ViewModel as an implicit dependency using
// a CompositionLocal.
@Composable
fun MyDescendant(myViewModel: MyViewModel) { /* ... */ }

// Pass only what the descendant needs
@Composable
fun MyDescendant(data: DataToDisplay) {
    // Display data
}
CompositionLocalSnippets.kt

Inversion of Control

Eine weitere Möglichkeit, unnötige Abhängigkeiten an ein composable zu übergeben, ist die Inversion of Control. Anstatt eine Abhängigkeit vom Nachfolger Logik ausführen, macht das übergeordnete Element dies stattdessen.

Im folgenden Beispiel wird gezeigt, wie ein Nachfolger die Anfrage auslösen muss, um Daten laden:

@Composable
fun MyComposable(myViewModel: MyViewModel = viewModel()) {
    // ...
    MyDescendant(myViewModel)
}

@Composable
fun MyDescendant(myViewModel: MyViewModel) {
    Button(onClick = { myViewModel.loadData() }) {
        Text("Load data")
    }
}
CompositionLocalSnippets.kt

Je nach Fall kann MyDescendant viel Verantwortung übernehmen. Außerdem ist MyDescendant dann weniger wiederverwendbar, da sie jetzt miteinander verknüpft sind. Betrachten Sie die Alternative, bei der die Abhängigkeit nicht an den untergeordneten Knoten übergeben wird und die Prinzipien der Inversion of Control verwendet, die den übergeordneten Knoten für die Ausführung der Logik verantwortlich machen:

@Composable
fun MyComposable(myViewModel: MyViewModel = viewModel()) {
    // ...
    ReusableLoadDataButton(
        onLoadClick = {
            myViewModel.loadData()
        }
    )
}

@Composable
fun ReusableLoadDataButton(onLoadClick: () -> Unit) {
    Button(onClick = onLoadClick) {
        Text("Load data")
    }
}
CompositionLocalSnippets.kt

Dieser Ansatz kann für einige Anwendungsfälle besser geeignet sein, da das untergeordnete Element von seinen unmittelbaren Vorfahren getrennt wird. Zusammensetzbare Funktionen mit Ancestors zugunsten flexibler zusammensetzbarer Funktionen auf unterer Ebene.

@Composable Content-Lambdas können ebenfalls auf die gleiche Weise verwendet werden, Vorteile:

@Composable
fun MyComposable(myViewModel: MyViewModel = viewModel()) {
    // ...
    ReusablePartOfTheScreen(
        content = {
            Button(
                onClick = {
                    myViewModel.loadData()
                }
            ) {
                Text("Confirm")
            }
        }
    )
}

@Composable
fun ReusablePartOfTheScreen(content: @Composable () -> Unit) {
    Column {
        // ...
        content()
    }
}
CompositionLocalSnippets.kt