创建自定义修饰符

Compose 为常见行为提供了许多开箱即用的修饰符，但您也可以创建自己的自定义修饰符。

修饰符包含多个部分：

  • 修饰符工厂
    • 这是 Modifier 的扩展函数，可为修饰符提供惯用的 API，并可将修饰符轻松链接到一起。修饰符工厂生成了 Compose 用于修改界面的修饰符元素。
  • 修饰符元素
    • 您可以在这里实现修饰符的行为。

您可以通过多种方式实现自定义修饰符，具体取决于所需的功能。通常，实现自定义修饰符的最简单方式就是实现一个自定义修饰符工厂，将其他已定义的修饰符工厂组合在一起。如果您需要更多自定义行为，请使用 Modifier.Node API 实现修饰符元素，这些 API 级别较低，但灵活性更高。

将现有修饰符链接在一起

通常，只需使用现有的修饰符即可创建自定义修饰符。例如，Modifier.clip() 是使用 graphicsLayer 修饰符实现的。此策略使用现有的修饰符元素，您需要提供自己的自定义修饰符工厂。

在实现自己的自定义修饰符之前，看看是否可以使用相同的策略。

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

或者，如果您发现自己经常重复同一组修饰符，可以将它们封装到自己的修饰符中：

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

使用可组合修饰符工厂创建自定义修饰符

您还可以使用可组合函数创建自定义修饰符，以将值传递给现有修饰符。这称为可组合修饰符工厂。

使用可组合修饰符工厂创建修饰符还允许使用更高级别的 Compose API，例如 animate*AsState 和其他 Compose 状态支持的动画 API。例如，以下代码段展示了一个在启用/停用时为 Alpha 变化添加动画效果的修饰符：

@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

如果您的自定义修饰符是一种从 CompositionLocal 提供默认值的便捷方法，那么最简单的实现方法是使用可组合项修饰符工厂：

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

此方法有一些注意事项，详见下文。

CompositionLocal 值在修饰符工厂的调用点进行解析

使用可组合项修饰符工厂创建自定义修饰符时，CompositionLocal 从创建它们（而非使用它们）的组合树中获取相应值。这可能会导致意外结果。以上面的 CompositionLocal 修饰符示例为例，使用可组合函数实现的方式略有不同：

@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

如果这不是您期望的修饰符的工作方式，请改用自定义 Modifier.Node，因为 CompositionLocal 会在使用点正确解析，并且可以安全提升。

绝不会跳过可组合函数修饰符

永远不会跳过可组合工厂修饰符，因为无法跳过具有返回值的可组合函数。这意味着每次重组时都会调用修饰符函数，如果频繁重组，费用可能会很高。

可组合函数修饰符必须在可组合函数中调用

与所有可组合函数一样，必须从组合中调用可组合工厂修饰符。这限制了修饰符可以提升到的位置，因为它永远无法从组合中提升。相比之下，非可组合项修饰符工厂可以从可组合函数中提升出来，以便更轻松地重复使用并提高性能：

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

使用 Modifier.Node 实现自定义修饰符行为

Modifier.Node 是用于在 Compose 中创建修饰符的较低级别的 API。它与 Compose 实现自己的修饰符的 API 相同，也是创建自定义修饰符的最高效方式。

使用 Modifier.Node 实现自定义修饰符

使用 Modifier.Node 实现自定义修饰符的过程分为三个部分：

  • Modifier.Node 实现，用于存储修饰符的逻辑和状态。
  • ModifierNodeElement，用于创建和更新修饰符节点实例。
  • 可选的修饰符工厂（如上文所述）。

ModifierNodeElement 类是无状态的，每次重组都会分配新实例，而 Modifier.Node 类可以是有状态的，将在多次重组后继续存在，甚至可以重复使用。

以下部分介绍了各个部分，并举例说明了如何构建自定义修饰符来绘制圆形。

Modifier.Node

Modifier.Node 实现（在此示例中为 CircleNode）实现了自定义修饰符的功能。

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

在此示例中，它会使用传入修饰符函数的颜色来绘制圆形。

节点会实现 Modifier.Node 以及零个或多个节点类型。根据修饰符所需的功能，有不同的节点类型。上面的示例需要能够绘制，因此实现了 DrawModifierNode，从而允许其替换绘制方法。

可用的类型如下：

节点

用法

示例链接

LayoutModifierNode

一个 Modifier.Node，用于更改其封装内容的测量和布局方式。

示例

DrawModifierNode

绘制到布局空间中的 Modifier.Node。

示例

CompositionLocalConsumerModifierNode

实现此接口可让 Modifier.Node 读取 CompositionLocal。

示例

SemanticsModifierNode

一个 Modifier.Node，用于添加用于测试、无障碍功能和类似用例的语义键值对。

示例

PointerInputModifierNode

一个 Modifier.Node，用于接收 PointerInputChanges.

示例

ParentDataModifierNode

为父布局提供数据的 Modifier.Node。

示例

LayoutAwareModifierNode

一个 Modifier.Node，用于接收 onMeasured 和 onPlaced 回调。

