wear-compose-m3

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prerequisites and compatibility

前提条件与兼容性

Current Wear OS Compose version in-use: To find the installed library version, read
```
gradle/libs.versions.toml
```
or
```
build.gradle.kts
```
directly. Don't run
```
./gradlew dependencies
```
or other shell commands to resolve versions.
Wear OS Compose Material3 version: If an internal tool is available to establish the latest stable version
```
{VERSION}
```
of
```
androidx.wear.compose:compose-material3
```
, use that tool.
- Otherwise, fetch the official Maven metadata XML to identify
```
{VERSION}
```
  (highest number, ignoring
```
-alpha
```
  ,
```
-beta
```
  , or
```
-rc
```
  ).
Strict compliance: If a version is listed as stable, you MUST use it, unless overridden by the user. Do not downgrade based on initial "Unresolved reference" errors in the editor or outdated web search results.
Kotlin version: For Wear Compose Material3, use Kotlin 2.0.0 or higher.
Compose compiler:
- If Kotlin version is 2.0.0+ , the project must use the
```
org.jetbrains.kotlin.plugin.compose
```
 Gradle plugin.
- If Kotlin version is < 2.0.0 , the project must use
```
kotlinCompilerExtensionVersion
```
 in
```
composeOptions
```
 , matching the Compose to Kotlin Compatibility Map.
Min SDK: Ensure
```
minSdk
```
is at least 25.
Sample extraction mandate: Wear Compose libraries ship with an additional JAR file which contains individual samples for each and every component. You mustn't propose code changes, other than previews or basic changes such as color changes, until the samples in Capability 3 are extracted to the local cache. Library source files are incomplete and NOT a substitute for these samples; bypassing extraction is an environment setup failure.

当前使用的Wear OS Compose版本：要查看已安装的库版本，请直接读取
```
gradle/libs.versions.toml
```
或
```
build.gradle.kts
```
文件。不要运行
```
./gradlew dependencies
```
或其他shell命令来解析版本。
Wear OS Compose Material3版本：如果有内部工具可获取
```
androidx.wear.compose:compose-material3
```
的最新稳定版本
```
{VERSION}
```
，请使用该工具。
- 若没有，则获取官方Maven元数据XML来确定
```
{VERSION}
```
  （选择最高版本号，忽略
```
-alpha
```
  、
```
-beta
```
  或
```
-rc
```
  后缀的版本）。
严格合规要求：如果某个版本标记为稳定版，除非用户另行指定，否则必须使用该版本。不要因编辑器中出现的初始"Unresolved reference"错误或过时的网页搜索结果而降级版本。
Kotlin版本：对于Wear Compose Material3，请使用Kotlin 2.0.0或更高版本。
Compose编译器：
- 若Kotlin版本为2.0.0+，项目必须使用
```
org.jetbrains.kotlin.plugin.compose
```
 Gradle插件。
- 若Kotlin版本**< 2.0.0**，项目必须在
```
composeOptions
```
 中配置
```
kotlinCompilerExtensionVersion
```
 ，并与Compose与Kotlin兼容性映射表匹配。
最低SDK版本：确保
```
minSdk
```
至少为25。
示例提取要求：Wear Compose库附带一个额外的JAR文件，其中包含每个组件的独立示例。在将功能3中的示例提取到本地缓存之前，除了预览或颜色修改等基础更改外，不得提议任何代码变更。库源文件不完整，不能替代这些示例；跳过提取步骤属于环境设置失败。

Gotchas

注意事项

Mandatory sync and validation: After updating versions in
```
libs.versions.toml
```
or
```
build.gradle.kts
```
, you must perform a Gradle sync before refactoring any code. This ensures the environment has resolved the libraries correctly.
Prohibition of guessing (error protocol): If you encounter an 'Unresolved Reference' or API mismatch after a successful sync, do not attempt to 'fix' it by downgrading the library version.

强制同步与验证：在
```
libs.versions.toml
```
或
```
build.gradle.kts
```
中更新版本后，必须先执行Gradle同步，再重构任何代码。这确保环境已正确解析库文件。
禁止猜测（错误处理规则）：如果同步成功后仍遇到'Unresolved Reference'或API不匹配问题，请勿通过降级库版本尝试"修复"。

Capabilities and tools

功能与工具

Capability 1: Migration

