Compose で XML テーマをマテリアル 3 に移行する

既存のアプリに Compose を導入する場合は、Compose コンポーネントで MaterialTheme を使用するようにマテリアル XML テーマを移行する必要があります。つまり、アプリのテーマ設定には、View ベースのテーマと Compose テーマの 2 つの信頼できる情報源があります。スタイル設定の変更は、複数の場所で行う必要があります。アプリが Compose に完全に移行されたら、XML テーマ設定を削除します。

色の移行には、マテリアルテーマビルダーツールを使用できます。

XML から Compose への移行を開始するときは、テーマ設定を Material 3 Compose のテーマ設定に移行します。

用語集

用語	定義
`MaterialTheme`	Compose UI コンポーネントにテーマ設定（色、タイポグラフィ、シェイプ）を提供するコンポーズ可能な関数。
`Shape`	`MaterialTheme` のカスタムコンポーネントのシェイプを定義するために使用される Compose オブジェクト。
`Typography`	`MaterialTheme` のカスタムテキストスタイル（フォントファミリー、サイズ、太さ）を定義するために使用される Compose オブジェクト。
`Color`	`MaterialTheme` のカスタムカラーパターンを定義するために使用される Compose オブジェクト。
XML テーマ	XML ファイルで定義され、View システムで使用される Android のテーマ設定システム。

制限事項

移行を行う前に、次の制限事項に注意してください。

このガイドでは、Material 3 への移行のみに焦点を当てます。代替のデザインシステムからの移行については、マテリアル 2 または Compose のカスタムデザインシステムをご覧ください。
最終的な目標は Compose への完全な移行であり、これにより XML テーマ設定を削除できます。このガイドでは移行方法について説明しますが、XML テーマ設定を最終的に削除する方法については説明しません。

ステップ 1: デザインシステムを評価する

XML View プロジェクトで使用されているデザインシステムを特定します。既存のデザインシステムを Compose の Material 3 に移行するための移行パスと必要な手順を分析します。

ステップ 2: テーマのソースファイルを特定する

XML では ?attr/colorPrimary と記述します。Compose では、MaterialTheme.* を使用してテーマ値にアクセスします。

テーマ設定に必要なすべての XML リソースとファイル（ライトモードとダークモードのカラースキームと修飾子、テーマ、シェイプ、ディメンション、タイポグラフィ、スタイル、その他の関連ファイル）を特定して見つけます。

文字列などのリソースはそのまま再利用できるため、移行する必要はありません。

ステップ 3: 色を移行する

重要な原則: XML では名前付きの 16 進数色が使用されます。マテリアル 3 では、セマンティックロール（primary、onPrimary、surface など）を使用します。カラーを 16 進数で命名するのをやめ、ロールで命名してください。

例:

XML カラー名	Material 3 の役割
`colorPrimary`	`primary`
`colorPrimaryDark` / `colorPrimaryVariant`	`primaryContainer` または `secondary`
`colorAccent`	`secondary` または `tertiary`
`colorOnPrimary`	`onPrimary`
`android:colorBackground`	`background`
`colorSurface`	`surface`
`colorOnSurface`	`onSurface`
`colorError`	`error`
`colorOnError`	`onError`
`colorOutline`	`outline`
`colorSurfaceVariant`	`surfaceVariant`
`colorOnSurfaceVariant`	`onSurfaceVariant`

ダークとライトのカラーパターンを XML から Material 3 Compose の同等のものに移行します。

ステップ 4: カスタムシェイプとタイポグラフィを移行する

アプリでカスタムシェイプを使用している場合:
1. Compose コードで、XML のシェイプ定義を複製する Shape オブジェクトを定義します。
2. この Shape オブジェクトを MaterialTheme に渡します。
  
  詳細については、シェイプをご覧ください。
アプリでカスタムタイポグラフィを使用している場合:
1. Compose コードで、XML のテキストスタイルとフォント定義を複製する Typography オブジェクトを定義します。
2. この Typography オブジェクトを MaterialTheme に渡します。
  
  詳しくは、タイポグラフィをご覧ください。

