Compose 为常见行为提供了许多开箱即用的修饰符,但您也可以创建自己的自定义修饰符。
修饰符包含多个部分:
- 修饰符工厂
- 这是
Modifier
的扩展函数,可为修饰符提供惯用的 API,并可将修饰符轻松链接到一起。修饰符工厂生成了 Compose 用于修改界面的修饰符元素。
- 这是
- 修饰符元素
- 您可以在这里实现修饰符的行为。
您可以通过多种方式实现自定义修饰符,具体取决于所需的功能。通常,实现自定义修饰符的最简单方式就是实现一个自定义修饰符工厂,将其他已定义的修饰符工厂组合在一起。如果您需要更多自定义行为,请使用 Modifier.Node
API 实现修饰符元素,这些 API 级别较低,但灵活性更高。
将现有修饰符链接在一起
通常,只需使用现有的修饰符即可创建自定义修饰符。例如,Modifier.clip()
是使用 graphicsLayer
修饰符实现的。此策略使用现有的修饰符元素,您需要提供自己的自定义修饰符工厂。
在实现自己的自定义修饰符之前,看看是否可以使用相同的策略。
fun Modifier.clip(shape: Shape) = graphicsLayer(shape = shape, clip = true)
或者,如果您发现自己经常重复同一组修饰符,可以将它们封装到自己的修饰符中:
fun Modifier.myBackground(color: Color) = padding(16.dp) .clip(RoundedCornerShape(8.dp)) .background(color)
使用可组合修饰符工厂创建自定义修饰符
您还可以使用可组合函数创建自定义修饰符,以将值传递给现有修饰符。这称为可组合修饰符工厂。
使用可组合修饰符工厂创建修饰符还允许使用更高级别的 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 } }
如果您的自定义修饰符是一种从 CompositionLocal
提供默认值的便捷方法,那么最简单的实现方法是使用可组合项修饰符工厂:
@Composable fun Modifier.fadedBackground(): Modifier { val color = LocalContentColor.current return this then Modifier.background(color.copy(alpha = 0.5f)) }
此方法有一些注意事项,详见下文。
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) } } }
如果这不是您期望的修饰符的工作方式,请改用自定义 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 }
使用 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) } }
在此示例中,它会使用传入修饰符函数的颜色来绘制圆形。
节点会实现 Modifier.Node
以及零个或多个节点类型。根据修饰符所需的功能,有不同的节点类型。上面的示例需要能够绘制,因此实现了 DrawModifierNode
,从而允许其替换绘制方法。
可用的类型如下:
节点 |
用法 |
示例链接 |
一个 |
||
绘制到布局空间中的 |
||
实现此接口可让 |
||
一个 |
||
一个 |
||
为父布局提供数据的 |
||
一个 |
||
一个 |
||
实现 |
||
一个能够将工作委托给其他 这有助于将多个节点实现组合为一个。 |
||
允许 |
对节点的相应元素调用更新时,节点会自动失效。由于我们的示例是 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 } }
ModifierNodeElement
实现需要替换以下方法:
create
:此函数用于实例化修饰符节点。首次应用修饰符时,系统会调用此方法来创建节点。通常,这相当于构造节点并使用传入到修饰符工厂的参数对其进行配置。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)
完整示例
以下三个部分结合在一起,可用于创建自定义修饰符,以使用 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) } }
使用 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) } } }
引用 CompositionLocal
Modifier.Node
修饰符不会自动观察对 Compose 状态对象的更改,如 CompositionLocal
。与刚刚使用可组合项工厂创建的修饰符相比,Modifier.Node
修饰符的优势在于,它们可以从界面树中使用该修饰符的位置(而不是分配该修饰符的位置)读取局部组合的值,而使用 currentValueOf
。
不过,修饰符节点实例不会自动观察状态变化。如需自动响应 CompositionLocal 的变化,您可以在作用域内读取其当前值:
DrawModifierNode
:ContentDrawScope
LayoutModifierNode
:MeasureScope
和IntrinsicMeasureScope
SemanticsModifierNode
:SemanticsPropertyReceiver
此示例会观察 LocalContentColor
的值,以根据背景的颜色绘制背景。由于 ContentDrawScope
会观察到快照更改,因此当 LocalContentColor
的值发生更改时,系统会自动重新绘制:
class BackgroundColorConsumerNode : Modifier.Node(), DrawModifierNode, CompositionLocalConsumerModifierNode { override fun ContentDrawScope.draw() { val currentColor = currentValueOf(LocalContentColor) drawRect(color = currentColor) drawContent() } }
如需响应范围外的状态变化并自动更新修饰符,请使用 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) } }
为修饰符添加动画效果
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) ) { } } } }
使用委托在修饰符之间共享状态
Modifier.Node
修饰符可以委托给其他节点。这有很多用途,例如跨不同修饰符提取常见实现,但也可用于在修饰符之间共享共同状态。
例如,共享互动数据的可点击修饰符节点的基本实现如下:
class ClickableNode : DelegatingNode() { val interactionData = InteractionData() val focusableNode = delegate( FocusableNode(interactionData) ) val indicationNode = delegate( IndicationNode(interactionData) ) }
选择停用节点自动失效功能
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) } } }