功能1：迁移

Use this guidance when migrating from an older version of Wear OS Compose or Horologist.

Unless otherwise indicated by the developer, use the latest stable version of Wear Compose Material3 from
```
{VERSION}
```
.
Read the migration guide.
Use the official component mappings from the migration guide.
Before refactoring any component (for example,
```
Chip
```
->
```
Button
```
), check the parameter names, slot types, and "Expressive" design tokens.
Do not use the Horologist Composables, Compose Layout, or Compose Material libraries.
Always check against the component guidance in Capability 4.
Expect screenshot tests to fail when a migration has been performed: Even when migrating to very similar components, expected defaults for padding and positioning will have changed. Do not seek to artificially match the pre-migration screenshot, but give preference to the Material3 defaults.

当从旧版本Wear OS Compose或Horologist迁移时，请遵循以下指导。

除非开发者另行指定，否则使用
```
{VERSION}
```
中的Wear Compose Material3最新稳定版本。
阅读迁移指南。
使用迁移指南中的官方组件映射关系。
在重构任何组件（例如
```
Chip
```
->
```
Button
```
）之前，检查参数名称、插槽类型和"Expressive"设计标记。
不要使用Horologist Composables、Compose Layout或Compose Material库。
务必对照功能4中的组件指导进行检查。
迁移完成后，截图测试可能会失败：即使迁移到非常相似的组件，内边距和位置的默认值也可能已更改。请勿刻意匹配迁移前的截图，应优先使用Material3的默认值。

Capability 2: Adding Wear OS Compose Material3 features or updating the app

功能2：添加Wear OS Compose Material3功能或更新应用

Use this guidance when the developer asks to update a project which is using an earlier version of Wear OS Compose Material3, or when they ask to add further features.

Unless otherwise indicated by the developer, use the latest stable version of Wear Compose Material3 from
```
{VERSION}
```
.
Do not use the Horologist Composables, Compose Layout, or Compose Material libraries.
Always check against the component guidance in Capability 4.
Expect screenshot tests to fail when a migration has been performed: Even when migrating to very similar components, expected defaults for padding and positioning will have changed. Do not seek to artificially match the pre-migration screenshot, but give preference to the Material3 defaults.

当开发者要求更新使用早期版本Wear OS Compose Material3的项目，或要求添加更多功能时，请遵循以下指导。

除非开发者另行指定，否则使用
```
{VERSION}
```
中的Wear Compose Material3最新稳定版本。
不要使用Horologist Composables、Compose Layout或Compose Material库。
务必对照功能4中的组件指导进行检查。
迁移完成后，截图测试可能会失败：即使迁移到非常相似的组件，内边距和位置的默认值也可能已更改。请勿刻意匹配迁移前的截图，应优先使用Material3的默认值。

Capability 3: Component samples

功能3：组件示例

Use this table of reference to find canonical samples for Wear Compose components. When working with a Wear Compose component, you must use the samples linked from the table to ensure you know how to correctly use it.

使用此参考表查找Wear Compose组件的标准示例。在使用Wear Compose组件时，必须使用表中链接的示例，以确保正确使用组件。

Material 3 components in

