mcpField
O
ordering-modifier-chains

ordering-modifier-chains

github.com/skydoves开发520129 次安装19 周前更新
代码仓库

关于 ordering-modifier-chains

面向 Jetpack Compose 开发者的技能，讲解 Modifier 链的顺序如何改变绘制、布局、点击区域和裁剪效果，并提供针对常见症状的调整方式。

主要功能

  1. 01按链顺序分析 Modifier 的包装关系
  2. 02调整 padding 与 background 的先后
  3. 03控制 clickable 的点击区域
  4. 04确定 clip 与背景的绘制顺序
  5. 05理解 graphicsLayer 对子树的作用

适用场景

  1. 01排查背景未覆盖预期区域
  2. 02修正按钮点击范围或涟漪边界
  3. 03让裁剪作用于背景绘制
  4. 04调整透明度或变换所覆盖的内容

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/skydoves/compose-performance-skills --skill ordering-modifier-chains

安装后在 Claude Code 中输入/ordering-modifier-chains确认已加载。

详细介绍

修饰符链的顺序——为什么 padding(8.dp).background(Red) ≠ background(Red).padding(8.dp)

修饰符的顺序很重要，因为每个修饰符都会像函数一样包装下一个修饰符。Modifier.padding(8.dp).background(Red) 会先缩小约束，因此背景会绘制在内侧的填充区域中——周围 8 dp 的边距不会变红。相反，Modifier.background(Red).padding(8.dp) 会先在父级的整个边界内绘制红色，再向内缩进内容。顺序错误是 Compose UI 中仅次于遗漏键的常见 bug。此技能会教 Claude 如何从上到下阅读修饰符链，并正确调整顺序。

何时使用此技能

  • 开发者询问“为什么点击区域会延伸到可见按钮之外？”、“为什么涟漪效果会在错误的形状上跳动？”、“为什么背景绘制在了错误的区域？”或“Modifier 的顺序重要吗？”。
  • 代码审查中发现类似 Modifier.padding(...).clickable { }、Modifier.background(...).clip(...) 或 Modifier.alpha(state.value).graphicsLayer { } 的链。
  • 按钮的点击目标延伸到了周围的填充区域，或者背景没有遵循圆角半径。
  • 父级上的裁剪无法遮罩子级绘制内容，或者 graphicsLayer { alpha = 0.5f } 对同级元素也产生了部分影响。
  • 开发者考虑通过 remember { Modifier.… } 提升 Modifier 链，以“优化性能”。

何时不要使用此技能

  • 链的顺序正确，问题出在别处（例如在错误阶段读取状态、惰性布局中遗漏键）。请先使用 ../../recomposition/deferring-state-reads/SKILL.md 或 ../../lists/optimizing-lazy-layouts/SKILL.md 进行诊断。
  • 问题出在自定义修饰符本身（使用了旧式 composed { }、缺少 diff）→ 请参阅 ../migrating-to-modifier-node/SKILL.md。
  • 问题是是否应该创建自定义修饰符——此技能假设你已经有一串内置修饰符，需要正确排列它们。

先决条件

  • 熟悉 Modifier 组合相关术语（padding、background、clip、clickable、graphicsLayer）。
  • 任意受支持版本的 Compose UI——自 1.0 起，修饰符顺序的语义一直保持稳定。
  • 如需对提升修饰符链作出最终性能结论，请使用真实设备和发布构建（skydoves 热门观点 #5：调试构建会骗人）。

工作流

  • 1. 准确识别症状。 将其归为以下一种：绘制区域错误、点击／指针区域错误、涟漪效果边界错误、裁剪区域错误、内边距测量错误、graphicsLayer 作用域错误。每种情况都对应特定的调整顺序。

  • 2. 从上到下阅读修饰符链——每个修饰符的效果都会作用于它下方的所有内容。 将修饰符链视为嵌套的函数调用：Modifier.a().b().c() 表示“a 包裹（b 包裹（c））”。最上方的修饰符是最外层的包装；最下方的修饰符最靠近内容。

  • 3. 根据症状应用规范顺序。 以下模式涵盖了四种最常见的情况（padding 与 background、clickable 的位置、background 前的 clip、graphicsLayer 的作用域）。

  • 4. 特别注意这些修饰符——顺序会影响实际行为，而非仅仅是风格问题：

    • clickable — 指针命中区域是它在链中所在位置的边界。它上方（外层）的所有内容都会包含在内；它下方（内层）的内容则不会。
    • clip — 会裁剪它下方（内层）的所有内容。它上方的内容不会被裁剪。
    • background — 会在它于链中所在位置的边界内绘制。
    • padding — 会缩减传递给它下方所有内容的可用空间。
    • graphicsLayer — 会将它下方的所有内容包裹在一个渲染层中（alpha、变换和裁剪都会作用于其下方的子树）。

  • 5. 确定触摸目标的无障碍需求。 将 clickable 放在视觉内边距的上方，即可实现 Material 的 48dp 最小触摸目标，让内边距区域也可以点击。代价是：内边距区域也会触发涟漪效果。若只允许点击视觉区域，则将 clickable 放在 padding 下方。

  • 6. 不要为了“性能”而通过 remember 提升 Modifier 链。 Compose 已经会在内部复用结构相等的 Modifier 链；remember { Modifier.fillMaxWidth().padding(16.dp) } 属于微优化，在性能分析中很少能体现出来。不得在没有先通过 FrameTimingMetric 基准测试证明未提升的链会造成可测量的性能退化之前，添加此类 remember。有关在项 lambda 中的分配问题，请参阅 ../../lists/optimizing-lazy-layouts/SKILL.md。

