Wear OS Compose Material3…

适用于创建、更新或从 Material 2.5/Horologist 迁移 Wear OS Compose 项目，并正确使用 Material3、Foundation、Navigation3 组件与预览。

适用场景

解决思路

1. 读取当前 Wear OS Compose 版本：直接读取 `gradle/libs.versions.toml` 或 `build.gradle.kts`；不要运行 `./gradlew dependencies` 或其他 shell 命令来解析版本。
2. 确定 Wear OS Compose Material3 最新稳定版 `{VERSION}`：若有内部工具可用，使用该工具；否则抓取官方 Maven metadata XML `https://dl.google.com/dl/android/maven2/androidx/wear/compose/compose-material3/maven-metadata.xml`，取最高版本号并忽略 `-alpha`、`-beta`、`-rc`。
3. 严格遵循稳定版：如果某版本被列为 stable，除非用户覆盖，否则必须使用它；不要因编辑器初始的 `Unresolved reference` 错误或过时的网络搜索结果而降级。
4. Kotlin 版本：使用 Wear Compose Material3 时，Kotlin 必须为 `2.0.0` 或更高。
5. Compose 编译器：若 Kotlin 为 `2.0.0+`，项目必须使用 `org.jetbrains.kotlin.plugin.compose` Gradle 插件；若 Kotlin `< 2.0.0`，项目必须使用 `composeOptions` 中的 `kotlinCompilerExtensionVersion`，并与 Compose to Kotlin Compatibility Map 匹配。
6. Min SDK：确保 `minSdk` 至少为 `25`。
7. 强制同步与验证：在 `libs.versions.toml` 或 `build.gradle.kts` 中更新版本后，必须先执行 Gradle sync，再重构任何代码；这确保环境正确解析库。
8. 禁止猜测的错误协议：如果在成功 sync 后遇到 `Unresolved Reference` 或 API 不匹配，不要尝试通过降级库版本来修复。
9. 迁移能力：除非开发者另有说明，使用来自 `{VERSION}` 的最新稳定版 Wear Compose Material3。
10. 迁移能力：阅读迁移指南 `references/android/training/wearables/compose/migrate-to-material3.md`。
11. 迁移能力：使用迁移指南中的官方组件映射。
12. 迁移能力：在重构任何组件（例如 `Chip` -> `Button`）之前，检查参数名、slot 类型和 Expressive 设计 token。
13. 迁移能力：不要使用 Horologist Composables、Compose Layout 或 Compose Material 库。
14. 迁移能力：始终对照 Capability 4 的组件指导检查。
15. 迁移能力：迁移后预期截图测试会失败；即使迁移到非常相似的组件，padding 和定位的默认值也会改变。不要人为匹配迁移前的截图，而应优先采用 Material3 默认值。
16. 添加 Wear OS Compose Material3 功能或更新应用：除非开发者另有说明，使用来自 `{VERSION}` 的最新稳定版 Wear Compose Material3。
17. 添加功能/更新：不要使用 Horologist Composables、Compose Layout 或 Compose Material 库。
18. 添加功能/更新：始终对照 Capability 4 的组件指导检查。
19. 添加功能/更新：迁移后预期截图测试会失败；即使迁移到非常相似的组件，padding 和定位的默认值也会改变。不要人为匹配迁移前的截图，而应优先采用 Material3 默认值。
20. 组件样例：使用 Capability 3 表格查找 Wear Compose 组件的权威样例；处理任何 Wear Compose 组件时，必须使用表中链接的样例，以确保知道如何正确使用它。该表格覆盖 `androidx.wear.compose.material3.*`、`androidx.wear.compose.foundation.*`、`androidx.wear.compose.navigation3.*` 的全部组件与符号。
21. `AppScaffold` 和 `ScreenScaffold`：使用 `AppScaffold` 作为外层容器，`ScreenScaffold` 作为子级。
22. `AppScaffold` 和 `ScreenScaffold`：只使用一个 `AppScaffold`，可使用任意数量 `ScreenScaffold`。
23. `ScalingLazyColumn`：改用 `TransformingLazyColumn`。
24. `TransformingLazyColumn`：需要这些 import：`androidx.wear.compose.foundation.lazy.TransformingLazyColumn`、`androidx.wear.compose.foundation.lazy.TransformingLazyColumnDefaults`、`androidx.wear.compose.foundation.lazy.rememberTransformingLazyColumnState`、`androidx.wear.compose.material3.lazy.rememberTransformationSpec`、`androidx.wear.compose.material3.lazy.transformedHeight`。
25. `TransformingLazyColumn`：参考 canonical example：使用 `rememberTransformingLazyColumnState()`、`rememberTransformationSpec()`、`ScreenScaffold(scrollState = columnState)`、`TransformingLazyColumn(state = columnState, contentPadding = contentPadding)`；item 中用 `Modifier.fillMaxWidth().transformedHeight(this, transformationSpec).minimumVerticalContentPadding(...)` 和 `transformation = SurfaceTransformation(transformationSpec)`。
26. `TransformingLazyColumn`：使用 `TransformingLazyColumn` 而不是 `ScalingLazyColumn`。
27. `TransformingLazyColumn`：必须把 `ScreenScaffold` 的 `contentPadding` 参数传给 `TransformingLazyColumn`。
28. `TransformingLazyColumn`：使用 `minimumVerticalContentPadding` modifier 实现所需的上/下 padding；该值应来自 defaults，如 `ButtonDefaults`、`CardDefaults`、`ListHeaderDefaults`；注意这是 `TransformingLazyColumnItemScope` 内的 scoped modifier。
29. `TransformingLazyColumn`：确保列表会发生 morph 和 scale。
30. `TransformingLazyColumn`：使用 `transformedHeight` modifier。
31. `TransformingLazyColumn`：使用 `transform = SurfaceTransform(...)`。
32. `TransformingLazyColumn`：如果为列表配置 snapping，必须同时使用 `flingBehavior` 和 `rotaryScrollableBehavior`，例如 `flingBehavior = TransformingLazyColumnDefaults.snapFlingBehavior(columnState)`、`rotaryScrollableBehavior = RotaryScrollableDefaults.snapBehavior(columnState)`。
33. `ScreenScaffold`：用 `!LocalScrollCaptureInProgress.current` 保护 `scrollIndicator`。
34. `EdgeButton`：不要在 `TransformingLazyColumn` 中作为最后一项；改用 `ScreenScaffold` 的 slot。
35. `EdgeButton`：在 `TransformingLazyColumn` 中使用时，添加所需 overscroll 行为：在 `EdgeButton` 的 `Modifier.scrollable(columnState, orientation = Orientation.Vertical, reverseDirection = true, overscrollEffect = rememberOverscrollEffect())`。
36. `Column`：仅当屏幕即使使用最大系统字体也永远不会滚动时，才作为 `ScreenScaffold` 的直接子级使用。
37. `Column`：所有其他情况改用 `TransformingLazyColumn`。
38. 样式：不要硬编码文字大小，使用 `MaterialTheme` 的 `typography`。
39. 样式：不要硬编码颜色，使用 `MaterialTheme` 的 `colorScheme`。
40. 使用组件 defaults：组件如 `Button` 有对应的 `ButtonDefaults` 对象。
41. 使用组件 defaults：处理 padding 和样式值时，检查并使用任何组件的 `*Defaults` 对象，优先于硬编码值。
42. 使用 Wear 专用预览注解：`@WearPreviewDevices`。
43. 使用 Wear 专用预览注解：`@WearPreviewFontScales`。
44. 使用 Wear 专用预览注解：确保包含 `androidx.wear.compose:compose-ui-tooling` 依赖。
45. Ambient mode：使用 `LocalAmbientModeManager` 而不是 `AmbientLifecycleObserver`。
46. Navigation：全新添加导航时，使用 Navigation3。
47. Navigation：Wear OS 的 Navigation3 使用来自 Wear Compose `compose-navigation3` 库的 `SwipeDismissableSceneStrategy()`。
48. Comments：任何 Kotlin 文件被修改后，确保现有注释保持最新并准确反映实现变更。
49. `HorizontalPager` 或 `VerticalPager`：按此顺序使用 Composable 层级：`AppScaffold`、`HorizontalPagerScaffold`、`HorizontalPager`、`AnimatedPage`、`ScreenScaffold`；`VerticalPager` 类似。

适用边界 · 注意事项

• 不适用于非 Wear OS 或非 Jetpack Compose 项目。
• 不适用于无法满足 `minSdk` 25、Kotlin 2.0.0+ 或对应 Compose 编译器兼容配置等前置条件的项目。
• 不适用于仅需传统 Android Material3 或非 Wear 设备 UI 的场景。