androidx.wear.compose.material3.*

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, SwipeToRevealSample, TimePickerSample, TransformationSpecSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`ButtonDefaults`	ButtonSample, CurvedTextSamples, DynamicColorSchemeSample, EdgeButtonSample, ListHeaderSample, PlaceholderSample, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, TextButtonSample, TransformationSpecSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`ButtonGroup`	ButtonGroupSample, TransformationSpecSample
`Card`	CardSample, SwipeToRevealSample, TransformingLazyColumnSample
`CardDefaults`	CardSample, SurfaceTransformationSample, SwipeToRevealSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`CheckboxButton`	CheckboxButtonSample, SwipeToDismissBoxSample
`ChildButton` , `OutlinedButton`	ButtonSample
`ColorScheme` , `dynamicColorScheme`	DynamicColorSchemeSample
`CompactButton` , `CompactButtonDefaults`	ButtonSample, TransformingLazyColumnSample
`ConfirmationDialog` , `ConfirmationDialogDefaults` , `FailureConfirmationDialog` , `FavoriteIcon` , `SuccessConfirmationDialog` , `confirmationDialogCurvedText`	ConfirmationDialogSample
`CurvedTextDefaults`	CurvedTextSamples
`DatePicker` , `DatePickerType`	DatePickerSample
`EdgeButton`	EdgeButtonSample, OneHandedGestureSamples, ScaffoldSample, TransformingLazyColumnSample
`EdgeButtonSize`	EdgeButtonSample
`FadingExpandingLabel`	FadingExpandingLabelSample
`FilledIconButton` , `FilledTonalIconButton` , `IconButtonColors` , `IconButtonShapes` , `OutlinedIconButton`	IconButtonSample
`FilledTonalButton`	AlertDialogSample, ButtonSample, ConfirmationDialogSample, OpenOnPhoneDialogSample, PlaceholderSample, ScrollAwaySample, SwipeToDismissBoxSample
`GestureAction` , `OneHandedGestureClickIndicator` , `OneHandedGestureClickIndicatorState` , `oneHandedGesture` , `rememberOneHandedGestureConfiguration`	ButtonSample, CardSample, OneHandedGestureSamples
`GesturePriority` , `LocalOneHandedGestureEnabled` , `OneHandedGestureDefaults` , `OneHandedGestureHorizontalPageIndicator` , `OneHandedGesturePageIndicatorState` , `OneHandedGestureScrollIndicator` , `OneHandedGestureScrollIndicatorState` , `OneHandedGestureVerticalPageIndicator`	OneHandedGestureSamples
`HeadphoneIcon` , `Stepper` , `StepperLevelIndicator` , `rangeSemantics`	StepperSample
`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` , `WifiOffIcon` , `WifiOnIcon`	IconToggleButtonSample
`LevelIndicator`	LevelIndicatorSample
`LinearProgressIndicator`	LinearProgressIndicatorSample
`ListHeader`	ListHeaderSample, ScrollAwaySample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
`ListHeaderDefaults`	ListHeaderSample, ScrollAwaySample, TransformingLazyColumnSample
`ListSubHeader`	ListHeaderSample
`MaterialTheme`	AlertDialogSample, ButtonSample, CardSample, CurvedTextSamples, DynamicColorSchemeSample, LinearProgressIndicatorSample, PagerScaffoldSample, ProgressIndicatorSample, SwipeToDismissBoxSample, TimeTextSample, TransformingLazyColumnNotificationsSample
`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, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
`ScreenScaffoldDefaults` , `ScrollIndicator`	ScrollIndicatorSample
`ScreenStage` , `scrollAway`	ScrollAwaySample
`Slider` , `SliderDefaults`	SliderSample
`SplitCheckboxButton`	CheckboxButtonSample
`SplitSwitchButton`	SwitchButtonSample
`StepperDefaults` , `VolumeDownIcon` , `VolumeUpIcon`	LevelIndicatorSample, StepperSample
`SurfaceTransformation`	AlertDialogSample, DynamicColorSchemeSample, ListHeaderSample, ScaffoldSample, SurfaceTransformationSample, 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, 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, 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, SwipeToRevealSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`timeTextSeparator`	ScrollAwaySample, TimeTextSample

组件 / 符号	参考示例
`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, SwipeToRevealSample, TimePickerSample, TransformationSpecSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`ButtonDefaults`	ButtonSample, CurvedTextSamples, DynamicColorSchemeSample, EdgeButtonSample, ListHeaderSample, PlaceholderSample, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, TextButtonSample, TransformationSpecSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`ButtonGroup`	ButtonGroupSample, TransformationSpecSample
`Card`	CardSample, SwipeToRevealSample, TransformingLazyColumnSample
`CardDefaults`	CardSample, SurfaceTransformationSample, SwipeToRevealSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`CheckboxButton`	CheckboxButtonSample, SwipeToDismissBoxSample
`ChildButton` , `OutlinedButton`	ButtonSample
`ColorScheme` , `dynamicColorScheme`	DynamicColorSchemeSample
`CompactButton` , `CompactButtonDefaults`	ButtonSample, TransformingLazyColumnSample
`ConfirmationDialog` , `ConfirmationDialogDefaults` , `FailureConfirmationDialog` , `FavoriteIcon` , `SuccessConfirmationDialog` , `confirmationDialogCurvedText`	ConfirmationDialogSample
`CurvedTextDefaults`	CurvedTextSamples
`DatePicker` , `DatePickerType`	DatePickerSample
`EdgeButton`	EdgeButtonSample, OneHandedGestureSamples, ScaffoldSample, TransformingLazyColumnSample
`EdgeButtonSize`	EdgeButtonSample
`FadingExpandingLabel`	FadingExpandingLabelSample
`FilledIconButton` , `FilledTonalIconButton` , `IconButtonColors` , `IconButtonShapes` , `OutlinedIconButton`	IconButtonSample
`FilledTonalButton`	AlertDialogSample, ButtonSample, ConfirmationDialogSample, OpenOnPhoneDialogSample, PlaceholderSample, ScrollAwaySample, SwipeToDismissBoxSample
`GestureAction` , `OneHandedGestureClickIndicator` , `OneHandedGestureClickIndicatorState` , `oneHandedGesture` , `rememberOneHandedGestureConfiguration`	ButtonSample, CardSample, OneHandedGestureSamples
`GesturePriority` , `LocalOneHandedGestureEnabled` , `OneHandedGestureDefaults` , `OneHandedGestureHorizontalPageIndicator` , `OneHandedGesturePageIndicatorState` , `OneHandedGestureScrollIndicator` , `OneHandedGestureScrollIndicatorState` , `OneHandedGestureVerticalPageIndicator`	OneHandedGestureSamples
`HeadphoneIcon` , `Stepper` , `StepperLevelIndicator` , `rangeSemantics`	StepperSample
`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` , `WifiOffIcon` , `WifiOnIcon`	IconToggleButtonSample
`LevelIndicator`	LevelIndicatorSample
`LinearProgressIndicator`	LinearProgressIndicatorSample
`ListHeader`	ListHeaderSample, ScrollAwaySample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
`ListHeaderDefaults`	ListHeaderSample, ScrollAwaySample, TransformingLazyColumnSample
`ListSubHeader`	ListHeaderSample
`MaterialTheme`	AlertDialogSample, ButtonSample, CardSample, CurvedTextSamples, DynamicColorSchemeSample, LinearProgressIndicatorSample, PagerScaffoldSample, ProgressIndicatorSample, SwipeToDismissBoxSample, TimeTextSample, TransformingLazyColumnNotificationsSample
`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, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
`ScreenScaffoldDefaults` , `ScrollIndicator`	ScrollIndicatorSample
`ScreenStage` , `scrollAway`	ScrollAwaySample
`Slider` , `SliderDefaults`	SliderSample
`SplitCheckboxButton`	CheckboxButtonSample
`SplitSwitchButton`	SwitchButtonSample
`StepperDefaults` , `VolumeDownIcon` , `VolumeUpIcon`	LevelIndicatorSample, StepperSample
`SurfaceTransformation`	AlertDialogSample, DynamicColorSchemeSample, ListHeaderSample, ScaffoldSample, SurfaceTransformationSample, 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, 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, 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, SwipeToRevealSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`timeTextSeparator`	ScrollAwaySample, TimeTextSample

Foundation components in

androidx.wear.compose.foundation.*

androidx.wear.compose.foundation.*

中的Foundation组件

Component / Symbol	Reference Samples
`AmbientMode` , `AmbientTickEffect` , `LocalAmbientModeManager` , `rememberAmbientModeManager`	AmbientModeSample
`AutoCenteringParams` , `ScalingLazyColumnDefaults` , `ScalingLazyListAnchorType`	ScalingLazyColumnSample
`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
`ExperimentalWearFoundationApi` , `RevealValue` , `SwipeToReveal` , `rememberRevealState`	SwipeToRevealSample
`HorizontalPager` , `VerticalPager` , `rememberPagerState`	OneHandedGestureSamples, PageIndicatorSample, PagerSamples, PagerScaffoldSample
`ItemEdge` , `TransformingLazyColumnDefaults`	TransformingLazyColumnSample
`PagerDefaults`	PagerScaffoldSample
`RotaryScrollableDefaults`	PagerScaffoldSample, RotarySamples, ScalingLazyColumnSample, TransformingLazyColumnSample
`RotarySnapLayoutInfoProvider` , `rotaryScrollable`	RotarySamples
`ScalingLazyColumn`	ExpandableSample, HierarchicalFocusSample, OneHandedGestureSamples, ScalingLazyColumnSample, SwipeToRevealSample, SwipeToRevealSample
`ScrollInfoProvider`	ScrollAwaySample
`SwipeToDismissValue` , `edgeSwipeToDismiss` , `rememberSwipeToDismissBoxState`	SwipeToDismissBoxSample, SwipeToDismissBoxSample
`TransformingLazyColumn`	DynamicColorSchemeSample, ListHeaderSample, OneHandedGestureSamples, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, SwipeToRevealSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`TransformingLazyColumnFirstLayoutItemProvider`	TransformingLazyColumnSample, TransformingLazyColumnSample
`TransformingLazyColumnItemScrollProgress`	TransformationSpecSample
`expandableButton` , `expandableItems`	ExpandableSample
`expandableItem` , `rememberExpandableState`	ExpandableSample, SwipeToRevealSample
`hierarchicalFocusGroup`	HierarchicalFocusSample
`items`	SwipeToRevealSample, TransformingLazyColumnNotificationsSample
`itemsIndexed`	TransformingLazyColumnSample
`rememberScalingLazyListState`	OneHandedGestureSamples, ScalingLazyColumnSample, SwipeToRevealSample
`rememberTransformingLazyColumnState`	ListHeaderSample, OneHandedGestureSamples, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, SwipeToRevealSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`requestFocusOnHierarchyActive`	HierarchicalFocusSample, RotarySamples
`weight`	CurvedWorldSample, TimeTextSample

