jetpack-compose

Jetpack Compose 专家技能

关于编写正确、高性能 Jetpack Compose 代码的客观实用指南。 重点关注开发者日常遇到的实际问题，并以分析 androidx/androidx 的实际源码为依据（分支：androidx-main）。

工作流

协助编写 Compose 代码时，请遵循以下清单：

1. 理解请求

• 涉及哪个 Compose 层？（Runtime、UI、Foundation、Material3、Navigation）
• 这是状态、布局、性能问题，还是架构问题？

2. 查阅相应参考资料

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

主题	参考文件
@State、remember、mutableStateOf、状态提升、derivedStateOf、snapshotFlow	references/state-management.md
组织可组合项、插槽、提取、预览	references/view-composition.md
Modifier 顺序、自定义 Modifier、Modifier.Node	references/modifiers.md
LaunchedEffect、DisposableEffect、SideEffect、rememberCoroutineScope	references/side-effects.md
CompositionLocal、LocalContext、LocalDensity、自定义 local	references/composition-locals.md
LazyColumn、LazyRow、LazyGrid、Pager、键、内容类型	references/lists-scrolling.md
NavHost、类型安全路由、深层链接、共享元素转场	references/navigation.md
animate*AsState、AnimatedVisibility、Crossfade、转场	references/animation.md
MaterialTheme、ColorScheme、动态颜色、Typography、形状	references/theming-material3.md
重组跳过、稳定性、基线配置文件、基准测试	references/performance.md
语义、内容描述、遍历顺序、测试	references/accessibility.md
已移除/替换的 API、从旧版 Compose 迁移的路径	references/deprecated-patterns.md
Styles API（实验性）：Style {}、MutableStyleState、Modifier.styleable()	references/styles-experimental.md

3. 应用并验证

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

4. 引用来源

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

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

核心原则

1. Compose 以三个阶段思考：Composition → Layout → Drawing。每个阶段中的状态读取只会触发该阶段及后续阶段的工作。

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

3. Modifier 的顺序很重要。Modifier.padding(16.dp).background(Color.Red) 的视觉效果不同于 Modifier.background(Color.Red).padding(16.dp)。

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

5. 副作用用于连接 Compose 的声明式世界与命令式 API。选择适合当前任务的副作用——误用会导致难以追踪的错误。

源代码依据

除了指导文档之外，此技能还捆绑了来自 androidx/androidx（分支：androidx-main）的实际源代码。需要验证某项功能的内部工作方式，或用户要求“给我看看实际实现”时，请阅读 references/source-code/ 中的原始源代码：

模块	源代码参考	包含的关键文件
Runtime	references/source-code/runtime-source.md	Composer.kt、Recomposer.kt、State.kt、Effects.kt、CompositionLocal.kt、Remember.kt、SlotTable.kt、Snapshot.kt
UI	references/source-code/ui-source.md	AndroidCompositionLocals.android.kt、Modifier.kt、Layout.kt、LayoutNode.kt、ModifierNodeElement.kt、DrawModifier.kt
Foundation	references/source-code/foundation-source.md	LazyList.kt、LazyGrid.kt、BasicTextField.kt、Clickable.kt、Scrollable.kt、Pager.kt
Material3	references/source-code/material3-source.md	MaterialTheme.kt、ColorScheme.kt、Button.kt、Scaffold.kt、TextField.kt、NavigationBar.kt
Navigation	references/source-code/navigation-source.md	NavHost.kt、ComposeNavigator.kt、NavGraphBuilder.kt、DialogNavigator.kt

两层方法

1. 从指导文档开始——阅读与主题相关的参考资料（例如，references/state-management.md）
2. 深入查看源代码——如果用户需要依据，或你需要进行验证，请阅读 references/source-code/ 中的内容

源代码树索引

compose/
├── runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/
├── ui/ui/src/androidMain/kotlin/androidx/compose/ui/platform/
├── ui/ui/src/commonMain/kotlin/androidx/compose/ui/
├── foundation/foundation/src/commonMain/kotlin/androidx/compose/foundation/
├── material3/material3/src/commonMain/kotlin/androidx/compose/material3/
└── navigation/navigation-compose/src/commonMain/kotlin/androidx/navigation/compose/