模式

模式：background 在 padding 外部还是内部
// WRONG (when the intent is "padded box with red fill")
Box(Modifier.padding(8.dp).background(Color.Red))
// WRONG because: padding is applied first; background then paints across the inner (padded) bounds — the result is a smaller red region, with no red in the padded margin. If the design intent was "red card with 8dp internal padding", red is on the wrong side of the padding.

// RIGHT — red fills the box; content is inset by 8dp.
Box(Modifier.background(Color.Red).padding(8.dp)) { /* content */ }

反过来组合也有效——但只有当开发者明确不希望红色延伸到周围的内边距区域时才这样做（例如小型内部徽标）。对于“带内部内边距的卡片”，默认采用 background → padding。

模式：clickable 位于 padding 上方还是下方（触摸目标与视觉区域）
// WRONG (when the click should fire only on the visible icon)
Box(Modifier.padding(16.dp).clickable { onTap() })
// WRONG because: clickable's hit region is its position in the chain — and at this position, the bounds INCLUDE the padding. Taps in the padding fire onTap and ripple bounces past the visible icon.

// RIGHT — click only fires on the visible content area.
Box(Modifier.clickable { onTap() }.padding(16.dp))

// RIGHT — accessibility 48dp touch target: extend the tap area into the padding intentionally.
Box(
    Modifier
        .padding(8.dp)            // outer spacing
        .clickable { onTap() }    // tap fires across the next size step
        .padding(16.dp)           // visual padding inside the tap area
)

将 clickable 刻意放在视觉内边距外部、但位于任何外部间距内部，即可实现 48dp 的 Material 最小触摸目标。根据设计意图选择即可——两种顺序都没有“更正确”之分；它们描述的是不同的产品。

模式：clip 位于 background 之前还是之后
// WRONG (rounded card with red fill)
Box(Modifier.background(Color.Red).clip(RoundedCornerShape(8.dp)))
// WRONG because: background paints first across square bounds; clip then applies to children only. The red rectangle is unclipped — corners stay square.

// RIGHT — clip wraps the background, so the red is rounded.
Box(Modifier.clip(RoundedCornerShape(8.dp)).background(Color.Red))

对于同时具有裁剪和背景语义的修饰符，Modifier.background(color = ..., shape = ...) 可在一个节点中完成两者，避免顺序问题：

// RIGHT — single modifier handles shape clipping and fill atomically.
Box(Modifier.background(Color.Red, RoundedCornerShape(8.dp)))
模式：graphicsLayer 会包裹它下方的所有内容
// RIGHT — alpha applies to the entire subtree (background + content).
Box(
    Modifier
        .graphicsLayer { alpha = 0.5f }
        .background(Color.Red)
        .padding(8.dp)
) { Text("Half-faded card") }

// WRONG — alpha only fades the content; background is fully opaque.
Box(
    Modifier
        .background(Color.Red)
        .padding(8.dp)
        .graphicsLayer { alpha = 0.5f }
) { Text("Surprising opacity") }
// WRONG because: graphicsLayer wraps only what's below it; the background painted above is not in its layer.

这是动画读取阶段错误之后，最常见的“为什么我的淡出效果这么奇怪”问题。若目的是“淡化整个视觉单元”，请将 graphicsLayer 放在链的顶部或靠近顶部的位置。

模式：clickable 位于 graphicsLayer 内部（命中测试带来的意外）
// RIGHT — graphicsLayer { } wraps clickable; ripple is captured into the layer.
Box(
    Modifier
        .graphicsLayer { alpha = 0.9f }
        .clickable { onTap() }
        .padding(16.dp)
)

