Compose でマテリアル 2 からマテリアル 3 に移行する

マテリアル デザイン 3 はマテリアル デザインの進化版です。最新のテーマ設定、コンポーネント、Material You のパーソナライズ機能（ダイナミック カラーなど）などが含まれています。マテリアル デザイン 2 の更新版であり、Android 12 以降の新しい視覚的スタイルおよびシステム UI と調和します。

このガイドでは、Compose Material（androidx.compose.material）Jetpack ライブラリから Compose Material 3（androidx.compose.material3）Jetpack ライブラリへの移行に焦点を当てます。

アプローチ

一般的に、1 つのアプリで M2 と M3 の両方を長期的に使用すべきではありません。これは、2 つのデザイン システムとそれぞれのライブラリが、UX / UI デザインと Compose の実装に関して大きく異なるためです。

アプリは、特定のデザイン システム（Figma を使用して作成されたものなど）を使用している場合があります。その場合、デベロッパーまたはデザインチームは、Compose の移行を開始する「前」に、デザイン システムを M2 から M3 に移行することを強くおすすめします。アプリの UX/UI デザインが M2 をベースとしている場合、アプリを M3 に移行するのは合理的ではありません。

また、アプリのサイズ、複雑さ、UX/UI デザインに応じて、移行のアプローチを変えるべきです。それにより、コードベースへの影響を最小限に抑えることができます。段階的に移行するアプローチを取る必要があります。

移行のタイミング

できるだけ早く移行を開始してください。ただし、現実的にアプリが M2 から M3 への完全な移行に適しているかを考慮することが重要です。移行を開始する前に、次のような阻害要因のシナリオをいくつか調査することを検討する必要があります。

上記のシナリオの影響を受ける場合でも、アプリのアップデートをコミットしてリリースする際は、その前に段階的な移行のアプローチを取る必要があります。その場合は、M2 と M3 を共存させて使用し、M3 に移行しながら M2 を徐々に取り除きます。

段階的なアプローチ

段階的な移行の一般的な手順は次のとおりです。

1. M2 の依存関係を残したまま、M3 の依存関係を追加します。
2. アプリのテーマの M2 バージョンを残したまま、アプリのテーマの M3 バージョンを追加します。
3. アプリのサイズと複雑さに応じて、個々のモジュール、画面、コンポーザブルを M3 に移行します（詳しくは、以降のセクションをご覧ください）。
4. 移行が完全に終了したら、アプリのテーマの M2 バージョンを削除します。
5. M2 の依存関係を削除します。

依存関係

M3 には、M2 とは別個のパッケージとバージョンがあります。

implementation "androidx.compose.material:material:$m2-version"

implementation "androidx.compose.material3:material3:$m3-version"

最新の M3 バージョンについては、Compose Material 3 のリリースページをご覧ください。

メインの M2 ライブラリと M3 ライブラリにないその他のマテリアル依存関係は、変更されていません。それらの依存関係では M2 と M3 のパッケージとバージョンが混在して使用されていますが、これは移行には影響しません。それらは M3 でそのまま使用できます。

試験運用版 API

一部の M3 API は試験運用版とみなされています。その場合は、ExperimentalMaterial3Api アノテーションを使用して、関数レベルまたはファイルレベルでオプトインする必要があります。

import androidx.compose.material3.ExperimentalMaterial3Api

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AppComposable() {
    // M3 composables
}

テーマ設定

テーマ コンポーザブルは M2 と M3 のどちらでも MaterialTheme という名前ですが、インポート パッケージとパラメータが異なります。

import androidx.compose.material.MaterialTheme

MaterialTheme(
    colors = AppColors,
    typography = AppTypography,
    shapes = AppShapes
) {
    // M2 content
}

import androidx.compose.material3.MaterialTheme

MaterialTheme(
    colorScheme = AppColorScheme,
    typography = AppTypography,
    shapes = AppShapes
) {
    // M3 content
}

カラー

M3 のカラーシステムは M2 とは大きく異なります。カラー パラメータの数が増えており、名前と M3 コンポーネントへのマッピングが異なります。これは、Compose では、M2 の Colors クラス、M3 の ColorScheme クラス、および関連する関数に適用されます。

import androidx.compose.material.lightColors
import androidx.compose.material.darkColors

val AppLightColors = lightColors(
    // M2 light Color parameters
)
val AppDarkColors = darkColors(
    // M2 dark Color parameters
)
val AppColors = if (darkTheme) {
    AppDarkColors
} else {
    AppLightColors
}

import androidx.compose.material3.lightColorScheme
import androidx.compose.material3.darkColorScheme

