创建自定义修饰符

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 修饰符示例为例，使用可组合函数的实现方式略有不同：

@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，因为组合局部变量将在使用位置正确解析，并且可以安全地提升。

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

系统绝不会跳过可组合工厂修饰符，因为具有返回值的可组合函数无法跳过。这意味着，系统会在每次重组时调用修饰符函数，如果频繁重组，这可能会很耗费资源。

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

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

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 是一个较低级别的 API，用于在 Compose 中创建修饰符。它与 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，以便它可以替换 draw 方法。

可用的类型如下：

节点

用法

示例链接

LayoutModifierNode

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

示例

DrawModifierNode

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

示例

CompositionLocalConsumerModifierNode

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

示例

SemanticsModifierNode

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

示例

PointerInputModifierNode

接收 PointerInputChange 的 Modifier.Node。

示例

ParentDataModifierNode

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

示例

LayoutAwareModifierNode

一个接收 onMeasured 和 onPlaced 回调的 Modifier.Node。

示例

GlobalPositionAwareModifierNode

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

示例

ObserverModifierNode

实现 ObserverNode 的 Modifier.Node 可以提供自己的 onObservedReadsChanged 实现，系统会在响应 observeReads 块中读取的快照对象发生变化时调用该实现。

示例

DelegatingNode

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

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

示例

TraversableNode

允许 Modifier.Node 类向上/向下遍历节点树，以查找同一类型的类或特定键。

示例

当对相应元素调用 update 时，节点会自动失效。由于我们的示例是 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

引用组合本地变量

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

但是，修饰符节点实例不会自动观察状态变化。如需自动响应本地组合变更，您可以在作用域内读取其当前值：

此示例会监控 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

选择停用节点自动失效

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

如果您的自定义修饰符同时修改布局和绘制，这会特别有用。停用自动失效后，您只需在仅绘制相关属性（例如 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

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