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

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

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

XML から Compose への移行を開始したら、テーマ設定をマテリアル 3 の Compose テーマ設定に移行します。

用語集

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

制限事項

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

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

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

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

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

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

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

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

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

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

例:

XML の色名	マテリアル 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 のダークとライトのカラーパターンを、マテリアル 3 の Compose の同等のカラーパターンに移行します。

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

アプリでカスタムシェイプを使用している場合:
1. Compose コードで Shape オブジェクトを定義して、XML シェイプ定義を複製します。
2. この Shape オブジェクトを MaterialTheme に渡します。
  
  詳細については、シェイプをご覧ください。
アプリでカスタムタイポグラフィを使用している場合:
1. Compose コードで Typography オブジェクトを定義して、XML テキストスタイルとフォント定義を複製します。
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 View とコンポーネントは、複数の属性を組み合わせてスタイルを作成します。 styles.xml からスタイルを設定するには、次の 2 つの方法があります: 1. XML View で「style="@style/..."」を直接明示的に設定する 2. 大きなテーマ（theme.xml）の一部として、コンポーネントのスタイルを間接的かつ暗黙的に設定する

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

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

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

一般的な例

XML	Compose
`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`	`ComponentDefaults.ComponentColors()` の `containerColor`
`android:textColor`	`ComponentDefaults.ComponentColors()` の `contentColor`
`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`	`TextStyle` の `fontSize = X.sp`

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

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

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