jetpack-compose

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Jetpack Compose Expert Skill

Jetpack Compose专家技能

Non-opinionated, practical guidance for writing correct, performant Jetpack Compose code. Focuses on real pitfalls developers encounter daily, backed by analysis of the actual

androidx/androidx

source code (branch:

androidx-main

提供客观务实的指导，帮助开发者编写正确、高性能的Jetpack Compose代码。聚焦开发者日常遇到的实际陷阱，基于

androidx/androidx

源码（分支：

androidx-main

）分析。

Workflow

工作流程

When helping with Compose code, follow this checklist:

当协助处理Compose代码时，请遵循以下检查清单：

1. Understand the request

1. 理解需求

What Compose layer is involved? (Runtime, UI, Foundation, Material3, Navigation)
Is this a state problem, layout problem, performance problem, or architecture question?

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

2. Consult the right reference

2. 查阅正确的参考资料

Read the relevant reference file(s) from

references/

before answering:

Topic	Reference File
`@State` , `remember` , `mutableStateOf` , state hoisting, `derivedStateOf` , `snapshotFlow`	`references/state-management.md`
Structuring composables, slots, extraction, preview	`references/view-composition.md`
Modifier ordering, custom modifiers, `Modifier.Node`	`references/modifiers.md`
`LaunchedEffect` , `DisposableEffect` , `SideEffect` , `rememberCoroutineScope`	`references/side-effects.md`
`CompositionLocal` , `LocalContext` , `LocalDensity` , custom locals	`references/composition-locals.md`
`LazyColumn` , `LazyRow` , `LazyGrid` , `Pager` , keys, content types	`references/lists-scrolling.md`
`NavHost` , type-safe routes, deep links, shared element transitions	`references/navigation.md`
`animate*AsState` , `AnimatedVisibility` , `Crossfade` , transitions	`references/animation.md`
`MaterialTheme` , `ColorScheme` , dynamic color, `Typography` , shapes	`references/theming-material3.md`
Recomposition skipping, stability, baseline profiles, benchmarking	`references/performance.md`
Semantics, content descriptions, traversal order, testing	`references/accessibility.md`
Removed/replaced APIs, migration paths from older Compose versions	`references/deprecated-patterns.md`
Styles API (experimental): `Style {}` , `MutableStyleState` , `Modifier.styleable()`	`references/styles-experimental.md`

在回答前，请阅读

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` 、自定义本地变量	`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. Apply and verify

3. 应用并验证

Write code that follows the patterns in the reference
Flag any anti-patterns you see in the user's existing code
Suggest the minimal correct solution — don't over-engineer

编写符合参考资料中模式的代码
标记用户现有代码中的任何反模式
建议最简的正确解决方案——不要过度设计

4. Cite the source

4. 引用源码

When referencing Compose internals, point to the exact source file:

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

当提及Compose内部实现时，请指向具体的源码文件：

// 参考：compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/Composer.kt

Key Principles

核心原则

Compose thinks in three phases: Composition → Layout → Drawing. State reads in each phase only trigger work for that phase and later ones.
Recomposition is frequent and cheap — but only if you help the compiler skip unchanged scopes. Use stable types, avoid allocations in composable bodies.

Modifier order matters.

Modifier.padding(16.dp).background(Color.Red)

is visually different from

Modifier.background(Color.Red).padding(16.dp)

State should live as low as possible and be hoisted only as high as needed. Don't put everything in a ViewModel just because you can.
Side effects exist to bridge Compose's declarative world with imperative APIs. Use the right one for the job — misusing them causes bugs that are hard to trace.

Compose分为三个阶段：组合 → 布局 → 绘制。每个阶段的状态读取只会触发该阶段及后续阶段的工作。
重组频繁且成本低——但前提是你要帮助编译器跳过未更改的作用域。使用稳定类型，避免在可组合项体内进行对象分配。

Modifier顺序至关重要。

Modifier.padding(16.dp).background(Color.Red)

与

Modifier.background(Color.Red).padding(16.dp)

在视觉效果上是不同的。

状态应尽可能下沉，仅在必要时才提升。不要为了方便就把所有状态都放到ViewModel中。
副作用用于衔接Compose的声明式世界与命令式API。为具体任务选择合适的副作用——误用会导致难以追踪的Bug。

Source Code Receipts

源码参考

Beyond the guidance docs, this skill bundles the actual source code from

androidx/androidx

(branch:

androidx-main

). When you need to verify how something works internally, or the user asks "show me the actual implementation", read the raw source from

references/source-code/

Module	Source Reference	Key Files Inside
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

除了指导文档外，本技能还包含来自

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

Two-layer approach

双层方法

Start with guidance — read the topic-specific reference (e.g.,
```
references/state-management.md
```
)
Go deeper with source — if the user wants receipts or you need to verify, read from
```
references/source-code/
```

从指导开始——阅读主题相关的参考资料（例如
```
references/state-management.md
```
）
深入源码——如果用户需要参考依据或你需要验证，请从
```
references/source-code/
```
中读取

Source tree map

源码目录结构

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/

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/