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 で提供されていない。下記のコンポーネントとレイアウト セクションを参照 段階的な移行を開始
デベロッパーまたはデザインチームがアプリのデザイン システムをまだ M2 から M3 に移行していない デザイン システムを M2 から M3 に移行した後で段階的な移行を開始

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

段階的なアプローチ

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

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

依存関係

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

M2

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

M3

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

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

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

ライブラリ パッケージとバージョン
Compose マテリアル アイコン androidx.compose.material:material-icons-*:$m2-version
Compose マテリアル リップル androidx.compose.material:material-ripple:$m2-version
Compose Material 3 のウィンドウ サイズ クラス androidx.compose.material3:material3-window-size-class:$m3-version

試験運用版 API

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

import androidx.compose.material3.ExperimentalMaterial3Api

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

テーマ設定

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

M2

import androidx.compose.material.MaterialTheme

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

M3

import androidx.compose.material3.MaterialTheme

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

カラー

M2 と M3 のカラーシステムの比較
図 1: M2 のカラーシステム(左)と M3 のカラーシステム(右)

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

M2

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
}

M3

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 カラーパターンで使用される色調パレットに拡張します。出発点として、次のマッピングを使用することをおすすめします。

M2 マテリアル テーマビルダー
primary Primary
primaryVariant Secondary
secondary Tertiary
surface または background Neutral
マテリアル テーマビルダーで M3 カラーパターンを生成するために使用される M2 カラー
図 2: マテリアル テーマビルダーで M3 カラーパターンを生成するために使用される Jetchat の M2 カラー

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

isLight

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

M2

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
        …
    }
}

M3

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 以降のデバイスの壁紙の色を利用できます。

タイポグラフィ

M2 と M3 のタイポグラフィ システムの比較
図 3: M2 のタイポグラフィ システム(左)と M3 のタイポグラフィ システム(右)

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

M2

import androidx.compose.material.Typography

val AppTypography = Typography(
    // M2 TextStyle parameters
)

M3

import androidx.compose.material3.Typography

val AppTypography = Typography(
    // M3 TextStyle parameters
)

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

M2 M3
h1 displayLarge
h2 displayMedium
h3 displaySmall
該当なし headlineLarge
h4 headlineMedium
h5 headlineSmall
h6 titleLarge
subtitle1 titleMedium
subtitle2 titleSmall
body1 bodyLarge
body2 bodyMedium
caption bodySmall
button labelLarge
該当なし labelMedium
overline labelSmall

シェイプ

M2 と M3 のシェイプ システムの比較
図 4: M2 のシェイプ システム(左)と M3 のシェイプ システム(右)

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

M2

import androidx.compose.material.Shapes

val AppShapes = Shapes(
    // M2 Shape parameters
)

M3

import androidx.compose.material3.Shapes

val AppShapes = Shapes(
    // M3 Shape parameters
)

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

M2 M3
該当なし extraSmall
small small
medium medium
large large
該当なし extraLarge

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

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

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

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

欠落している API:

M2 M3
androidx.compose.material.BackdropScaffold まだ提供されていません
androidx.compose.material.BottomDrawer M3 に同等の API はありません。提供されたらボトムシートに移行してください
androidx.compose.material.BottomSheetScaffold まだ提供されていません
androidx.compose.material.ModalBottomSheetLayout まだ提供されていません
androidx.compose.material.swipeable まだ提供されていません

名前が変更された API:

M2 M3
androidx.compose.material.BottomNavigation androidx.compose.material3.NavigationBar
androidx.compose.material.BottomNavigationItem androidx.compose.material3.NavigationBarItem
androidx.compose.material.Chip androidx.compose.material3.AssistChip または androidx.compose.material3.SuggestionChip
androidx.compose.material.ModalDrawer androidx.compose.material3.ModalNavigationDrawer

その他のすべての API:

M2 M3
androidx.compose.material.AlertDialog androidx.compose.material3.AlertDialog
androidx.compose.material.Badge androidx.compose.material3.Badge
androidx.compose.material.BadgedBox androidx.compose.material3.BadgedBox
androidx.compose.material.BottomAppBar androidx.compose.material3.BottomAppBar
androidx.compose.material.Button androidx.compose.material3.Button
androidx.compose.material.Card androidx.compose.material3.Card
androidx.compose.material.Checkbox androidx.compose.material3.Checkbox
androidx.compose.material.CircularProgressIndicator androidx.compose.material3.CircularProgressIndicator
androidx.compose.material.Divider androidx.compose.material3.Divider
androidx.compose.material.DropdownMenu androidx.compose.material3.DropdownMenu
androidx.compose.material.DropdownMenuItem androidx.compose.material3.DropdownMenuItem
androidx.compose.material.ExposedDropdownMenuBox androidx.compose.material3.ExposedDropdownMenuBox
androidx.compose.material.ExtendedFloatingActionButton androidx.compose.material3.ExtendedFloatingActionButton
androidx.compose.material.FilterChip androidx.compose.material3.FilterChip
androidx.compose.material.FloatingActionButton androidx.compose.material3.FloatingActionButton
androidx.compose.material.Icon androidx.compose.material3.Icon
androidx.compose.material.IconButton androidx.compose.material3.IconButton
androidx.compose.material.IconToggleButton androidx.compose.material3.IconToggleButton
androidx.compose.material.LeadingIconTab androidx.compose.material3.LeadingIconTab
androidx.compose.material.LinearProgressIndicator androidx.compose.material3.LinearProgressIndicator
androidx.compose.material.ListItem androidx.compose.material3.ListItem
androidx.compose.material.NavigationRail androidx.compose.material3.NavigationRail
androidx.compose.material.NavigationRailItem androidx.compose.material3.NavigationRailItem
androidx.compose.material.OutlinedButton androidx.compose.material3.OutlinedButton
androidx.compose.material.OutlinedTextField androidx.compose.material3.OutlinedTextField
androidx.compose.material.RadioButton androidx.compose.material3.RadioButton
androidx.compose.material.RangeSlider androidx.compose.material3.RangeSlider
androidx.compose.material.Scaffold androidx.compose.material3.Scaffold
androidx.compose.material.ScrollableTabRow androidx.compose.material3.ScrollableTabRow
androidx.compose.material.Slider androidx.compose.material3.Slider
androidx.compose.material.Snackbar androidx.compose.material3.Snackbar
androidx.compose.material.Switch androidx.compose.material3.Switch
androidx.compose.material.Tab androidx.compose.material3.Tab
androidx.compose.material.TabRow androidx.compose.material3.TabRow
androidx.compose.material.Text androidx.compose.material3.Text
androidx.compose.material.TextButton androidx.compose.material3.TextButton
androidx.compose.material.TextField androidx.compose.material3.TextField
androidx.compose.material.TopAppBar androidx.compose.material3.TopAppBar
androidx.compose.material.TriStateCheckbox androidx.compose.material3.TriStateCheckbox

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

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