val AppLightColorScheme = lightColorScheme(
    // M3 light Color parameters
)
val AppDarkColorScheme = darkColorScheme(
    // M3 dark Color parameters
)
val AppColorScheme = if (darkTheme) {
    AppDarkColorScheme
} else {
    AppLightColorScheme
}

M2 と M3 のカラーシステムに大きな違いがあるため、Color パラメータの合理的なマッピングは存在しません。代わりに、マテリアル テーマビルダー ツールを使用して、M3 カラーパターンを生成します。このツールで M2 カラーをコアソースカラーとして使用し、M3 カラーパターンで使用される色調パレットに拡張します。出発点として、次のマッピングを使用することをおすすめします。

ライトテーマとダークテーマのカラーの 16 進数コード値をツールからコピーし、それらを使用して M3 ColorScheme インスタンスを実装できます。または、マテリアル テーマビルダーで Compose コードをエクスポートすることもできます。

isLight

M2 の Colors クラスとは異なり、M3 の ColorScheme クラスには isLight パラメータが含まれていません。一般的に、テーマレベルでこの情報を必要とするものは、すべてモデル化を試みる必要があります。次に例を示します。

import androidx.compose.material.lightColors
import androidx.compose.material.darkColors
import androidx.compose.material.MaterialTheme

@Composable
private fun AppTheme(
  darkTheme: Boolean = isSystemInDarkTheme(),
  content: @Composable () -> Unit
) {
  val colors = if (darkTheme) darkColors(…) else lightColors(…)
  MaterialTheme(
      colors = colors,
      content = content
  )
}

@Composable
fun AppComposable() {
    AppTheme {
        val cardElevation = if (MaterialTheme.colors.isLight) 0.dp else 4.dp
        …
    }
}

import androidx.compose.material3.lightColorScheme
import androidx.compose.material3.darkColorScheme
import androidx.compose.material3.MaterialTheme

val LocalCardElevation = staticCompositionLocalOf { Dp.Unspecified }
@Composable
private fun AppTheme(
   darkTheme: Boolean = isSystemInDarkTheme(),
    content: @Composable () -> Unit
) {
   val cardElevation = if (darkTheme) 4.dp else 0.dp
    CompositionLocalProvider(LocalCardElevation provides cardElevation) {
        val colorScheme = if (darkTheme) darkColorScheme(…) else lightColorScheme(…)
        MaterialTheme(
            colorScheme = colorScheme,
            content = content
        )
    }
}

@Composable
fun AppComposable() {
    AppTheme {
        val cardElevation = LocalCardElevation.current
        …
    }
}

詳しくは、Compose のカスタム デザイン システムのガイドをご覧ください。

ダイナミック カラー

M3 の新機能にダイナミック カラーがあります。M3 ColorScheme では、カスタムカラーを使用する代わりに、以下の関数を使用して Android 12 以降のデバイスの壁紙の色を利用できます。

• dynamicLightColorScheme
• dynamicDarkColorScheme

タイポグラフィ

M3 のタイポグラフィ システムは M2 とは異なります。タイポグラフィ パラメータの数はほぼ同じですが、名前と M3 コンポーネントへのマッピングが異なります。これは、Compose では、M2 の Typography クラスと M3 の Typography クラスに適用されます。

import androidx.compose.material.Typography

val AppTypography = Typography(
    // M2 TextStyle parameters
)

import androidx.compose.material3.Typography

val AppTypography = Typography(
    // M3 TextStyle parameters
)

出発点として、次の TextStyle パラメータ マッピングを使用することをおすすめします。

シェイプ

M3 のシェイプ システムは M2 とは異なります。シェイプ パラメータの数が増えており、名前と M3 コンポーネントへのマッピングが異なります。これは、Compose では、M2 の Shapes クラスと M3 の Shapes クラスに適用されます。

import androidx.compose.material.Shapes

val AppShapes = Shapes(
    // M2 Shape parameters
)

import androidx.compose.material3.Shapes

val AppShapes = Shapes(
    // M3 Shape parameters
)

出発点として、次の Shape パラメータ マッピングを使用することをおすすめします。

コンポーネントとレイアウト

M2 のコンポーネントとレイアウトのほとんどは M3 でも提供されています。ただし、M2 にはあったが M3 にはないものと、M2 にはなかった新しいものがあります。さらに、一部の M3 コンポーネントには、M2 の同等のコンポーネントよりも多くのバリエーションがあります。一般的に、M3 の API サーフェスは、M2 の最も近い同等の API サーフェスにできる限り類似したものを提供しようとします。

