Modifikatoren für die Inhaltserstellung

Mit Modifikatoren können Sie ein Composeable verzieren oder ergänzen. Mit Modifikatoren Folgendes tun:

  • Größe, Layout, Verhalten und Aussehen der zusammensetzbaren Funktion ändern
  • Informationen wie Labels für Bedienungshilfen hinzufügen
  • Nutzereingabe verarbeiten
  • Fügen Sie allgemeine Interaktionen hinzu, z. B. dass ein Element anklickbar, scrollbar, verschiebbar oder zoombar ist.

Modifikatoren sind standardmäßige Kotlin-Objekte. Erstellen Sie einen Modifizierer, indem Sie eine der Modifier-Klassenfunktionen:

@Composable
private fun Greeting(name: String) {
    Column(modifier = Modifier.padding(24.dp)) {
        Text(text = "Hello,")
        Text(text = name)
    }
}
ModifierSnippets.kt

Zwei Textzeilen auf farbigem Hintergrund mit Innenabständen.

Sie können diese Funktionen verketten, um sie zusammenzusetzen:

@Composable
private fun Greeting(name: String) {
    Column(
        modifier = Modifier
            .padding(24.dp)
            .fillMaxWidth()
    ) {
        Text(text = "Hello,")
        Text(text = name)
    }
}
ModifierSnippets.kt

Der farbige Hintergrund hinter dem Text erstreckt sich jetzt über die gesamte Breite des Geräts.

Im obigen Code werden verschiedene Modifikatorfunktionen zusammen verwendet.

  • padding platziert ein Element mit Platz.
  • Mit fillMaxWidth wird für die zusammensetzbare Füllung die maximale Breite festgelegt, die von in das übergeordnete Element ein.

Als Best Practice hat es sich bewährt, wenn alle zusammensetzbaren Funktionen einen modifier-Wert akzeptieren. und übergeben Sie diesen Modifikator an das erste untergeordnete Element, das UI ausgibt. Dadurch werden Ihre und macht sein Verhalten vorhersehbarer und intuitiver. Für Weitere Informationen finden Sie in den Richtlinien für die Compose API, Elemente akzeptieren und respektieren ein Modifikatorparameter.

Die Reihenfolge der Modifikatoren ist wichtig

Die Reihenfolge der Modifikatorfunktionen ist erheblich. Da jede Funktion ändert sich zu der Modifier, die von der vorherigen Funktion zurückgegeben wurde, die Sequenz das Endergebnis beeinflusst. Sehen wir uns dazu ein Beispiel an:

@Composable
fun ArtistCard(/*...*/) {
    val padding = 16.dp
    Column(
        Modifier
            .clickable(onClick = onClick)
            .padding(padding)
            .fillMaxWidth()
    ) {
        // rest of the implementation
    }
}
ModifierSnippets.kt

Der gesamte Bereich, einschließlich des Abstands an den Rändern, reagiert auf Klicks.

Im Code oben ist der gesamte Bereich anklickbar, einschließlich des umgebenden Abstands, da der Modifikator padding nach dem Modifikator clickable angewendet wurde. Wenn die Reihenfolge der Modifikatoren umgekehrt ist, reagiert der durch padding hinzugefügte Abstand nicht auf Nutzereingaben:

@Composable
fun ArtistCard(/*...*/) {
    val padding = 16.dp
    Column(
        Modifier
            .padding(padding)
            .clickable(onClick = onClick)
            .fillMaxWidth()
    ) {
        // rest of the implementation
    }
}
ModifierSnippets.kt

Der Abstand am Rand des Layouts reagiert nicht mehr auf Klicks.

Integrierte Modifikatoren

Jetpack Compose bietet eine Liste mit integrierten Modifikatoren zum Dekorieren oder um eine zusammensetzbare Funktion zu erweitern. Hier sind einige gängige Modifikatoren, mit denen Sie Ihre Layouts.

padding und size

Standardmäßig umschließen die untergeordneten Layouts in der Funktion „Schreiben“. Sie können jedoch mit dem Modifikator size eine Größe festlegen:

@Composable
fun ArtistCard(/*...*/) {
    Row(
        modifier = Modifier.size(width = 400.dp, height = 100.dp)
    ) {
        Image(/*...*/)
        Column { /*...*/ }
    }
}
ModifierSnippets.kt

Die von Ihnen angegebene Größe wird möglicherweise nicht berücksichtigt, wenn sie nicht den Einschränkungen des übergeordneten Elements des Layouts entspricht. Wenn Sie die zusammensetzbare Funktion Größe unabhängig von den eingehenden Einschränkungen festgelegt werden soll, verwenden Sie die Methode requiredSize. Modifikator:

@Composable
fun ArtistCard(/*...*/) {
    Row(
        modifier = Modifier.size(width = 400.dp, height = 100.dp)
    ) {
        Image(
            /*...*/
            modifier = Modifier.requiredSize(150.dp)
        )
        Column { /*...*/ }
    }
}
ModifierSnippets.kt

Das untergeordnete Bild ist größer als die Einschränkungen des übergeordneten Elements

Selbst wenn das übergeordnete Element height auf 100.dp festgelegt ist, wird die Höhe des Elements Der Image ist 150.dp, da der Modifikator requiredSize Vorrang.

Wenn ein untergeordnetes Layout die gesamte vom übergeordneten Layout zulässige Höhe einnehmen soll, fügen Sie den Modifikator fillMaxHeight hinzu. Compose bietet auch fillMaxSize und fillMaxWidth:

@Composable
fun ArtistCard(/*...*/) {
    Row(
        modifier = Modifier.size(width = 400.dp, height = 100.dp)
    ) {
        Image(
            /*...*/
            modifier = Modifier.fillMaxHeight()
        )
        Column { /*...*/ }
    }
}
ModifierSnippets.kt

Die Bildhöhe ist so groß wie die des übergeordneten Elements.

Wenn Sie allen Seiten eines Elements einen Abstand hinzufügen möchten, legen Sie einen padding-Modifikator fest.

Wenn Sie über einer Textgrundlinie einen bestimmten Abstand vom oberen Rand des Layouts zur Grundlinie schaffen möchten, verwenden Sie den Modifikator paddingFromBaseline:

@Composable
fun ArtistCard(artist: Artist) {
    Row(/*...*/) {
        Column {
            Text(
                text = artist.name,
                modifier = Modifier.paddingFromBaseline(top = 50.dp)
            )
            Text(artist.lastSeenOnline)
        }
    }
}
ModifierSnippets.kt

Text mit einem Abstand darüber

Offset

Wenn Sie ein Layout relativ zu seiner ursprünglichen Position positionieren möchten, fügen Sie den Modifikator offset hinzu und legen Sie den Versatz auf der x- und y-Achse fest. Abweichungen können sowohl positiv als auch negativ sein. Der Unterschied zwischen padding und offset besteht darin, dass die Messwerte eines Composeables durch das Hinzufügen eines offset nicht geändert werden:

@Composable
fun ArtistCard(artist: Artist) {
    Row(/*...*/) {
        Column {
            Text(artist.name)
            Text(
                text = artist.lastSeenOnline,
                modifier = Modifier.offset(x = 4.dp)
            )
        }
    }
}
ModifierSnippets.kt

Text wurde auf die rechte Seite des übergeordneten Containers verschoben

Der offset-Modifikator wird horizontal entsprechend der Layoutrichtung angewendet. In einem rechtsläufigen Kontext verschiebt eine positive offset das Element während es in einem rechts nach links-Kontext das Element nach links verschiebt, Wenn Sie einen Offset festlegen möchten, ohne die Layoutrichtung zu berücksichtigen, sehen Sie sich den Modifikator absoluteOffset an. Bei einem positiven Offsetwert wird das Element immer nach rechts verschoben.

Der Modifikator offset hat zwei Überladungen: offset, bei der die Abweichungen als Parameter übergeben werden, und offset, bei der ein Lambda übergeben wird. Detailliertere Informationen zur Verwendung und Optimierung finden Sie in den Compose-Leistung – Lesevorgänge so lange wie möglich zurückstellen:

Bereichssicherheit in Compose

In Compose gibt es Modifikatoren, die nur auf untergeordnete Elemente bestimmter Composeables angewendet werden können. Compose erzwingt dies mithilfe benutzerdefinierter Bereiche.

Wenn Sie beispielsweise ein untergeordnetes Element so groß wie das übergeordnete Element Box machen möchten, ohne die Größe von Box zu beeinflussen, verwenden Sie den Modifikator matchParentSize. matchParentSize ist nur verfügbar in BoxScope Daher kann es nur für ein untergeordnetes Element innerhalb eines übergeordneten Box-Elements verwendet werden.

Die Bereichssicherheit verhindert, dass Sie Modifikatoren hinzufügen, die in anderen zusammensetzbare Funktionen und Bereiche und spart Zeit durch Versuch und Irrtum.

Mithilfe von bereichsspezifischen Modifikatoren werden Eltern über bestimmte Informationen informiert, die sie über das Kind wissen sollten. Sie werden auch als Modifikatoren für übergeordnete Daten. Ihre internen Strukturen unterscheiden sich vom allgemeinen Zweck. aber aus Nutzungssicht spielen diese Unterschiede keine Rolle.

matchParentSize in Box

