wear-compose-m3

前提条件和兼容性

1. 当前使用的 Wear OS Compose 版本： 如需查找已安装的库版本，请直接读取 gradle/libs.versions.toml 或 build.gradle.kts。不要运行 ./gradlew dependencies 或其他 shell 命令来解析版本。
2. Wear OS Compose Material3 版本： 如果有内部工具可用于确定 androidx.wear.compose:compose-material3 的最新稳定版本 {VERSION}，请使用该工具。
   • 否则，获取官方 Maven 元数据 XML，以确定 {VERSION}（忽略 -alpha、-beta 或 -rc，取最高版本号）。
3. 严格遵守： 如果某个版本标记为稳定版，就必须使用该版本，除非用户另有要求。不要因为编辑器中最初出现“Unresolved reference”错误或网页搜索结果过时而降级。
4. Kotlin 和 Compose 编译器： 使用 Kotlin 2.0.0+，并搭配 org.jetbrains.kotlin.plugin.compose Gradle 插件。
5. 最低 SDK： 确保 minSdk 至少为 25。
6. 编译 SDK 和 AGP： 确保 compileSdk 和 AGP 满足库的 AAR 元数据最低要求（1.6.x 需要 compileSdk >= 35 且 AGP >= 8.6.0；1.7.x 需要 compileSdk >= 37 且 AGP >= 9.1.0）。

注意事项

1. 必须同步并验证： 更新 libs.versions.toml 或 build.gradle.kts 中的版本后，在重构前执行 Gradle 同步（或运行 ./gradlew assembleDebug），并在重构后运行 ./gradlew assembleDebug 验证构建。
2. 禁止猜测（错误处理规则）： 成功同步后，如果遇到“Unresolved Reference”或 API 不匹配，不要尝试通过降级库版本来“修复”。

功能和工具

功能 1：迁移、更新和添加功能

从旧版 Wear OS Compose 或 Horologist 迁移、更新现有的 Wear Compose Material3 项目或添加功能时，请遵循以下指南。

1. 除非开发者另有说明，否则使用 {VERSION} 中的最新稳定版 Wear Compose Material3（优先于迁移指南中的任何具体版本字符串）。
2. 从 Material 2.5 或 Horologist 迁移时，请阅读迁移指南，并使用其中的官方组件映射。
3. 重构任何组件（例如，Chip -> Button）之前，请检查参数名称、插槽类型和“Expressive”设计令牌。
4. 不要使用 Horologist Composables、Compose Layout 或 Compose Material 库；请将 Horologist 组件替换为对应的 Wear Compose M3 组件（AppScaffold -> M3 AppScaffold、ScreenScaffold -> M3 ScreenScaffold、ScalingLazyColumn -> TransformingLazyColumn、ResponsiveListHeader -> ListHeader、PagerScreen -> HorizontalPagerScaffold、Chip -> Button、Confirmation -> ConfirmationDialog）。
5. 务必对照功能 3 中的组件指南进行检查。
6. 迁移或更新组件时，截图测试可能会失败：内边距和位置的预期默认值已经发生变化。不要试图人为匹配之前的截图，应优先采用 Material3 默认值。

功能 2：组件示例

使用此参考表查找 Wear Compose 组件的规范示例。 使用 Wear Compose 组件时，必须使用表格中的链接示例，以确保了解该组件的正确用法。

重要： 标记为 [alpha]、[beta] 或 [rc] 的符号仅适用于相应的预发布版本，不包含在稳定版 {VERSION} 中。除非项目明确针对该预发布版本，否则不要使用这些符号。

androidx.wear.compose.material3.* 中的 Material 3 组件