组件 / 符号	参考示例
`AmbientMode` , `AmbientTickEffect` , `LocalAmbientModeManager` , `rememberAmbientModeManager`	AmbientModeSample
`AutoCenteringParams` , `ScalingLazyColumnDefaults` , `ScalingLazyListAnchorType`	ScalingLazyColumnSample
`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
`ExperimentalWearFoundationApi` , `RevealValue` , `SwipeToReveal` , `rememberRevealState`	SwipeToRevealSample
`HorizontalPager` , `VerticalPager` , `rememberPagerState`	OneHandedGestureSamples, PageIndicatorSample, PagerSamples, PagerScaffoldSample
`ItemEdge` , `TransformingLazyColumnDefaults`	TransformingLazyColumnSample
`PagerDefaults`	PagerScaffoldSample
`RotaryScrollableDefaults`	PagerScaffoldSample, RotarySamples, ScalingLazyColumnSample, TransformingLazyColumnSample
`RotarySnapLayoutInfoProvider` , `rotaryScrollable`	RotarySamples
`ScalingLazyColumn`	ExpandableSample, HierarchicalFocusSample, OneHandedGestureSamples, ScalingLazyColumnSample, SwipeToRevealSample, SwipeToRevealSample
`ScrollInfoProvider`	ScrollAwaySample
`SwipeToDismissValue` , `edgeSwipeToDismiss` , `rememberSwipeToDismissBoxState`	SwipeToDismissBoxSample, SwipeToDismissBoxSample
`TransformingLazyColumn`	DynamicColorSchemeSample, ListHeaderSample, OneHandedGestureSamples, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, SwipeToRevealSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`TransformingLazyColumnFirstLayoutItemProvider`	TransformingLazyColumnSample, TransformingLazyColumnSample
`TransformingLazyColumnItemScrollProgress`	TransformationSpecSample
`expandableButton` , `expandableItems`	ExpandableSample
`expandableItem` , `rememberExpandableState`	ExpandableSample, SwipeToRevealSample
`hierarchicalFocusGroup`	HierarchicalFocusSample
`items`	SwipeToRevealSample, TransformingLazyColumnNotificationsSample
`itemsIndexed`	TransformingLazyColumnSample
`rememberScalingLazyListState`	OneHandedGestureSamples, ScalingLazyColumnSample, SwipeToRevealSample
`rememberTransformingLazyColumnState`	ListHeaderSample, OneHandedGestureSamples, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, SwipeToRevealSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`requestFocusOnHierarchyActive`	HierarchicalFocusSample, RotarySamples
`weight`	CurvedWorldSample, TimeTextSample

Capability 4: Component guidance

功能4：组件指导

Mandatory: Use this capability as a checklist against any component use. It provides more holistic guidance on how to use each component in practice, beyond the component syntax.

```
AppScaffold
```
and
```
ScreenScaffold
```
- [ ] Use
```
AppScaffold
```
  as the outer container, with
```
ScreenScaffold
```
  children.
- [ ] Use only ONE
```
AppScaffold
```
  and any number of
```
ScreenScaffold
```
  .
```
ScalingLazyColumn
```
- Use
```
TransformingLazyColumn
```
instead.

TransformingLazyColumn

- You will need the following imports:

kotlin

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

Canonical example:

kotlin

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,
                )
            }
        }
    }
}

[ ] Use
```
TransformingLazyColumn
```
instead of
```
ScalingLazyColumn
```
.

[ ] You must pass the

contentPadding

parameter from

ScreenScaffold

to the

TransformingLazyColumn

[ ] Use the
```
minimumVerticalContentPadding
```
modifier to achieve required padding top and bottom.
- This expects a value from defaults, such as
```
ButtonDefaults
```
  ,
```
CardDefaults
```
  , `ListHeaderDefaults.