Wie bereits erwähnt, verwenden Sie den Modifikator matchParentSize, wenn ein untergeordnetes Layout dieselbe Größe wie ein übergeordnetes Box haben soll, ohne dass sich die Größe von Box ändert.

Hinweis: matchParentSize ist nur im Bereich Box verfügbar. Das bedeutet, dass es nur auf direkte untergeordnete Elemente von Box-Kompositen angewendet werden kann.

Im folgenden Beispiel übernimmt das untergeordnete Element Spacer seine Größe von seinem übergeordneten Element Box, das wiederum seine Größe von den größten untergeordneten Elementen übernimmt, in diesem Fall von ArtistCard.

@Composable
fun MatchParentSizeComposable() {
    Box {
        Spacer(
            Modifier
                .matchParentSize()
                .background(Color.LightGray)
        )
        ArtistCard()
    }
}
ModifierSnippets.kt

Behälter mit grauem Hintergrund

Wenn anstelle von matchParentSize fillMaxSize verwendet würde, würde Spacer den gesamten für das übergeordnete Element verfügbaren Platz einnehmen, wodurch sich das übergeordnete Element ausdehnt und den gesamten verfügbaren Platz einnimmt.

Grauer Hintergrund, der den gesamten Bildschirm ausfüllt

weight in Row und Column

Wie Sie im vorherigen Abschnitt zu Abstand und Größe gesehen haben, wird die Größe eines Elements standardmäßig durch den Inhalt definiert, der umgebrochen wird. Mit dem weight-Modifikator, der nur in RowScope und ColumnScope verfügbar ist, können Sie die Größe eines Elements im übergeordneten Element flexibel festlegen.

Nehmen wir als Beispiel eine Row mit zwei Box-Kompositionen. Das erste Feld hat doppelt so viel weight wie das zweite, also doppelt so viel Breite. Da Row 210.dp breit ist, ist der erste Box 140.dp breit und Die zweite ist 70.dp:

@Composable
fun ArtistCard(/*...*/) {
    Row(
        modifier = Modifier.fillMaxWidth()
    ) {
        Image(
            /*...*/
            modifier = Modifier.weight(2f)
        )
        Column(
            modifier = Modifier.weight(1f)
        ) {
            /*...*/
        }
    }
}
ModifierSnippets.kt

Die Bildbreite ist doppelt so groß wie die Textbreite.

Modifikatoren extrahieren und wiederverwenden

Mehrere Modifikatoren können miteinander verknüpft werden, um ein Composeable zu verzieren oder zu ergänzen. Diese Kette wird über die Modifier-Schnittstelle erstellt, die eine sortierte, unveränderliche Liste einzelner Modifier.Elements darstellt.

Jedes Modifier.Element steht für ein individuelles Verhalten, z. B. für das Layout, das Zeichnen und die Grafik, alle gestenbezogenen, Fokus- und semantischen Verhaltensweisen sowie Geräteeingabeereignisse. Ihre Reihenfolge ist wichtig: Modifikatorelemente, die zuerst hinzugefügt wurden.

Manchmal kann es vorteilhaft sein, dieselben Modifikatorketteninstanzen in mehreren Composeable-Objekten wiederzuverwenden. Dazu werden sie in Variablen extrahiert und in einen höheren Gültigkeitsbereich verschoben. Sie kann die Lesbarkeit von Code oder aus verschiedenen Gründen:

  • Die Neuzuweisung der Modifikatoren wird bei einer Neuzusammensetzung nicht wiederholt. für zusammensetzbare Funktionen verwenden,
  • Modifikatorketten könnten sehr lang und komplex sein. Dieselbe Instanz einer Kette kann den Aufwand für die Arbeitslast verringern, die die Compose-Laufzeit wenn Sie sie vergleichen,
  • Diese Extraktion fördert die Sauberkeit, Einheitlichkeit und Verwaltbarkeit des Codes in der gesamten Codebasis

Best Practices für die Wiederverwendung von Modifikatoren

Erstellen Sie eigene Modifier-Ketten und extrahieren Sie sie, um sie für mehrere zusammensetzbare Komponenten wiederzuverwenden. Es ist völlig in Ordnung, nur einen Modifikator zu speichern, da es sich um datengestützte Objekte handelt:

val reusableModifier = Modifier
    .fillMaxWidth()
    .background(Color.Red)
    .padding(12.dp)
ModifierSnippets.kt

Modifikatoren bei häufig wechselndem Status extrahieren und wiederverwenden

Wenn sich die Status in Composeables häufig ändern, z. B. Animationen oder scrollState, kann es zu einer erheblichen Anzahl von Neuzusammensetzungen kommen. In diesem Fall werden Ihre Modifikatoren bei jeder Neuzusammensetzung und möglicherweise für jeden Frame:

@Composable
fun LoadingWheelAnimation() {
    val animatedState = animateFloatAsState(/*...*/)

    LoadingWheel(
        // Creation and allocation of this modifier will happen on every frame of the animation!
        modifier = Modifier
            .padding(12.dp)
            .background(Color.Gray),
        animatedState = animatedState
    )
}
ModifierSnippets.kt

Stattdessen können Sie dieselbe Instanz des Modifikators erstellen, extrahieren und wiederverwenden. und übergeben es wie folgt an die zusammensetzbare Funktion:

// Now, the allocation of the modifier happens here:
val reusableModifier = Modifier
    .padding(12.dp)
    .background(Color.Gray)

@Composable
fun LoadingWheelAnimation() {
    val animatedState = animateFloatAsState(/*...*/)

    LoadingWheel(
        // No allocation, as we're just reusing the same instance
        modifier = reusableModifier,
        animatedState = animatedState
    )
}
ModifierSnippets.kt

Modifikatoren ohne Bereich extrahieren und wiederverwenden

Modifikatoren können auf einen bestimmten Geltungsbereich oder auf einen bestimmten zusammensetzbar sind. Modifier ohne Bereich können Sie ganz einfach außerhalb von Composables als einfache Variablen extrahieren:

val reusableModifier = Modifier
    .fillMaxWidth()
    .background(Color.Red)
    .padding(12.dp)

@Composable
fun AuthorField() {
    HeaderText(
        // ...
        modifier = reusableModifier
    )
    SubtitleText(
        // ...
        modifier = reusableModifier
    )
}
ModifierSnippets.kt

Das kann besonders vorteilhaft sein, wenn es mit Lazy-Layouts kombiniert wird. In den meisten Fällen sollten alle Ihre Artikel (die möglicherweise sehr zahlreich sind) genau dieselben Modifikatoren haben:

val reusableItemModifier = Modifier
    .padding(bottom = 12.dp)
    .size(216.dp)
    .clip(CircleShape)

@Composable
private fun AuthorList(authors: List<Author>) {
    LazyColumn {
        items(authors) {
            AsyncImage(
                // ...
                modifier = reusableItemModifier,
            )
        }
    }
}
ModifierSnippets.kt

Modifikatoren mit Bereich extrahieren und wiederverwenden

Wenn Sie mit Modifikatoren arbeiten, die auf bestimmte Composeables beschränkt sind, können Sie sie auf die höchstmögliche Ebene extrahieren und bei Bedarf wiederverwenden:

Column(/*...*/) {
    val reusableItemModifier = Modifier
        .padding(bottom = 12.dp)
        // Align Modifier.Element requires a ColumnScope
        .align(Alignment.CenterHorizontally)
        .weight(1f)
    Text1(
        modifier = reusableItemModifier,
        // ...
    )
    Text2(
        modifier = reusableItemModifier
        // ...
    )
    // ...
}
ModifierSnippets.kt

Sie sollten nur die extrahierten Bereichsmodifikatoren an den direkte untergeordnete Elemente des gleichen Bereichs. Weitere Informationen finden Sie im Abschnitt Sicherheit des Umfangs in Schreiben Sie, um mehr darüber zu erfahren, warum das wichtig ist:

Column(modifier = Modifier.fillMaxWidth()) {
    // Weight modifier is scoped to the Column composable
    val reusableItemModifier = Modifier.weight(1f)

    // Weight will be properly assigned here since this Text is a direct child of Column
    Text1(
        modifier = reusableItemModifier
        // ...
    )

    Box {
        Text2(
            // Weight won't do anything here since the Text composable is not a direct child of Column
            modifier = reusableItemModifier
            // ...
        )
    }
}
ModifierSnippets.kt

Weitere Verkettung extrahierter Modifikatoren

Sie können die extrahierten Modifikatorketten weiter verketten oder anhängen, indem Sie die Methode .then()-Funktion:

val reusableModifier = Modifier
    .fillMaxWidth()
    .background(Color.Red)
    .padding(12.dp)

// Append to your reusableModifier
reusableModifier.clickable { /*...*/ }

// Append your reusableModifier
otherModifier.then(reusableModifier)
ModifierSnippets.kt

Denken Sie daran, dass die Reihenfolge der Modifikatoren wichtig ist.

Weitere Informationen

Wir stellen eine vollständige Liste der Modifikatoren bereit, mit ihre Parameter und Bereiche.

Weitere Übungen zur Verwendung von Modifikatoren finden Sie in den Grundlegende Layouts im Codelab zu „Compose“ oder im Jetzt im Android-Repository.

Weitere Informationen zu benutzerdefinierten Modifikatoren und deren Erstellung finden Sie in der Dokumentation unter Benutzerdefinierte Layouts – Layout-Modifikator verwenden.