Component / Symbol	Reference Samples
AlertDialog, AlertDialogDefaults	AlertDialogSample
AnimatedPage, HorizontalPagerScaffold, VerticalPagerScaffold	OneHandedGestureSamples, PageIndicatorSample, PagerScaffoldSample
AnimatedText, rememberAnimatedTextFontRegistry	AnimatedTextSample
AppCard	CardSample
AppScaffold	ListHeaderSample, PagerScaffoldSample, ScaffoldSample, SurfaceTransformationSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
ArcProgressIndicator, ArcProgressIndicatorDefaults, CircularProgressIndicator, CircularProgressIndicatorDefaults, ProgressIndicatorDefaults, SegmentedCircularProgressIndicator, drawCircularProgressIndicator	ProgressIndicatorSample
Button	AlertDialogSample, AnimatedTextSample, ButtonGroupSample, ButtonSample, DatePickerSample, DynamicColorSchemeSample, FadingExpandingLabelSample, ListHeaderSample, OneHandedGestureSamples, PageIndicatorSample, PagerScaffoldSample, PickerSample, ScaffoldSample, ScrollIndicatorSample, StepperSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, SwipeToRevealSample, TimePickerSample, TransformationSpecSample, TransformingLazyColumnSample, TransformingLazyColumnSample
ButtonDefaults	ButtonSample, CurvedTextSamples, DynamicColorSchemeSample, EdgeButtonSample, ListHeaderSample, OneHandedGestureSamples, PlaceholderSample, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, TextButtonSample, TransformationSpecSample, TransformingLazyColumnSample, TransformingLazyColumnSample
ButtonGroup	ButtonGroupSample, TransformationSpecSample
Card	CardSample, SwipeDismissableSceneStrategySample, SwipeToRevealSample, TransformingLazyColumnSample
CardDefaults	CardSample, SurfaceTransformationSample, SwipeToRevealSample, TransformingLazyColumnSample, TransformingLazyColumnSample
CheckboxButton	CheckboxButtonSample, SwipeToDismissBoxSample
ChildButton, OutlinedButton	ButtonSample
ColorScheme, dynamicColorScheme	DynamicColorSchemeSample
CompactButton, CompactButtonDefaults	ButtonSample, TransformingLazyColumnSample
ConfirmationDialog, ConfirmationDialogDefaults, FailureConfirmationDialog, SuccessConfirmationDialog, confirmationDialogCurvedText	ConfirmationDialogSample
CurvedTextDefaults	CurvedTextSamples
DatePicker, DatePickerType	DatePickerSample
EdgeButton	EdgeButtonSample, OneHandedGestureSamples, ScaffoldSample, SwipeDismissableSceneStrategySample, TransformingLazyColumnSample
EdgeButtonSize	EdgeButtonSample
FadingExpandingLabel	FadingExpandingLabelSample
FilledIconButton, FilledTonalIconButton, IconButtonColors, IconButtonShapes, OutlinedIconButton	IconButtonSample
FilledTonalButton	AlertDialogSample, ButtonSample, ConfirmationDialogSample, OpenOnPhoneDialogSample, PlaceholderSample, ScrollAwaySample, SwipeToDismissBoxSample
HorizontalPageIndicator, VerticalPageIndicator	PageIndicatorSample
Icon	AlertDialogSample, ButtonSample, CardSample, CheckboxButtonSample, ConfirmationDialogSample, CurvedTextSamples, DatePickerSample, EdgeButtonSample, IconButtonSample, ListHeaderSample, PlaceholderSample, ProgressIndicatorSample, RadioButtonSample, SwipeToRevealSample, SwitchButtonSample, TimePickerSample
IconButton	IconButtonSample, LevelIndicatorSample, ProgressIndicatorSample
IconButtonDefaults	IconButtonSample, ProgressIndicatorSample
IconToggleButton, IconToggleButtonDefaults	IconToggleButtonSample
LevelIndicator	LevelIndicatorSample
LinearProgressIndicator	LinearProgressIndicatorSample
ListHeader	ListHeaderSample, ScrollAwaySample, SwipeDismissableSceneStrategySample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
ListHeaderDefaults	ListHeaderSample, ScrollAwaySample, TransformingLazyColumnSample
ListSubHeader	ListHeaderSample
LocalOneHandedGestureEnabled, OneHandedGestureDefaults, OneHandedGestureHorizontalPageIndicator, OneHandedGesturePageIndicatorState, OneHandedGesturePriority, OneHandedGestureScrollIndicator, OneHandedGestureScrollIndicatorState, OneHandedGestureVerticalPageIndicator	OneHandedGestureSamples
MaterialTheme	AlertDialogSample, ButtonSample, CardSample, CurvedTextSamples, DynamicColorSchemeSample, LinearProgressIndicatorSample, PagerScaffoldSample, ProgressIndicatorSample, SwipeToDismissBoxSample, TimeTextSample, TransformingLazyColumnNotificationsSample
OneHandedGestureAction, OneHandedGestureClickIndicator, OneHandedGestureClickIndicatorState, oneHandedGesture, rememberOneHandedGestureConfiguration	ButtonSample, CardSample, OneHandedGestureSamples
OpenOnPhoneDialog, OpenOnPhoneDialogDefaults, openOnPhoneDialogCurvedText	OpenOnPhoneDialogSample
OutlinedCard	CardSample, TransformingLazyColumnSample
PagerScaffoldDefaults	PageIndicatorSample, PagerScaffoldSample
Picker	PickerSample
PickerGroup	PickerGroupSample
RadioButton, SplitRadioButton	RadioButtonSample
ResponsiveTransformationSpec, TransformationVariableSpec	SurfaceTransformationSample, TransformationSpecSample
RevealValue, SwipeToReveal, SwipeToRevealDefaults, rememberRevealState	SwipeToRevealSample
ScreenScaffold	ListHeaderSample, OneHandedGestureSamples, PagerScaffoldSample, ScaffoldSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
ScreenScaffoldDefaults, ScrollIndicator	ScrollIndicatorSample
ScreenStage, scrollAway	ScrollAwaySample
Slider, SliderDefaults	SliderSample
SplitCheckboxButton	CheckboxButtonSample
SplitSwitchButton	SwitchButtonSample
Stepper, StepperLevelIndicator, rangeSemantics	StepperSample
StepperDefaults	LevelIndicatorSample, StepperSample
SurfaceTransformation	AlertDialogSample, DynamicColorSchemeSample, ListHeaderSample, ScaffoldSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
SwipeToDismissBox	SwipeToDismissBoxSample
SwitchButton	AlertDialogSample, OneHandedGestureSamples, SwitchButtonSample
Text	AlertDialogSample, AnimatedTextSample, ButtonGroupSample, ButtonSample, CardSample, CheckboxButtonSample, ConfirmationDialogSample, DatePickerSample, DynamicColorSchemeSample, EdgeButtonSample, ListHeaderSample, OneHandedGestureSamples, OpenOnPhoneDialogSample, PageIndicatorSample, PagerScaffoldSample, PickerGroupSample, PickerSample, PlaceholderSample, RadioButtonSample, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, StepperSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, SwipeToDismissBoxSample, SwipeToRevealSample, SwitchButtonSample, TextButtonSample, TextToggleButtonSample, TimePickerSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
TextButton	TextButtonSample
TextButtonDefaults	TextButtonSample, TextToggleButtonSample
TextToggleButton, TextToggleButtonDefaults, touchTargetAwareSize	TextToggleButtonSample
TimePicker, TimePickerType	TimePickerSample
TimeText	ScrollAwaySample, ScrollIndicatorSample, TimeTextSample
TimeTextDefaults, timeTextCurvedText	TimeTextSample
TitleCard	CardSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, SwipeToRevealSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
TransformationSpec	TransformationSpecSample
curvedText	CurvedTextSamples, ScrollAwaySample, TimeTextSample
firstVisibleItemLayoutItemInfo, layoutItemInfoOf, rememberTransformingLazyColumnFirstLayoutItemProvider	TransformingLazyColumnSample
placeholder, placeholderShimmer, rememberPlaceholderState	PlaceholderSample
rememberPickerState	PickerGroupSample, PickerSample
rememberTransformationSpec, transformedHeight	AlertDialogSample, DynamicColorSchemeSample, ListHeaderSample, ScaffoldSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, SwipeToRevealSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
timeTextSeparator	ScrollAwaySample, TimeTextSample