- Note: This is a scoped modifier available within
```
TransformingLazyColumnItemScope
```
  .
[ ] Ensure the list morphs and scales.
[ ] Use
```
transformedHeight
```
modifier.
[ ] Use
```
transform = SurfaceTransform(...)
```
.
[ ] If configuring a list for snapping, use
```
flingBehavior
```
and
```
rotaryScrollableBehavior
```
together:

kotlin

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

ScreenScaffold

[ ] Guard the

scrollIndicator

with

!LocalScrollCaptureInProgress.current

EdgeButton

[ ] Do NOT use as the final item within a
```
TransformingLazyColumn
```
. Instead, use the slot in
```
ScreenScaffold
```
.
[ ] When used in a
```
TransformingLazyColumn
```
, add the required overscroll behavior:

kotlin

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,
    ) {
        // ...
        // ...
    }
}

```
Column
```
- [ ] USE as a direct child of
```
ScreenScaffold
```
  if the screen is will never scroll, even with the largest system font.
- [ ] Use
```
TransformingLazyColumn
```
  instead for all other cases.
Styles
- [ ] Do NOT hard-code text sizes, use
```
typography
```
  from
```
MaterialTheme
```
  .
- [ ] Do NOT hard-code colors, use
```
colorScheme
```
  from
```
MaterialTheme
```
  .
