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

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

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

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

用語集

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

制限事項

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

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

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

XML ビュー プロジェクトで使用されているデザイン システムを特定します。既存のデザイン システムを 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 から Material 3 Compose の同等のカラーパターンに移行します。

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

  • アプリでカスタム シェイプを使用している場合:

    1. Compose コードで、XML シェイプ定義を複製する Shapes オブジェクトを定義します。

    2. この Shapes オブジェクトを MaterialTheme に渡します。

      詳細については、シェイプをご覧ください。

  • アプリでカスタム タイポグラフィを使用している場合:

    1. Compose コードで Typography オブジェクトを定義して、XML テキスト スタイルとフォント定義を複製します。

    2. この Typography オブジェクトを MaterialTheme に渡します。

      詳しくは、タイポグラフィをご覧ください。

作成ロール 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 ビューで「style="@style/..."」を直接明示的に設定する
  2. より大きなテーマ（theme.xml）の一部として、コンポーネントのスタイルを間接的かつ暗黙的に設定する

Compose にはスタイルに直接対応するものはありません。代わりに、AppTheme で定義された新しい試験運用版の Styles API を使用して、パラメータまたは修飾子としてコンポーザブルにスタイルを渡すか、定義されたスタイルを使用して、レイヤ化された再利用可能なコンポーザブル バリエーションを作成します。

スタイルとベース コンポーネントに従って名前が付けられた個別のコンポーズ可能な関数を指定して、それらのコンポーネントのスタイル設定とユースケースの違いを示します。

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

よくある例

XML 作成
Theme.Material3.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...)（Typography(bodyMedium = ...) で定義）
ShapeAppearance.*.SmallComponent Shapes(small = RoundedCornerShape(X.dp))
Widget.Material3.Button Button(colors = ButtonDefaults.buttonColors(...))
Widget.Material3.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 値と一致することを確認します。移行された値をハードコードしないでください。