カラー、タイポグラフィ、シェイプの各システムが更新されたため、M3 コンポーネントは、M2 とは異なり、新しいテーマ設定値にマップされる傾向があります。これらのマッピングの信頼できる情報源として、Compose Material 3 ソースコードの tokens ディレクトリを確認することをおすすめします。

コンポーネントによっては特別な考慮が必要ですが、出発点として次の関数マッピングを使用することをおすすめします。

欠落している API:

置き換えられた API:

名前が変更された API:

その他のすべての API:

最新の M3 のコンポーネントとレイアウトについては、Compose Material 3 API リファレンスの概要をご覧ください。新しい API と更新された API については、リリースページでご確認ください。

スキャフォールド、スナックバー、ナビゲーション ドロワー

M3 のスキャフォールドは M2 とは異なります。メインのレイアウト コンポーザブルは M2 と M3 のどちらでも Scaffold という名前ですが、インポート パッケージとパラメータが異なります。

import androidx.compose.material.Scaffold

Scaffold(
    // M2 scaffold parameters
)

import androidx.compose.material3.Scaffold

Scaffold(
    // M3 scaffold parameters
)

M2 の Scaffold に含まれる backgroundColor パラメータは、M3 の Scaffold では containerColor という名前になりました。

import androidx.compose.material.Scaffold

Scaffold(
    backgroundColor = …,
    content = { … }
)

import androidx.compose.material3.Scaffold

Scaffold(
    containerColor = …,
    content = { … }
)

M2 の ScaffoldState クラスは、不要になった drawerState パラメータを含んでいるため、M3 ではなくなりました。M3 の Scaffold でスナックバーを表示するには、代わりに SnackbarHostState を使用します。

import androidx.compose.material.Scaffold
import androidx.compose.material.rememberScaffoldState

val scaffoldState = rememberScaffoldState()
val scope = rememberCoroutineScope()

Scaffold(
    scaffoldState = scaffoldState,
    content = {
        …
        scope.launch {
            scaffoldState.snackbarHostState.showSnackbar(…)
        }
    }
)

import androidx.compose.material3.Scaffold
import androidx.compose.material3.SnackbarHost
import androidx.compose.material3.SnackbarHostState

val snackbarHostState = remember { SnackbarHostState() }
val scope = rememberCoroutineScope()

Scaffold(
    snackbarHost = { SnackbarHost(snackbarHostState) },
    content = {
        …
        scope.launch {
            snackbarHostState.showSnackbar(…)
        }
    }
)

M2 における Scaffold の drawer* パラメータは、M3 ではすべて Scaffold から削除されました。これには、drawerShape や drawerContent などのパラメータが含まれます。M3 の Scaffold でドロワーを表示するには、代わりに ModalNavigationDrawer などのナビゲーション ドロワー コンポーザブルを使用します。

import androidx.compose.material.DrawerValue
import
import androidx.compose.material.Scaffold
import androidx.compose.material.rememberDrawerState
import androidx.compose.material.rememberScaffoldState

val scaffoldState = rememberScaffoldState(
    drawerState = rememberDrawerState(DrawerValue.Closed)
)
val scope = rememberCoroutineScope()

Scaffold(
    scaffoldState = scaffoldState,
    drawerContent = { … },
    drawerGesturesEnabled = …,
    drawerShape = …,
    drawerElevation = …,
    drawerBackgroundColor = …,
    drawerContentColor = …,
    drawerScrimColor = …,
    content = {
        …
        scope.launch {
            scaffoldState.drawerState.open()
        }
    }
)

import androidx.compose.material3.DrawerValue
import androidx.compose.material3.ModalDrawerSheet
import androidx.compose.material3.ModalNavigationDrawer
import androidx.compose.material3.Scaffold
import androidx.compose.material3.rememberDrawerState

val drawerState = rememberDrawerState(DrawerValue.Closed)
val scope = rememberCoroutineScope()

ModalNavigationDrawer(
    drawerState = drawerState,
    drawerContent = {
        ModalDrawerSheet(
            drawerShape = …,
            drawerTonalElevation = …,
            drawerContainerColor = …,
            drawerContentColor = …,
            content = { … }
        )
    },
    gesturesEnabled = …,
    scrimColor = …,
    content = {
        Scaffold(
            content = {
                …
                scope.launch {
                    drawerState.open()
                }
            }
        )
    }
)

トップ アプリバー

M3 のトップ アプリバーは M2 とは異なります。メインのトップ アプリバー コンポーザブルは M2 と M3 のどちらでも TopAppBar という名前ですが、インポート パッケージとパラメータが異なります。