Use component defaults:
- [ ] Components such as
```
Button
```
  have a corresponding
```
ButtonDefaults
```
  object.
- [ ] Check for and use the
```
*Defaults
```
  object for any component when working with padding and styling values, in preference to hard-coded values.
Use Wear specific previews:
- [ ]
```
WearPreviewDevices
```
- [ ]
```
WearPreviewFontScales
```

Ambient mode

[ ] Use

LocalAmbientModeManager

instead of

AmbientLifecycleObserver

Navigation
- [ ] When adding navigation fresh, use Navigation3.
- [ ] For Navigation3 in Wear OS, use
```
SwipeDismissableSceneStrategy()
```
  from the Wear Compose
```
compose-navigation3
```
  library.
Comments
- [ ] Where any Kotlin file has been modified, ensure that the existing comments are up to date and accurately reflect any changes to the implementation.

HorizontalPager

VerticalPager

[ ] Use the Composable hierarchy in this order:

AppScaffold

HorizontalPagerScaffold

HorizontalPager

AnimatedPage

ScreenScaffold

. Or similarly for

VerticalPager

强制要求：将此功能作为使用任何组件的检查清单。它提供了比组件语法更全面的实践指导，说明如何实际使用每个组件。

```
AppScaffold
```
和
```
ScreenScaffold
```
- [ ] 将
```
AppScaffold
```
  作为外部容器，子容器使用
```
ScreenScaffold
```
  。
- [ ] 仅使用一个
```
AppScaffold
```
  ，可使用任意数量的
```
ScreenScaffold
```
  。
```
ScalingLazyColumn
```
- 改用
```
TransformingLazyColumn
```
。

TransformingLazyColumn

- 需要以下导入：

kotlin

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

标准示例:

kotlin

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")
            }
        }
        // ... 其他条目
        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