スナックバーとナビゲーション ドロワーを備えた M2 と M3 のスキャフォールドの比較
図 5: スナックバーとナビゲーション ドロワーを備えた M2 のスキャフォールド(左)と、スナックバーとナビゲーション ドロワーを備えた M3 のスキャフォールド(右)

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

M2

import androidx.compose.material.Scaffold

Scaffold(
    // M2 scaffold parameters
)

M3

import androidx.compose.material3.Scaffold

Scaffold(
    // M3 scaffold parameters
)

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

M2

import androidx.compose.material.Scaffold

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

M3

import androidx.compose.material3.Scaffold

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

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

M2

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(…)
        }
    }
)

M3

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 における Scaffolddrawer* パラメータは、M3 ではすべて Scaffold から削除されました。これには、drawerShapedrawerContent などのパラメータが含まれます。M3 のスキャフォールドでドロワーを表示するには、代わりに ModalNavigationDrawer などのナビゲーション ドロワー コンポーザブルを使用します。

M2

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()
        }
    }
)

M3

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()
                }
            }
        )
    }
)

トップ アプリバー

トップ アプリバーとスクロール リストを備えた M2 と M3 のスキャフォールドの比較
図 6: トップ アプリバーとスクロール リストを備えた M2 のスキャフォールド(左)と、トップ アプリバーとスクロール リストを備えた M3 のスキャフォールド(右)

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

M2

import androidx.compose.material.TopAppBar

TopAppBar(…)

M3

import androidx.compose.material3.TopAppBar

TopAppBar(…)

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

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

M2

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) { … }
    }
)

M3

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 のナビゲーション バーの比較
図 7: M2 のボトム ナビゲーション(左)と M3 のナビゲーション バー(右)

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

M2

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

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

M3

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

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

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

M2 と M3 のボタンの比較
図 8: M2 のボタン(左)と M3 のボタン(右)

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

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(…)

M3

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 リファレンスの概要でご確認ください。

スイッチ

M2 と M3 のスイッチの比較
図 9: M2 のスイッチ(左)と M3 のスイッチ(右)

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

M2

import androidx.compose.material.Switch

Switch(…)

M3

import androidx.compose.material3.Switch

Switch(…)

サーフェスと高度

ライトテーマとダークテーマでの M2 のサーフェス高度と M3 のサーフェス高度の比較
図 10: ライトテーマでの M2 のサーフェス高度(左)とダークテーマでの M3 のサーフェス高度(右)

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

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

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

M2

import androidx.compose.material.Surface

Surface(
    elevation = …
) { … }

M3

import androidx.compose.material3.Surface

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

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

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

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

M2 と M3 のアイコンとテキストの強調の比較
図 11: M2 のアイコンとテキストの強調(左)と M3 のアイコンとテキストの強調(右)

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

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

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

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

M2 M3
ContentAlpha.high を持つ onSurface 一般的には onSurface、テキストでは FontWeight.Medium - FontWeight.Black
ContentAlpha.medium を持つ onSurface 一般的には onSurfaceVariant、テキストでは FontWeight.Thin - FontWeight.Normal
ContentAlpha.disabled を持つ onSurface onSurface.copy(alpha = 0.38f)

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

M2

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(…)
}

M3

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 のテキストの強調の例を次に示します。

M2

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(…)
}

M3

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* に置き換えて、同じ値を使用することができます。次に例を示します。

M2

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

M3

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

ビューの相互運用性

アプリにビューまたは XML の相互運用性があり、MDC-Android Compose Theme Adapter ライブラリを使用している場合は、M3 バージョンを使用する必要があります。

M2

implementation "com.google.android.material:compose-theme-adapter:$compose-theme-adapter-version"

M3

implementation "com.google.android.material:compose-theme-adapter-3:$compose-theme-adapter-3-version"

最新バージョンについては、MDC-Android Compose Theme Adapter リリースページをご覧ください。

M2 バージョンと M3 バージョンの主な違いは、MdcTheme コンポーザブルが Mdc3Theme コンポーザブルになったことです。

M2

import com.google.android.material.composethemeadapter.MdcTheme

MdcTheme {
    // M2 content
}

M3

import com.google.android.material.composethemeadapter3.Mdc3Theme

Mdc3Theme {
    // M3 content
}

詳しくは、README をご覧ください。

ビューでマテリアル 2 からマテリアル 3 に移行する方法については、マテリアル デザイン 3 への移行のガイドをご覧ください。

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

ドキュメント

サンプルアプリ

動画

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