androidx.wear.compose.foundation.* 中的基础组件

Component / Symbol	Reference Samples
AmbientMode, LocalAmbientModeManager, rememberAmbientModeManager	AmbientModeSample, OneHandedGestureSamples
AmbientTickEffect	AmbientModeSample
BasicSwipeToDismissBox	SwipeToDismissBoxSample
CurvedAlignment, CurvedTextStyle, angularGradientBackground, angularSize, basicCurvedText, clearAndSetSemantics, curvedColumn, padding, radialGradientBackground, radialSize, semantics, size	CurvedWorldSample
CurvedDirection, CurvedLayout, angularSizeDp, background, curvedBox, curvedComposable, curvedRow	CurvedTextSamples, CurvedWorldSample
CurvedModifier	CurvedTextSamples, CurvedWorldSample, TimeTextSample
HorizontalPager, VerticalPager, rememberPagerState	OneHandedGestureSamples, PageIndicatorSample, PagerSamples, PagerScaffoldSample
PagerDefaults	PagerScaffoldSample
RotaryScrollableDefaults	PagerScaffoldSample, RotarySamples, TransformingLazyColumnSample
RotarySnapLayoutInfoProvider, rotaryScrollable	RotarySamples
ScrollInfoProvider	ScrollAwaySample
SwipeToDismissValue, edgeSwipeToDismiss, rememberSwipeToDismissBoxState	SwipeToDismissBoxSample, SwipeToDismissBoxSample
TransformingLazyColumn	DynamicColorSchemeSample, ListHeaderSample, OneHandedGestureSamples, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, SwipeToRevealSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
TransformingLazyColumnDefaults	TransformingLazyColumnSample
TransformingLazyColumnFirstLayoutItemProvider	TransformingLazyColumnSample, TransformingLazyColumnSample
TransformingLazyColumnItemScrollProgress	TransformationSpecSample
expandableButton, expandableItem, expandableItems, rememberExpandableState	ExpandableSample
hierarchicalFocusGroup	HierarchicalFocusSample
items	SwipeDismissableSceneStrategySample, SwipeToRevealSample, TransformingLazyColumnNotificationsSample
itemsIndexed	TransformingLazyColumnSample
rememberTransformingLazyColumnState	ListHeaderSample, OneHandedGestureSamples, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, SwipeToRevealSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
requestFocusOnHierarchyActive	HierarchicalFocusSample, RotarySamples
weight	CurvedWorldSample, TimeTextSample

