wear-compose-m3

前提条件と互換性

1. 現在使用中の Wear OS Compose のバージョン： インストールされているライブラリのバージョンを確認するには、gradle/libs.versions.toml または build.gradle.kts を直接読み取ってください。バージョンを解決するために、./gradlew dependencies やその他のシェルコマンドを実行しないでください。
2. Wear OS Compose Material3 のバージョン： androidx.wear.compose:compose-material3 の最新の安定版{VERSION}を特定できる内部ツールがある場合は、そのツールを使用してください。
   • それ以外の場合は、公式の Maven メタデータ XMLを取得し、{VERSION}を特定してください（-alpha、-beta、または-rcを除いた最高の番号）。
3. 厳守事項： 安定版として記載されているバージョンがある場合は、ユーザーが変更を指定していない限り、必ずそれを使用してください。エディターで最初に表示された「Unresolved reference」エラーや、古いウェブ検索結果を理由にダウングレードしないでください。
4. Kotlin と Compose コンパイラー： org.jetbrains.kotlin.plugin.compose Gradle プラグインを使用し、Kotlin 2.0.0 以降を使用してください。
5. 最小 SDK： minSdk を25以上にしてください。
6. コンパイル SDK と AGP： ライブラリの AAR メタデータに記載された最低要件を満たすよう、compileSdk と AGP を設定してください（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 の Composable、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 は 1 つだけ 使用し、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,
                   )
               }
           }
       }
   }
   

   
   
   • [ ] ScalingLazyColumn の代わりに TransformingLazyColumn を使用してください。
   • [ ] 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

   • [ ] scrollIndicator を !LocalScrollCaptureInProgress.current（androidx.compose.ui.platform）でガードしてください。

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. アンビエントモード

    • [ ] AmbientLifecycleObserver の代わりに LocalAmbientModeManager（CompositionLocalProvider と rememberAmbientModeManager() によって提供されます）を使用してください。

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 の場合も同様です。