import androidx.compose.material.TopAppBar

TopAppBar(…)

import androidx.compose.material3.TopAppBar

TopAppBar(…)

以前 M2 の TopAppBar 内でコンテンツを中央に配置していた場合は、M3 の CenterAlignedTopAppBar を使用することを検討してください。MediumTopAppBar と LargeTopAppBar の使用も検討することをおすすめします。

M3 のトップ アプリバーには、TopAppBarScrollBehavior クラスを通じてスクロールに関する異なる機能（高度の変更など）を提供する新しい scrollBehavior パラメータが含まれています。このパラメータは、Modifer.nestedScroll によるコンテンツのスクロールと連携して機能します。これは、M2 の TopAppBar で、elevation パラメータを手動で変更することにより可能になりました。

import androidx.compose.material.AppBarDefaults
import androidx.compose.material.Scaffold
import androidx.compose.material.TopAppBar

val state = rememberLazyListState()
val isAtTop by remember {
    derivedStateOf {
        state.firstVisibleItemIndex == 0 && state.firstVisibleItemScrollOffset == 0
    }
}

Scaffold(
    topBar = {
        TopAppBar(
            elevation = if (isAtTop) {
                0.dp
            } else {
                AppBarDefaults.TopAppBarElevation
            },
            …
        )
    },
    content = {
        LazyColumn(state = state) { … }
    }
)

import androidx.compose.material3.Scaffold
import androidx.compose.material3.TopAppBar
import androidx.compose.material3.TopAppBarDefaults

val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior()

Scaffold(
    modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
    topBar = {
        TopAppBar(
            scrollBehavior = scrollBehavior,
            …
        )
    },
    content = {
        LazyColumn { … }
    }
)

ボトム ナビゲーション / ナビゲーション バー

M2 のボトム ナビゲーションは、M3 ではナビゲーション バーという名前に変更されました。M2 には BottomNavigation および BottomNavigationItem コンポーザブルがありますが、M3 には NavigationBar および NavigationBarItem コンポーザブルがあります。

import androidx.compose.material.BottomNavigation
import androidx.compose.material.BottomNavigationItem

BottomNavigation {
    BottomNavigationItem(…)
    BottomNavigationItem(…)
    BottomNavigationItem(…)
}

import androidx.compose.material3.NavigationBar
import androidx.compose.material3.NavigationBarItem

NavigationBar {
    NavigationBarItem(…)
    NavigationBarItem(…)
    NavigationBarItem(…)
}

ボタン、アイコンボタン、FAB

M3 のボタン、アイコンボタン、フローティング アクション ボタン（FAB）は M2 とは異なります。M3 には、M2 のボタン コンポーザブルがすべて含まれています。

import androidx.compose.material.Button
import androidx.compose.material.ExtendedFloatingActionButton
import androidx.compose.material.FloatingActionButton
import androidx.compose.material.IconButton
import androidx.compose.material.IconToggleButton
import androidx.compose.material.OutlinedButton
import androidx.compose.material.TextButton

// M2 buttons
Button(…)
OutlinedButton(…)
TextButton(…)
// M2 icon buttons
IconButton(…)
IconToggleButton(…)
// M2 FABs
FloatingActionButton(…)
ExtendedFloatingActionButton(…)

import androidx.compose.material3.Button
import androidx.compose.material3.ExtendedFloatingActionButton
import androidx.compose.material3.FloatingActionButton
import androidx.compose.material3.IconButton
import androidx.compose.material3.IconToggleButton
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.TextButton

// M3 buttons
Button(…)
OutlinedButton(…)
TextButton(…)
// M3 icon buttons
IconButton(…)
IconToggleButton(…)
// M3 FABs
FloatingActionButton(…)
ExtendedFloatingActionButton(…)

M3 には、新しいボタンのバリエーションもあります。それらについては、Compose Material 3 API リファレンスの概要でご確認ください。

切り替える

M3 のスイッチは M2 とは異なります。スイッチ コンポーザブルは M2 と M3 のどちらでも Switch という名前ですが、インポート パッケージが異なります。

import androidx.compose.material.Switch

Switch(…)

import androidx.compose.material3.Switch

Switch(…)

サーフェスと高度

M3 のサーフェス システムと高度システムは M2 とは異なります。M3 には次の 2 種類の高度があります。

• シャドウ高度（シャドウを投影 / M2 と同じ）
• 色調高度（色をオーバーレイ / M3 の新機能）

これは、Compose では、M2 の Surface 関数と M3 の Surface 関数に適用されます。

import androidx.compose.material.Surface

Surface(
    elevation = …
) { … }