Compose ロール	XML 名
`displayLarge`	`TextAppearance.Material3.DisplayLarge`
`displayMedium`	`TextAppearance.Material3.DisplayMedium`
`displaySmall`	`TextAppearance.Material3.DisplaySmall`
`headlineLarge`	`TextAppearance.Material3.HeadlineLarge`
`headlineMedium`	`TextAppearance.Material3.HeadlineMedium`
`headlineSmall`	`TextAppearance.Material3.HeadlineSmall`
`titleLarge`	`TextAppearance.Material3.TitleLarge`
`titleMedium`	`TextAppearance.Material3.TitleMedium`
`titleSmall`	`TextAppearance.Material3.TitleSmall`
`bodyLarge`	`TextAppearance.Material3.BodyLarge`
`bodyMedium`	`TextAppearance.Material3.BodyMedium`
`bodySmall`	`TextAppearance.Material3.BodySmall`
`labelLarge`	`TextAppearance.Material3.LabelLarge`
`labelMedium`	`TextAppearance.Material3.LabelMedium`
`labelSmall`	`TextAppearance.Material3.LabelSmall`

ステップ 5: スタイル（styles.xml）を移行する

XML スタイル（styles.xml）システムは、次のスタイルと外観を定義します。 1. ウィンドウとダイアログのウィジェット、コンポーネント、テーマ 2. タイポグラフィ 3. テーマとオーバーレイ 4. シェイプ

XML ビューとコンポーネントは、複数の属性を組み合わせてスタイルを作成します。スタイルは styles.xml から次の 2 つの方法で設定します。 1. XML ビュー 2 で「style="@style/..."」を直接かつ明示的に設定します。より大きなテーマ（theme.xml）の一部として、コンポーネントのスタイルを間接的かつ暗黙的に設定する

Compose にはスタイルに直接相当するものはありません。代わりに、スタイルはコンポーザブルのパラメータとして渡されるか、AppTheme で定義されるか、定義されたスタイルで再利用可能なレイヤードコンポーザブルバリエーションを作成することで定義されます。

スタイルとベースコンポーネントに従って名前が付けられた個別の @Composable 関数を提供し、それらのコンポーネントのスタイリングとユースケースの違いを示します。

パターン: XML 要素がカスタムスタイル（style="@style/MyPrimaryButton" など）を使用している場合は、スタイルをインラインで複製しようとしないでください。代わりに、特定のコンポーザブルを作成することを提案します。
例:
- XML: <Button style="@style/MyPrimaryButton" ... />
- 作成: MyPrimaryButton(onClick = { ... })
共通の属性グループ: スタイルで共通の修飾子（パディング + 高さなど）を設定する場合は、読み取り可能な拡張プロパティまたは共有の Modifier 変数に抽出します。

一般的な例

XML	作成
`Theme.MaterialComponents.*`	`MaterialTheme(colorScheme, typography, shapes) { }`
`TextAppearance.Material3.BodyMedium`	`Typography(bodyMedium = ...)` で定義される `TextStyle(...)`
`ShapeAppearance.*.SmallComponent`	`Shapes(small = RoundedCornerShape(X.dp))`
`Widget.MaterialComponents.Button`	`Button(colors = ButtonDefaults.buttonColors(...))`
`Widget.MaterialComponents.CardView`	`Card(shape=..., elevation=..., colors=...)`
`Widget.*.TextInputLayout.OutlinedBox`	`OutlinedTextField(colors = OutlinedTextFieldDefaults.colors(...))`
`Widget.*.Chip.Filter`	`FilterChip(colors = FilterChipDefaults.filterChipColors(...))`
`Widget.*.Toolbar.Primary`	`TopAppBar(colors = TopAppBarDefaults.topAppBarColors(...))`
`Widget.*.FloatingActionButton`	`FloatingActionButton(containerColor = ...)`
`backgroundTint`	`containerColor`（`ComponentDefaults.ComponentColors()`）
`android:textColor`	`contentColor`（`ComponentDefaults.ComponentColors()`）
`cornerRadius`	`shape = RoundedCornerShape(X.dp)`
`android:elevation`	`elevation = ComponentDefaults.elevation(defaultElevation = X.dp)`
`android:padding`	`contentPadding = PaddingValues(...)` または `Modifier.padding()`
`android:minHeight`	`Modifier.heightIn(min = X.dp)`
`strokeColor` + `strokeWidth`	`border = BorderStroke(width, color)`
`android:textSize`	`fontSize = X.sp`（`TextStyle`）

ステップ 6: テーマの移行を検証する

Compose の新しいマテリアルテーマの信頼できる情報源として、常に元の XML テーマの既存のテーマ値を使用します。ブランドの一貫性を維持し、視覚的な回帰を避けるため、移行中に新しいテーマ値を考案しないでください。

新しい Compose テーマの値が既存の XML の値と一致していることを確認します。移行した値をハードコードしないでください。