示例

GlobalPositionAwareModifierNode

一个 Modifier.Node，当内容的全局位置可能发生变化时，它会接收包含布局的最终 LayoutCoordinates 的 onGloballyPositioned 回调。

示例

ObserverModifierNode

实现 ObserverNode 的 Modifier.Node 可以提供自己的 onObservedReadsChanged 实现，系统将调用该实现，以响应对 observeReads 块中读取的快照对象所做的更改。

示例

DelegatingNode

一个能够将工作委托给其他 Modifier.Node 实例的 Modifier.Node。

这有助于将多个节点实现组合为一个。

示例

TraversableNode

允许 Modifier.Node 类针对相同类型的类或特定键在节点树中向上/向下遍历。

示例

对节点的相应元素调用更新时，节点会自动失效。由于我们的示例是 DrawModifierNode，因此每次对该元素调用 update 时，节点都会触发重新绘制，并且其颜色会正确地更新。您可以选择不自动失效，详见下文。

ModifierNodeElement

ModifierNodeElement 是一个不可变类，用于存储用于创建或更新自定义修饰符的数据：

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

ModifierNodeElement 实现需要替换以下方法：

  1. create：此函数用于实例化修饰符节点。首次应用修饰符时，系统会调用此方法来创建节点。通常，这相当于构造节点并使用传入到修饰符工厂的参数对其进行配置。
  2. update：每当在此节点已存在的同一位置提供此修饰符，但属性发生更改时，就会调用此函数。这由类的 equals 方法确定。之前创建的修饰符节点会作为参数发送到 update 调用。此时，您应该更新节点的属性，使其与更新后的参数相对应。以这种方式重复使用节点的能力对于 Modifier.Node 带来的性能提升至关重要；因此，您必须更新现有节点，而不是在 update 方法中创建新节点。在我们的圆圈示例中，节点的颜色已更新。

此外，ModifierNodeElement 实现还需要实现 equals 和 hashCode。仅当与前一个元素的等于比较返回 false 时，系统才会调用 update。

上面的示例使用数据类来实现这一点。这些方法用于检查节点是否需要更新。如果元素的属性对是否需要更新节点没有影响，或者由于二进制文件兼容性原因您想要避免使用数据类，您可以手动实现 equals 和 hashCode，例如内边距修饰符元素。

修饰符工厂

这是修饰符的公共 API Surface。大多数实现都直接创建修饰符元素并将其添加到修饰符链中：

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

完整示例

以下三个部分结合在一起，可用于创建自定义修饰符，以使用 Modifier.Node API 绘制圆形：

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

使用 Modifier.Node 的常见情况

使用 Modifier.Node 创建自定义修饰符时，您可能会遇到以下几种常见情况。

零参数

如果您的修饰符没有参数，则它不需要更新，而且也不需要是数据类。下面是将固定数量的内边距应用于可组合项的修饰符的实现示例：

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

引用 CompositionLocal

Modifier.Node 修饰符不会自动观察对 Compose 状态对象的更改，如 CompositionLocal。与刚刚使用可组合项工厂创建的修饰符相比，Modifier.Node 修饰符的优势在于，它们可以从界面树中使用该修饰符的位置（而不是分配该修饰符的位置）读取局部组合的值，而使用 currentValueOf。

不过，修饰符节点实例不会自动观察状态变化。如需自动响应 CompositionLocal 的变化，您可以在作用域内读取其当前值：

此示例会观察 LocalContentColor 的值，以根据背景的颜色绘制背景。由于 ContentDrawScope 会观察到快照更改，因此当 LocalContentColor 的值发生更改时，系统会自动重新绘制：

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

如需响应范围外的状态变化并自动更新修饰符，请使用 ObserverModifierNode。

例如，Modifier.scrollable 使用此方法观察 LocalDensity 中的变化。简单示例如下所示：

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

为修饰符添加动画效果

Modifier.Node 实现可以访问 coroutineScope。这将允许使用 Compose Animatable API。例如，以下代码段将上述 CircleNode 修改为重复淡入和淡出：

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

使用委托在修饰符之间共享状态

Modifier.Node 修饰符可以委托给其他节点。这有很多用途，例如跨不同修饰符提取常见实现，但也可用于在修饰符之间共享共同状态。

例如，共享互动数据的可点击修饰符节点的基本实现如下：

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

选择停用节点自动失效功能

Modifier.Node 节点会在其对应的 ModifierNodeElement 调用更新时自动失效。有时，在更复杂的修饰符中，您可能需要停用此行为，以便更精细地控制修饰符何时失效阶段。

如果您的自定义修饰符同时修改布局和绘制，这会特别有用。选择停用自动失效功能后，您只需在与绘制相关的属性（如 color 更改）和不让布局失效时使绘制失效。这可以提升修饰符的性能。

下面显示了一个假设示例，其修饰符具有 color、size 和 onClick lambda 作为属性。此修饰符只会使所需内容失效，并跳过任何不需要的失效：

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

上一页
约束条件和修饰符顺序
下一页
修饰符列表