compose

Compose 专家技能

面向 Android、Desktop、iOS 和 Web，提供编写正确且高性能 Compose 代码的务实指南，不偏袒任何观点。涵盖 Jetpack Compose 和 Compose Multiplatform。 基于对 androidx/androidx 和 JetBrains/compose-multiplatform-core 实际源代码的分析。

工作流

协助编写 Compose 代码时，请按以下清单操作：

1. 理解需求

• 涉及 Compose 的哪个层？（Runtime、UI、Foundation、Material3、Navigation）
• 这是状态问题、布局问题、性能问题，还是架构问题？
• 这是仅适用于 Android，还是适用于 Compose Multiplatform（CMP）？

2. 分析设计（如果提供了视觉参考）

• 如果用户分享了 Figma 画板、截图或设计规范，请参阅 references/design-to-compose.md
• 将设计分解为可组合项树
• 照录，不要改编——复制的内容、大小写、标点和数字格式都必须完全一致；将每个值精确对应到匹配的设计令牌，如果主题中缺少某个令牌，就添加该令牌，而不是替换为最接近的令牌（references/design-to-compose.md）
• 将设计令牌映射到 MaterialTheme，将间距映射到 CompositionLocals
• 确定动画需求——references/animation.md（contentKey、phase rule、M3 motion tokens）、references/animation-recipes.md（shimmer/loading-crossfade + choreography）或 references/animation-advanced.md（shared-element、predictive back、drawBehind-for-color）

3. 查阅正确的参考资料

回答前，请先阅读 references/ 中的相关参考文件：

主题	参考文件
状态提升边界（UI 值驱动业务逻辑）、derivedStateOf 捕获陷阱、跨阶段回写、持久状态优先于事件、@ReadOnlyComposable	references/state-management.md
插槽 / 内容 API 编写——接收器作用域（RowScope）、可选（可空）插槽、XxxDefaults、插槽与布尔标志的取舍	references/view-composition.md
屏幕 / 内容拆分（私有内容可组合项）、框架状态留在 UI 中（不提升到 ViewModel）	references/screen-structure.md
Modifier 作为 API 契约的规则（可复用根节点不硬编码布局、调用方 Modifier 优先）及链顺序	references/modifiers.md
副作用（LaunchedEffect/DisposableEffect/SideEffect）、生命周期副作用（LifecycleResumeEffect）、副作用反模式	references/side-effects.md
compositionLocalOf 与 staticCompositionLocalOf（重组范围）、自定义 Local、Local 中不使用可变 State	references/composition-locals.md
LazyList 性能陷阱——indexOf() 的 O(n²) 复杂度、键中不创建新对象、animateItem、ReportDrawnWhen、无限滚动触发条件	references/lists-scrolling.md
Navigation 3（NavDisplay、作为状态的返回栈、Compose 形状约束）；类型安全的 @Serializable 路由	references/navigation.md
AnimatedContent 的 contentKey 与形状匹配、将读取延迟到最新阶段（lambda Modifier）、M3 动效 / 缓动令牌	references/animation.md
动画方案（闪烁效果 / 加载交叉淡入淡出）、顺序 / 并行 / 错落编排	references/animation-recipes.md
共享元素过渡（sharedBounds/sharedElement/skipToLookaheadSize）、使用 drawBehind 实现动画颜色、预测性返回	references/animation-advanced.md
将主题扩展到 M3 的三个槽位之外——通过 CompositionLocal 定义自定义设计令牌	references/theming-material3.md
触控目标、间距、规范布局、折叠屏、M3 合规性审查	android-skills:android-ux
重组跳过、稳定性、基线配置文件、基准测试	references/performance.md
遍历顺序（traversalIndex / isTraversalGroup）、实时区域模式（Polite 与 Assertive）	references/accessibility.md
FocusRequester、focusable()、focusProperties、按键事件、方向键、电视、键盘、焦点恢复	references/focus-navigation.md
已移除 / 替换的 API、从旧版 Compose 迁移的路径	references/deprecated-patterns.md
Styles API（实验性）：Style {}、MutableStyleState、Modifier.styleable()	references/styles-experimental.md
将设计稿转写为代码——精确复制 / 大小写 / 数字格式、精确令牌与近似令牌的取舍、缺失令牌应新增而非替换；以导出结果而非渲染结果为准；Figma dropShadow/innerShadow（1.9+、链中的放置位置）、间距 / 海拔设计令牌 CompositionLocal	references/design-to-compose.md
生产环境崩溃模式、防御性编码、状态 / 性能规则	references/production-crash-playbook.md
CMP 注意事项（commonMain 中的 collectAsState、commonMain @Preview 包、Lottie→Kottie、编译器稳定性非 JVM）及仅 Android 项目迁移到 CMP	references/multiplatform.md
桌面端（Window、Tray、MenuBar）、iOS（UIKitView）、Web（ComposeViewport）	references/platform-specifics.md