graphicsLayer 不会改变命中测试的几何范围——clickable 始终根据它在链中的位置进行命中测试，无论它是否被 graphicsLayer 包裹。如果 graphicsLayer 应用了变换（平移、缩放、旋转），命中测试仍会依据布局后的（变换前）边界；对于变换后的命中测试，需要使用带有显式命中测试的 Modifier.pointerInput { }。有关更广泛的阶段讨论，请交叉参阅 ../../recomposition/deferring-state-reads/SKILL.md。

模式：提升 Modifier 链——通常没有收益
// OK but rarely necessary
@Composable
fun SnackList(snacks: ImmutableList<Snack>) {
    val rowModifier = remember { Modifier.fillMaxWidth().padding(16.dp) }
    LazyColumn {
        items(snacks, key = { it.id }) { snack -> SnackRow(snack, rowModifier) }
    }
}

// Equally fine in practice
@Composable
fun SnackList(snacks: ImmutableList<Snack>) {
    LazyColumn {
        items(snacks, key = { it.id }) { snack ->
            SnackRow(snack, Modifier.fillMaxWidth().padding(16.dp))
        }
    }
}

Compose 会对结构相等的 Modifier 链进行驻留。上面的两个代码片段在每个项目位置都会生成可通过 equals 比较的相同链。通过 remember 提升链，每次重组每个项目最多只省下一次分配——在合成微基准测试中可以测量到，但在真实界面的 FrameTimingMetric 中看不出来。没有可供参考的 FrameTimingMetric 回归数据时，MUST NOT 仅以“提升性能”为由添加 remember 行。更大的收益见 ../migrating-to-modifier-node/SKILL.md——修复 Modifier.composed { } 工厂。

模式：先 padding 再 size——无法测量的顺序
// Both compile; both are valid; they mean different things.
Box(Modifier.size(100.dp).padding(8.dp))   // 100dp box, 8dp inner padding → 84dp content area
Box(Modifier.padding(8.dp).size(100.dp))   // 100dp content area, 8dp outer margin → 116dp total

size 会约束链中该位置的边界；padding 会从传递给其下方所有内容的可用空间中扣除空间。从上往下阅读：顺序描述的是布局，而不是“换个顺序做同一件事”。

强制规则

  • MUST 从上到下阅读 modifier 链，并将每个 modifier 理解为包裹其下方所有内容的包装器。
  • 当点击区域应仅为可见区域时，MUST 将 clickable 放在 padding 之后（即先 padding 再 clickable，clickable 在链中位于 padding 下方）。当设计要求填充区域也可点击时（Material 48dp 触摸目标），将 clickable 放在 padding 之前。
  • MUST 将 clip 放在 background 之前，以裁剪背景绘制。也可以使用 Modifier.background(color, shape)，完全避免顺序问题。
  • 当 graphicsLayer 的变换 / alpha 必须作用于整个视觉单元（包括背景）时，MUST 将其放在链中靠前的位置。
  • 没有可供参考的 FrameTimingMetric 回归数据时，MUST NOT 仅以“提升性能”为由通过 remember { Modifier.… } 提升 Modifier 链——Compose 已经会对相同的链进行驻留，省下的分配很少会在性能分析结果中体现出来。
  • MUST NOT 添加 Modifier.composed { } 工厂来“修复”顺序问题。如果自定义 modifier 必须位于特定位置，可以直接使用 Modifier.Node。参见 ../migrating-to-modifier-node/SKILL.md。
  • PREFERRED： 对于以满足无障碍要求（最小 48dp）为目标的可点击项目，采用明确的 padding → clickable → padding 夹层：外层留白、将可点击区域设为包含视觉填充的大小，再通过内层填充包围内容。
  • PREFERRED： 两者都需要时，优先使用 Modifier.background(color = ..., shape = ...)，而不是 clip(shape).background(color) 组合。

验证

  • 绘制区域（背景、边框）符合设计意图——没有意外的红色溢出圆角，也没有在非预期的内边距中出现红色。
  • 点击 / 波纹区域符合设计意图——内边距中的点击是否触发都经过明确设计，而非偶然发生。
  • clip 会遮罩其下方的每一层；在每种主题下，裁剪后的圆角都符合预期。
  • graphicsLayer { alpha = ... }（或 scaleX、rotationZ 等）只影响预期的子树；按预期，背景和内容会一起淡出。
  • 对于任何提升的 Modifier 链，release + R8 + 真实设备上的 FrameTimingMetric 宏基准测试都显示，相比未提升的版本有可测量的改进。否则就移除 remember。
  • 没有为绕过链顺序问题而添加 Modifier.composed { }（重新 grep 模块）。

参考资料

评论

支持 Markdown