androidx.wear.compose.navigation3.* 中的 Navigation 3 组件

组件 / 符号	参考示例
rememberSwipeDismissableSceneStrategy	SwipeDismissableSceneStrategySample

能力 3：组件指南

必需：将此能力作为检查清单，用于核对任何组件的使用方式。除了组件语法之外，它还提供了关于如何在实践中使用各组件的更全面指导。

1. AppScaffold 和 ScreenScaffold

   • [ ] 使用 AppScaffold 作为外层容器，并以 ScreenScaffold 作为其子项。
   • [ ] 只能使用 一个 AppScaffold，而 ScreenScaffold 可以使用任意数量。

2. ScalingLazyColumn - 改用 TransformingLazyColumn。

3. TransformingLazyColumn - 需要以下导入：

   import androidx.wear.compose.foundation.lazy.TransformingLazyColumn
   import androidx.wear.compose.foundation.lazy.TransformingLazyColumnDefaults
   import androidx.wear.compose.foundation.lazy.rememberTransformingLazyColumnState
   // ...
   import androidx.wear.compose.material3.lazy.rememberTransformationSpec
   import androidx.wear.compose.material3.lazy.transformedHeight
   

   
   

   规范示例：

   val columnState = rememberTransformingLazyColumnState()
   val transformationSpec = rememberTransformationSpec()
   ScreenScaffold(
       scrollState = columnState
   ) { contentPadding ->
       TransformingLazyColumn(
           state = columnState,
           contentPadding = contentPadding
       ) {
           item {
               ListHeader(
                   modifier = Modifier
                       .fillMaxWidth()
                       .transformedHeight(this, transformationSpec)
                       .minimumVerticalContentPadding(ListHeaderDefaults.minimumTopListContentPadding),
                   transformation = SurfaceTransformation(transformationSpec)
               ) {
                   Text(text = "Header")
               }
           }
           // ... other items
           item {
               Button(
                   modifier = Modifier
                       .fillMaxWidth()
                       .transformedHeight(this, transformationSpec)
                       .minimumVerticalContentPadding(ButtonDefaults.minimumVerticalListContentPadding),
                   transformation = SurfaceTransformation(transformationSpec),
                   onClick = { /* ... */ },
                   icon = {
                       Icon(
                           imageVector = Icons.Default.Build,
                           contentDescription = "build",
                       )
                   },
               ) {
                   Text(
                       text = "Build",
                       maxLines = 1,
                       overflow = TextOverflow.Ellipsis,
                   )
               }
           }
       }
   }
   

   
   
   • [ ] 使用 TransformingLazyColumn 替代 ScalingLazyColumn。
   • [ ] 必须将 ScreenScaffold 中的 contentPadding 参数传递给 TransformingLazyColumn。
   • [ ] 使用 minimumVerticalContentPadding 修饰符设置所需的顶部和底部内边距。
     • 该修饰符需要使用默认值，例如 ButtonDefaults、CardDefaults、ListHeaderDefaults 中的值。
     • 注意：这是一个作用域修饰符，只能在 TransformingLazyColumnItemScope 中使用。
   • [ ] 确保列表项能够变形并缩放（应用于 TransformingLazyColumn 内部的组件，而非列表本身）：
     • [ ] 使用 Modifier.transformedHeight(this, transformationSpec)。
     • [ ] 使用 transformation = SurfaceTransformation(transformationSpec)。
   • [ ] 如果要配置具有吸附效果的列表，请同时使用 flingBehavior 和 rotaryScrollableBehavior：

   val columnState = rememberTransformingLazyColumnState()
   ScreenScaffold(scrollState = columnState) { contentPadding ->
       TransformingLazyColumn(
           state = columnState,
           flingBehavior = TransformingLazyColumnDefaults.snapFlingBehavior(columnState),
           rotaryScrollableBehavior = RotaryScrollableDefaults.snapBehavior(columnState)
       ) {
           // ...
           // ...
       }
   }
   

   
   

