Jetpack Compose 中的对齐线

借助 Compose 布局模型,您可以使用 AlignmentLine 创建自定义对齐线,父布局可以使用这些对齐线来对齐和定位其子级。例如,Row 可以使用其子级的自定义对齐线来对齐它们。

当布局为特定 AlignmentLine 提供值时,布局的父级可以在测量后使用相应 Placeable 实例上的 Placeable.get 运算符读取此值。然后,父级可以根据 AlignmentLine 的位置决定子级的位置。

Compose 中的某些可组合项已附带对齐线。例如,BasicText 可组合项会公开 FirstBaseline 和 LastBaseline 对齐线。

在以下示例中,名为 firstBaselineToTop 的自定义 LayoutModifier 会读取 FirstBaseline,向 Text 添加自其第一条基线起的内边距。

显示了向元素添加正常的内边距与将内边距应用到文本元素的基线之间的差异。
图 1. 显示了向元素添加正常内边距与向文本元素的基线应用内边距之间的差异。

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))
    }
}

为了读取示例中的 FirstBaseline,在测量阶段使用了 placeable [FirstBaseline]。

以下示例使用 paddingFrom 将 Text 的第一条基线放置在距离顶部 32 dp 的位置,就像 firstBaselineToTop 示例一样。如需从文本的第一条和最后一条基线开始填充,请使用 paddingFromBaseline。

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

“Hi there!”文本,其第一条基线上方有 32 dp 的内边距。
图 2. Text,其第一个基线之前有 32 dp 的内边距。

对齐行的子项

在 Row 中,alignByBaseline 和 alignBy 修饰符可让子级在对齐线上相互对齐。这两个修饰符都是 RowScope 的成员,因此您只能在 RowScope(例如 Row 的内容)中使用它们。将修饰符应用于必须对齐的每个子级。如果子级没有该属性,也没有 align,则会遵循 Row 的 verticalAlignment。

以下示例将两个不同大小的文本在其第一条基线上对齐:

@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
            )
        }
    }
}

标题文本和较小的副标题文本在基线上对齐。
图 3. 两个大小不同的 Text 元素在第一条基线上对齐。

alignByBaseline 与 alignBy(FirstBaseline) 相同。如需在非对齐线的位置上对齐,请将一个块传递给 alignBy。该块会接收测量的子项,并返回从子项顶部到要对齐的线的距离(以像素为单位)。在以下示例中,小框的中间位于其旁边文本的基线上:

@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()
            )
        }
    }
}

灰色小正方形,在标签文本的基线上垂直居中。
图 4. 一个灰色的 Box,其垂直中心与相邻 Text 的基线对齐。

使用这些修饰符的子项会形成一个组。Row 会放置该组的至少一个子级,就像它具有 Alignment.Top 一样,并放置其他子级,使其线条匹配。如果组中只有一个子级,则该子级会像具有 Alignment.Top 一样放置,因此不会与任何内容对齐。alignBy 是 align 的一种形式,因此这两个修饰符无法在同一子级上协同工作。

paddingFrom 和 alignBy 解决不同的问题:paddingFrom 根据元素自身的对齐线向其添加内边距,而 alignBy 则使同级元素彼此对齐。

在 Column 中,alignBy 接受 VerticalAlignmentLine 或代码块,并水平对齐子项。ColumnScope没有alignByBaseline。

创建自定义对齐线

创建自定义 Layout 可组合项或自定义 LayoutModifier 时,您可以提供自定义对齐线,以便其他父级可组合项可以使用它们来相应地对齐和放置其子级。

以下示例展示了一个自定义 BarChart 可组合项,它公开了两条对齐线:MaxChartValue 和 MinChartValue;这样,其他可组合项就可以对齐到图表的最大和最小数据值。两个文本元素(Max 和 Min)已与自定义对齐线的中心对齐。

BarChart 可组合项,其中 Text 与最大和最小数据值对齐。
图 5. BarChart 可组合项,其中文本与最大和最小数据值对齐。

自定义对齐线在项目中定义为顶级变量。

/**
 * 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)
})

我们的示例中用到的自定义对齐线属于 HorizontalAlignmentLine 类型,因为它们用于垂直对齐子项。如果多个布局为这些对齐线提供了一个值,系统就会以参数的形式传递合并政策。由于 Compose 布局系统坐标和 Canvas 坐标代表 [0, 0],左上角以及 x 轴和 y 轴的正方向都是向下的,因此 MaxChartValue 值将始终小于 MinChartValue。因此,对于最大图表数据值基线,合并策略为 min;对于最小图表数据值基线,合并策略为 max。

创建自定义 Layout 或 LayoutModifier 时,请在接受 alignmentLines: Map<AlignmentLine, Int> 参数的 MeasureScope.layout 方法中指定自定义对齐线。

@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()
                        )
                    ) {}
                }
            }
        }
    }
}

此可组合项的直接和间接父级均可使用对齐线。以下可组合项会创建一个自定义布局,它将两个 Text 槽和数据点作为参数,并将两个文本与最大和最小图表数据值对齐。此可组合项的预览如图 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)
        )
    }
}