4. 应用并验证

• 编写符合参考资料中模式的代码
• 指出用户现有代码中的任何反模式
• 提出最简洁且正确的解决方案——不要过度设计

5. 注明来源

引用 Compose 内部实现时，请指出确切的源文件：

// See: compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/Composer.kt

核心原则

1. Compose 分三个阶段运行：组合 → 布局 → 绘制。每个 阶段中的状态读取只会触发该阶段及后续阶段的工作。

2. 重组很频繁，开销也很低——但前提是你帮助编译器跳过未更改的 作用域。使用稳定类型，避免在可组合函数体中分配对象。

3. Modifier 的顺序很重要。Modifier.padding(16.dp).background(Color.Red) 在视觉上 与 Modifier.background(Color.Red).padding(16.dp) 不同。

4. 状态应尽可能放在低层，仅在需要时才向上提升。别因为可以这么做， 就把所有东西都放进 ViewModel。

5. 副作用用于衔接 Compose 的声明式世界与命令式 API。根据用途选择 合适的副作用——误用会导致难以追踪的错误。

6. Compose Multiplatform 共享运行时，但不共享平台。commonMain 中的 UI 代码 可移植。平台专属 API（LocalContext、BackHandler、 Window）需要使用 expect/actual 或条件源集。

源代码验证

始终对照实时源代码进行验证——绝不要只依赖训练数据。

第 1 层（首选）：android-sources MCP 服务

若可用，请使用 MCP 工具快速、精确地查找：

lookup_class(className: "LazyListState")
lookup_method(className: "Composer", methodName: "startRestartGroup")
search_in_source(query: "fun rememberLazyListState")
list_class_members(className: "Modifier")
get_class_hierarchy(className: "LazyListState")
find_references(className: "SnapshotState", methodName: "value")

第 2 层（备用）：原始 GitHub URL

如果 MCP 服务不可用，请直接获取源代码：

• AndroidX：https://raw.githubusercontent.com/androidx/androidx/androidx-main/{path}
• 目录列表：gh api repos/androidx/androidx/contents/{path}
• CMP：https://raw.githubusercontent.com/JetBrains/compose-multiplatform-core/jb-main/{path}
• AOSP 平台：https://android.googlesource.com/platform/frameworks/base/+/refs/heads/main/{path}?format=TEXT（base64）

两层方法

1. 先查看指导——阅读特定主题的参考资料（例如 references/state-management.md）
2. 对照实时源代码验证——使用 MCP 工具或原始 GitHub URL 确认行为

源代码树映射

androidx/androidx (branch: androidx-main)
├── compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/
├── compose/ui/ui/src/androidMain/kotlin/androidx/compose/ui/platform/
├── compose/ui/ui/src/commonMain/kotlin/androidx/compose/ui/
├── compose/foundation/foundation/src/commonMain/kotlin/androidx/compose/foundation/
├── compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/
└── compose/navigation/navigation-compose/src/commonMain/kotlin/androidx/navigation/compose/

compose-multiplatform-core (branch: jb-main)
├── compose/ui/ui/src/desktopMain/kotlin/androidx/compose/ui/window/
├── compose/ui/ui/src/iosMain/kotlin/androidx/compose/ui/window/
├── compose/ui/ui/src/webMain/kotlin/androidx/compose/ui/window/
├── compose/ui/ui/src/skikoMain/kotlin/androidx/compose/ui/
└── compose/foundation/foundation/src/skikoMain/kotlin/androidx/compose/foundation/

compose-multiplatform (resources library)
└── components/resources/library/src/commonMain/

权威文档

对于指导、最佳实践或迁移指南等仅凭源代码无法解答的问题，优先查阅 Google 的 Android 知识库，而不是进行网络搜索：

android docs search "LazyColumn performance"              # ranked kb:// URLs + summaries
android docs fetch kb://android/develop/ui/compose/lists  # full content of a result

精选文档超过 4,800 篇，涵盖 Android、Wear、TV、KMP 和 Glance。当 references/ 中的内部文件无法解答你的问题时，请使用此资源；需要了解实现细节而非指导时，请使用上文的源代码查找方式。