4. ScreenScaffold

   • [ ] 使用 !LocalScrollCaptureInProgress.current（androidx.compose.ui.platform）控制 scrollIndicator 的显示。

5. EdgeButton

   • [ ] 不要将其用作 TransformingLazyColumn 中的最后一项。应改用 ScreenScaffold 中的对应插槽。
   • [ ] 在 TransformingLazyColumn 中使用时，添加所需的过滚行为：

   val columnState = rememberTransformingLazyColumnState()
   ScreenScaffold(
       scrollState = columnState,
       edgeButton = {
           EdgeButton(
               onClick = { /* TODO */ },
               modifier = Modifier.scrollable(
                   columnState,
                   orientation = Orientation.Vertical,
                   reverseDirection = true,
                   // Apply overscroll to the EdgeButton for proper scrolling behavior.
                   overscrollEffect = rememberOverscrollEffect(),
               )
           ) {
               Text("More")
           }
       }
   ) { contentPadding ->
       TransformingLazyColumn(
           contentPadding = contentPadding,
           state = columnState,
       ) {
           // ...
           // ...
       }
   }
   

   
   

6. Column

   • [ ] 仅当屏幕在任何情况下（包括使用最大系统字体时）都永远不会滚动，才将其用作 ScreenScaffold 的直接子项。
   • [ ] 其他情况均应改用 TransformingLazyColumn。

7. 样式

   • [ ] 不要对文本大小进行硬编码，应使用 MaterialTheme 中的 typography。
   • [ ] 不要对颜色进行硬编码，应使用 MaterialTheme 中的 colorScheme。

8. 使用组件默认值：

   • [ ] Button 等组件都有对应的 ButtonDefaults 对象。
   • [ ] 设置内边距和样式值时，应检查并优先使用组件对应的 *Defaults 对象，而不是硬编码值。

9. 使用 Wear 专用预览注解 （androidx.wear.compose.ui.tooling.preview）：

   • [ ] @WearPreviewDevices
   • [ ] @WearPreviewFontScales
   • [ ] 确保已包含 androidx.wear.compose:compose-ui-tooling 依赖项。

10. 环境模式

    • [ ] 使用 LocalAmbientModeManager（由 CompositionLocalProvider 和 rememberAmbientModeManager() 提供），而不是 AmbientLifecycleObserver。

11. 导航

    • [ ] 新增导航时，使用 Navigation3（androidx.wear.compose:compose-navigation3）。
    • [ ] 使用 rememberSwipeDismissableSceneStrategy() / SwipeDismissableSceneStrategy（androidx.wear.compose.navigation3）。

12. 注释

    • [ ] 修改任何 Kotlin 文件时，确保现有注释已更新，并准确反映实现中的任何变更。

13. HorizontalPager 或 VerticalPager

    • [ ] 按以下顺序使用 Composable 层级：AppScaffold、HorizontalPagerScaffold、HorizontalPager、AnimatedPage、ScreenScaffold。对于 VerticalPager，顺序也相同。