import androidx.compose.material3.Surface

Surface(
    shadowElevation = …,
    tonalElevation = …
) { … }

UX / UI デザインの設定によっては、M2 の elevation の Dp 値を、M3 の shadowElevation と tonalElevation の両方またはいずれかに使用できます。Surface はほとんどのコンポーネントの背後にあるバッキング コンポーザブルであるため、コンポーネントのコンポーザブルは、同じ方法で移行する必要がある高度パラメータも公開できます。

M2 のダークテーマでの高度オーバーレイというコンセプトは、M3 では色調高度に置き換えられました。その結果、M3 では ElevationOverlay と LocalElevationOverlay がなくなり、M2 の LocalAbsoluteElevation は LocalAbsoluteTonalElevation に変更されました。

強調とコンテンツのアルファ

M3 の強調は M2 とは大きく異なります。M2 の強調では、特定のアルファ値を持つオンのカラーを使用して、テキストやアイコンなどのコンテンツを差別化することに重点が置かれていました。M3 では、次のような異なるアプローチが取られています。

• 拡張された M3 カラーシステムの「オン」のカラーに加えて、その「バリアントのオン」のカラーを使用する。
• テキストでは異なるフォントの太さを使用する。

その結果、M3 では ContentAlpha と LocalContentAlpha がなくなり、それらの置き換えが必要になりました。

出発点として、次のマッピングを使用することをおすすめします。

M2 と M3 のアイコンの強調の例を次に示します。

import androidx.compose.material.ContentAlpha
import androidx.compose.material.LocalContentAlpha

// High emphasis
CompositionLocalProvider(LocalContentAlpha provides ContentAlpha.high) {
    Icon(…)
}
// Medium emphasis
CompositionLocalProvider(LocalContentAlpha provides ContentAlpha.medium) {
    Icon(…)
}
// Disabled emphasis
CompositionLocalProvider(LocalContentAlpha provides ContentAlpha.disabled) {
    Icon(…)
}

import androidx.compose.material3.LocalContentColor

// High emphasis
CompositionLocalProvider(LocalContentColor provides MaterialTheme.colorScheme.onSurface) {
    Icon(…)
}
// Medium emphasis
CompositionLocalProvider(LocalContentColor provides MaterialTheme.colorScheme.onSurfaceVariant) {
    Icon(…)
}
// Disabled emphasis
CompositionLocalProvider(LocalContentColor provides MaterialTheme.colorScheme.onSurface.copy(alpha = 0.38f)) {
    Icon(…)
}

M2 と M3 のテキストの強調の例を次に示します。

import androidx.compose.material.ContentAlpha
import androidx.compose.material.LocalContentAlpha

// High emphasis
CompositionLocalProvider(LocalContentAlpha provides ContentAlpha.high) {
    Text(…)
}
// Medium emphasis
CompositionLocalProvider(LocalContentAlpha provides ContentAlpha.medium) {
    Text(…)
}
// Disabled emphasis
CompositionLocalProvider(LocalContentAlpha provides ContentAlpha.disabled) {
    Text(…)
}

import androidx.compose.material3.LocalContentColor

// High emphasis
Text(
    …,
    fontWeight = FontWeight.Bold
)
// Medium emphasis
Text(
    …,
    fontWeight = FontWeight.Normal
)
// Disabled emphasis
CompositionLocalProvider(LocalContentColor provides MaterialTheme.colorScheme.onSurface.copy(alpha = 0.38f)) {
    Text(
        …,
        fontWeight = FontWeight.Normal
    )
}

背景とコンテナ

M2 の背景は、M3 ではコンテナという名前になりました。一般的には、M2 の background* パラメータを M3 の container* に置き換えて、同じ値を使用することができます。次に例を示します。

Badge(
    backgroundColor = MaterialTheme.colors.primary
) { … }

Badge(
    containerColor = MaterialTheme.colorScheme.primary
) { … }

参考リンク

Compose における M2 から M3 への移行について詳しくは、以下の参考情報をご覧ください。

ドキュメント

• Compose のマテリアル デザイン 3

サンプルアプリ

• Reply M3 サンプルアプリ
• M2 から M3 への移行に関する Jetchat サンプルアプリ
  • 最初の alpha01 移行
  • フォローアップの alpha10 更新
• M2 から M3 への移行に関する Jetnews サンプルアプリ
• Now in Android M3 ヒーローアプリの :core-designsystem モジュール

動画

• Jetpack Compose を使用して Material You を実装する

API リファレンスとソースコード

• Compose Material 3 API リファレンス
• ソースコード内の Compose Material 3 サンプル