Lignes d'alignement dans Jetpack Compose

Le modèle de mise en page Compose vous permet d'utiliser AlignmentLine pour créer des lignes d'alignement personnalisées que les mises en page parentes pourront utiliser pour aligner et positionner leurs enfants. Par exemple, Row peut utiliser les lignes d'alignement personnalisées de ses enfants pour les aligner.

Lorsqu'une mise en page fournit une valeur pour uneAlignmentLine spécifique, les parents de la mise en page peuvent lire cette valeur après la mesure en utilisant l'opérateur Placeable.get sur l'instance Placeable correspondante. En fonction de la position d'AlignmentLine, les parents peuvent ensuite décider du positionnement des enfants.

Certains composables dans Compose sont déjà dotés de lignes d'alignement. Par exemple, le composable BasicText expose les lignes d'alignement FirstBaseline et LastBaseline.

Dans l'exemple ci-dessous, un modificateur de mise en page (LayoutModifier) personnalisé nommé firstBaselineToTop lit la première ligne de base (FirstBaseline) pour ajouter une marge intérieure au texte (Text) à partir de sa première ligne de base.

Indique la différence entre l'ajout d'une marge intérieure normale à un élément et l'application d'une marge intérieure à la première ligne de base d'un élément textuel.
Figure 1. Indique la différence entre l'ajout d'une marge intérieure normale à un élément et l'application d'une marge intérieure à la première ligne de base d'un élément de texte.

fun Modifier.firstBaselineToTop(
    firstBaselineToTop: Dp,
) = layout { measurable, constraints ->
    // Measure the composable
    val placeable = measurable.measure(constraints)

    // Check the composable has a first baseline
    check(placeable[FirstBaseline] != AlignmentLine.Unspecified)
    val firstBaseline = placeable[FirstBaseline]

    // Height of the composable with padding - first baseline
    val placeableY = firstBaselineToTop.roundToPx() - firstBaseline
    val height = placeable.height + placeableY
    layout(placeable.width, height) {
        // Where the composable gets placed
        placeable.placeRelative(0, placeableY)
    }
}

@Preview
@Composable
private fun TextWithPaddingToBaseline() {
    MaterialTheme {
        Text("Hi there!", Modifier.firstBaselineToTop(32.dp))
    }
}

Pour lire la FirstBaseline dans l'exemple, placeable [FirstBaseline] est utilisé dans la phase de mesure.

L'exemple suivant utilise paddingFrom pour placer la première ligne de base de Text à 32 dp du haut, comme dans l'exemple firstBaselineToTop. Pour ajouter une marge intérieure à partir de la première et de la dernière ligne de texte, utilisez paddingFromBaseline.

@Composable
private fun TextWithPaddingFromBaseline() {
    MaterialTheme {
        Text("Hi there!", Modifier.paddingFrom(FirstBaseline, before = 32.dp))
    }
}

Texte "Hi there!" avec une marge intérieure de 32 dp au-dessus de sa première ligne de base.
Figure 2. Text avec 32 dp de marge intérieure avant sa première ligne de base.

Aligner les enfants d'une ligne

Dans un Row, les modificateurs alignByBaseline et alignBy alignent les enfants les uns par rapport aux autres sur une ligne d'alignement. Les deux modificateurs sont membres de RowScope. Vous ne pouvez donc les utiliser que dans un RowScope, tel que le contenu d'un Row. Appliquez le modificateur à chaque enfant qui doit être aligné. Un enfant sans cet attribut et sans align suit la valeur verticalAlignment de l'élément Row.

L'exemple suivant aligne deux textes de tailles différentes sur leurs premières lignes de base :

@Composable
private fun TitleWithSubtitle() {
    MaterialTheme {
        Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            Text(
                "Title",
                modifier = Modifier.alignByBaseline(),
                style = MaterialTheme.typography.headlineMedium
            )
            Text(
                "Subtitle",
                modifier = Modifier.alignByBaseline(),
                style = MaterialTheme.typography.bodySmall
            )
        }
    }
}

Texte du titre et texte du sous-titre plus petit alignés sur leurs lignes de base.
Figure 3. Deux éléments Text de tailles différentes alignés sur leurs premières lignes de base.

alignByBaseline est identique à alignBy(FirstBaseline). Pour aligner sur une position qui n'est pas une ligne d'alignement, transmettez un bloc à alignBy. Le bloc reçoit l'enfant mesuré et renvoie la distance, en pixels, entre le haut de l'enfant et la ligne sur laquelle l'aligner. Dans l'exemple suivant, le milieu d'une petite boîte se trouve sur la ligne de base du texte à côté :

@Composable
private fun BoxMiddleOnBaseline() {
    MaterialTheme {
        Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            Box(
                modifier = Modifier
                    .size(8.dp)
                    .background(Color.Gray)
                    // Aligns the middle of the box with the text baseline.
                    .alignBy { it.measuredHeight / 2 }
            )
            Text(
                "Label",
                modifier = Modifier.alignByBaseline()
            )
        }
    }
}

Petit carré gris centré verticalement sur la ligne de base du texte du libellé.
Figure 4. Un Box gris dont le centre vertical est aligné sur la ligne de base du Text adjacent.

Les enfants qui utilisent ces modificateurs forment un groupe. Row place au moins un enfant du groupe comme s'il avait Alignment.Top et positionne les autres de manière à ce que leurs lignes correspondent. Un enfant seul dans le groupe est placé comme s'il avait Alignment.Top, de sorte qu'il ne s'aligne sur rien. alignBy est une forme de align. Les deux modificateurs ne fonctionnent donc pas ensemble sur le même enfant.