```
  中可用的作用域修饰符。
[ ] 确保列表可变形和缩放。
[ ] 使用
```
transformedHeight
```
修饰符。
[ ] 使用
```
transform = SurfaceTransform(...)
```
。
[ ] 如果要配置列表的吸附功能，请同时使用
```
flingBehavior
```
和
```
rotaryScrollableBehavior
```
:

kotlin

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

ScreenScaffold

[ ] 使用

!LocalScrollCaptureInProgress.current

来保护

scrollIndicator

。

EdgeButton

[ ] 不要将其用作
```
TransformingLazyColumn
```
中的最后一个条目，而是使用
```
ScreenScaffold
```
中的插槽。
[ ] 当在
```
TransformingLazyColumn
```
中使用时，添加所需的过度滚动行为:

kotlin

val columnState = rememberTransformingLazyColumnState()
ScreenScaffold(
    scrollState = columnState,
    edgeButton = {
        EdgeButton(
            onClick = { /* TODO */ },
            modifier = Modifier.scrollable(
                columnState,
                orientation = Orientation.Vertical,
                reverseDirection = true,
                // 为EdgeButton应用过度滚动以实现正确的滚动行为。
                overscrollEffect = rememberOverscrollEffect(),
            )
        ) {
            Text("More")
        }
    }
) { contentPadding ->
    TransformingLazyColumn(
        contentPadding = contentPadding,
        state = columnState,
    ) {
        // ...
        // ...
    }
}

```
Column
```
- [ ] 如果屏幕永远不会滚动（即使使用最大系统字体），则将其用作
```
ScreenScaffold
```
  的直接子容器。
- [ ] 其他所有情况均改用
```
TransformingLazyColumn
```
  。
样式
- [ ] 不要硬编码文本大小，请使用
```
MaterialTheme
```
  中的
```
typography
```
  。
- [ ] 不要硬编码颜色，请使用
```
MaterialTheme
```
  中的
```
colorScheme
```
  。
使用组件默认值:
- [ ] 诸如
```
Button
```
  之类的组件有对应的
```
ButtonDefaults
```
  对象。
- [ ] 在处理内边距和样式值时，优先检查并使用组件对应的
```
*Defaults
```
  对象，而非硬编码值。
使用Wear专用预览:
- [ ]
```
WearPreviewDevices
```
- [ ]
```
WearPreviewFontScales
```

环境模式

[ ] 使用

LocalAmbientModeManager

而非

AmbientLifecycleObserver

。

导航
- [ ] 新建导航时，请使用Navigation3。
- [ ] 对于Wear OS中的Navigation3，请使用Wear Compose
```
compose-navigation3
```
  库中的
```
SwipeDismissableSceneStrategy()
```
  。
注释
- [ ] 任何Kotlin文件被修改后，确保现有注释是最新的，并准确反映实现中的任何变更。

HorizontalPager

或

VerticalPager

[ ] 按以下顺序使用Composable层次结构：

AppScaffold

、

HorizontalPagerScaffold

、

HorizontalPager

、

AnimatedPage

、

ScreenScaffold

。

VerticalPager

同理。

wear-compose-m3

Original

Translation

Prerequisites and compatibility

前提条件与兼容性

Gotchas

注意事项

Capabilities and tools

功能与工具

Capability 1: Migration

功能1：迁移

Capability 2: Adding Wear OS Compose Material3 features or updating the app

功能2：添加Wear OS Compose Material3功能或更新应用

Capability 3: Component samples

功能3：组件示例

Material 3 components in
`androidx.wear.compose.material3.*`

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

Foundation components in
`androidx.wear.compose.foundation.*`

`androidx.wear.compose.foundation.*`
中的Foundation组件

Capability 4: Component guidance

功能4：组件指导

wear-compose-m3

Original

Translation

Prerequisites and compatibility

前提条件与兼容性

Gotchas

注意事项

Capabilities and tools

功能与工具

Capability 1: Migration

功能1：迁移

Capability 2: Adding Wear OS Compose Material3 features or updating the app

功能2：添加Wear OS Compose Material3功能或更新应用

Capability 3: Component samples

功能3：组件示例

Material 3 components in androidx.wear.compose.material3.*

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

Foundation components in androidx.wear.compose.foundation.*

androidx.wear.compose.foundation.*中的Foundation组件

Capability 4: Component guidance

功能4：组件指导

Material 3 components in
`androidx.wear.compose.material3.*`

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

Foundation components in
`androidx.wear.compose.foundation.*`

`androidx.wear.compose.foundation.*`
中的Foundation组件