paddingFrom et alignBy résolvent des problèmes différents : paddingFrom ajoute une marge intérieure à un élément en fonction de sa propre ligne d'alignement, et alignBy aligne les éléments frères les uns avec les autres.

Dans un Column, alignBy utilise un VerticalAlignmentLine ou un bloc, et aligne les éléments enfants horizontalement. ColumnScope n'a pas de alignByBaseline.

Créer des lignes d'alignement personnalisées

Lorsque vous créez un composable Layout ou LayoutModifier personnalisé, vous pouvez fournir des lignes d'alignement personnalisées afin que d'autres composables parents puissent les utiliser pour aligner et positionner leurs enfants.

L'exemple suivant montre un composable BarChart personnalisé qui expose deux lignes d'alignement, MaxChartValue et MinChartValue, afin que d'autres composables puissent s'aligner sur les valeurs maximale et minimale des données du graphique. Deux éléments de texte, Max et Min, ont été alignés au centre des lignes d'alignement personnalisées.

Composable BarChart avec texte aligné sur les valeurs maximale et minimale des données.
Figure 5 : BarChart composable avec texte aligné sur les valeurs maximale et minimale des données.

Les lignes d'alignement personnalisées sont définies comme des variables de niveau supérieur dans votre projet.

/**
 * AlignmentLine defined by the maximum data value in a [BarChart]
 */
private val MaxChartValue = HorizontalAlignmentLine(merger = { old, new ->
    min(old, new)
})

/**
 * AlignmentLine defined by the minimum data value in a [BarChart]
 */
private val MinChartValue = HorizontalAlignmentLine(merger = { old, new ->
    max(old, new)
})

Les lignes d'alignement personnalisées utilisées pour notre exemple sont de type HorizontalAlignmentLine, car elles permettent d'aligner verticalement les enfants. Une règle de fusion est transmise en tant que paramètre si plusieurs mises en page fournissent une valeur pour ces lignes d'alignement. Puisque les coordonnées du système de mise en page Compose et celle de Canvas représentent [0, 0], le coin supérieur gauche et les axes x ety sont des valeurs positives vers le bas de sorte que la valeur MaxChartValue sera toujours inférieure à celle de MinChartValue. Par conséquent, la règle de fusion est min pour la valeur de référence maximale des données de graphique et max pour la valeur de référence minimale.

Lorsque vous créez une Layout ou un LayoutModifier personnalisé, spécifiez des lignes d'alignement personnalisées dans la méthode MeasureScope.layout, qui accepte un paramètre alignmentLines: Map<AlignmentLine, Int>.

@Composable
private fun BarChart(
    dataPoints: List<Int>,
    modifier: Modifier = Modifier,
) {
    val maxValue: Float = remember(dataPoints) { dataPoints.maxOrNull()!! * 1.2f }

    BoxWithConstraints(modifier = modifier) {
        val density = LocalDensity.current
        with(density) {
            // ...
            // Calculate baselines
            val maxYBaseline = // ...
            val minYBaseline = // ...
            Layout(
                content = {},
                modifier = Modifier.drawBehind {
                    // ...
                }
            ) { _, constraints ->
                with(constraints) {
                    layout(
                        width = if (hasBoundedWidth) maxWidth else minWidth,
                        height = if (hasBoundedHeight) maxHeight else minHeight,
                        // Custom AlignmentLines are set here. These are propagated
                        // to direct and indirect parent composables.
                        alignmentLines = mapOf(
                            MinChartValue to minYBaseline.roundToInt(),
                            MaxChartValue to maxYBaseline.roundToInt()
                        )
                    ) {}
                }
            }
        }
    }
}

Les parents directs et indirects de ce composable peuvent utiliser les lignes d'alignement. Le composable suivant crée une mise en page personnalisée qui utilise comme paramètre deux emplacements Text et points de données, et aligne les deux textes avec les valeurs maximales et minimales des données de graphique. L'aperçu de ce composable est illustré dans la Figure 5.

@Composable
private fun BarChartMinMax(
    dataPoints: List<Int>,
    maxText: @Composable () -> Unit,
    minText: @Composable () -> Unit,
    modifier: Modifier = Modifier,
) {
    Layout(
        content = {
            maxText()
            minText()
            // Set a fixed size to make the example easier to follow
            BarChart(dataPoints, Modifier.size(200.dp))
        },
        modifier = modifier
    ) { measurables, constraints ->
        check(measurables.size == 3)
        val placeables = measurables.map {
            it.measure(constraints.copy(minWidth = 0, minHeight = 0))
        }

        val maxTextPlaceable = placeables[0]
        val minTextPlaceable = placeables[1]
        val barChartPlaceable = placeables[2]

        // Obtain the alignment lines from BarChart to position the Text
        val minValueBaseline = barChartPlaceable[MinChartValue]
        val maxValueBaseline = barChartPlaceable[MaxChartValue]
        layout(constraints.maxWidth, constraints.maxHeight) {
            maxTextPlaceable.placeRelative(
                x = 0,
                y = maxValueBaseline - (maxTextPlaceable.height / 2)
            )
            minTextPlaceable.placeRelative(
                x = 0,
                y = minValueBaseline - (minTextPlaceable.height / 2)
            )
            barChartPlaceable.placeRelative(
                x = max(maxTextPlaceable.width, minTextPlaceable.width) + 20,
                y = 0
            )
        }
    }
}
@Preview
@Composable
private fun ChartDataPreview() {
    MaterialTheme {
        BarChartMinMax(
            dataPoints = listOf(4, 24, 15),
            maxText = { Text("Max") },
            minText = { Text("Min") },
            modifier = Modifier.padding(24.dp)
        )
    }
}