Bermigrasi dari Material 2 ke Material 3 di Compose

Desain Material 3 adalah evolusi berikutnya dari Desain Material. Desain Material ini mencakup versi terbaru tema, komponen, dan fitur personalisasi Material You seperti warna dinamis. Ini adalah update dari Desain Material 2 dan terkait erat dengan gaya visual dan UI sistem baru di Android 12 dan yang lebih baru.

Panduan ini berfokus pada migrasi dari library Jetpack Compose Material (androidx.compose.material) ke library Jetpack Compose Material 3 (androidx.compose.material3).

Pendekatan

Secara umum, Anda tidak boleh menggunakan M2 dan M3 dalam satu aplikasi jangka panjang. Hal ini karena kedua sistem desain dan library masing-masing sangat berbeda dalam hal desain UX/UI dan implementasi Compose-nya.

Aplikasi Anda mungkin menggunakan sistem desain, seperti yang dibuat menggunakan Figma. Jika demikian, kami sangat menyarankan Anda atau tim desain Anda untuk memigrasikannya dari M2 ke M3 sebelum memulai migrasi Compose. Sangat tidak umum jika migrasi aplikasi ke M3 saat desain UX/UI-nya didasarkan pada M2.

Selain itu, pendekatan Anda terhadap migrasi harus berbeda bergantung pada ukuran, kompleksitas, dan desain UX/UI aplikasi. Dengan begitu, Anda dapat meminimalkan dampak terhadap codebase. Anda harus menggunakan pendekatan bertahap untuk migrasi.

Waktu bermigrasi

Anda harus memulai migrasi sesegera mungkin. Namun, penting untuk mempertimbangkan apakah aplikasi Anda berada di posisi realistis untuk sepenuhnya bermigrasi dari M2 ke M3. Ada beberapa skenario “pemblokir” yang perlu dipertimbangkan sebelum memulai:

Meskipun terpengaruh oleh skenario di atas, Anda harus melakukan pendekatan bertahap untuk migrasi sebelum melakukan dan merilis update aplikasi. Dalam hal ini, Anda akan menggunakan M2 dan M3 secara berdampingan, dan secara bertahap menghentikan M2 saat bermigrasi ke M3.

Pendekatan bertahap

Langkah-langkah umum untuk migrasi bertahap adalah sebagai berikut:

1. Tambahkan dependensi M3 bersama dependensi M2.
2. Tambahkan versi M3 tema aplikasi Anda bersama versi M2 tema aplikasi.
3. Migrasikan setiap modul, layar, atau composable ke M3, bergantung pada ukuran dan kompleksitas aplikasi Anda (lihat bagian di bawah untuk detailnya).
4. Setelah dimigrasikan sepenuhnya, hapus versi M2 tema aplikasi Anda.
5. Hapus dependensi M2.

Dependensi

M3 memiliki paket dan versi terpisah untuk M2:

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

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

Lihat versi M3 terbaru di halaman rilis Compose Material 3.

Dependensi Material lainnya di luar library M2 dan M3 utama tidak berubah. Dependensi tersebut menggunakan kombinasi paket dan versi M2 dan M3, tetapi hal ini tidak memengaruhi migrasi. Dependensi dapat digunakan begitu saja dengan M3:

API Eksperimental

Beberapa API M3 dianggap eksperimental. Dalam hal ini, Anda harus memilih untuk mengaktifkan fungsi atau level file menggunakan anotasi ExperimentalMaterial3Api:

import androidx.compose.material3.ExperimentalMaterial3Api

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

Tema

Pada M2 dan M3, composable tema diberi nama MaterialTheme, tetapi paket dan parameter impornya berbeda:

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
}

Warna

Sistem warna di M3 sangat berbeda dengan M2. Jumlah parameter warna telah meningkat, memiliki nama berbeda, dan memetakan secara berbeda ke komponen M3. Di Compose, ini berlaku untuk class Colors M2, class ColorScheme M3, dan fungsi terkait:

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
}

Mengingat perbedaan yang signifikan antara sistem warna M2 dan M3, tidak ada pemetaan yang wajar untuk parameter Color. Sebagai gantinya, gunakan alat Builder Tema Material untuk membuat skema warna M3. Gunakan warna M2 sebagai warna sumber “inti” pada alat, yang diperluas alat ini ke palet warna yang digunakan oleh skema warna M3. Pemetaan berikut direkomendasikan sebagai titik awal:

Anda dapat menyalin nilai kode heksadesimal warna untuk tema terang dan gelap dari alat ini dan menggunakannya untuk menerapkan instance ColorScheme M3. Atau, Material Theme Builder dapat mengekspor kode Compose.

isLight

Tidak seperti class Colors M2, class ColorScheme M3 tidak menyertakan parameter isLight. Secara umum, Anda harus mencoba membuat model apa pun yang memerlukan informasi ini di level tema. Contoh:

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

Lihat panduan Sistem desain kustom di Compose untuk informasi selengkapnya.

Warna dinamis

Fitur baru di M3 adalah warna dinamis. Daripada menggunakan warna kustom, ColorScheme M3 dapat menggunakan warna wallpaper perangkat di Android 12 dan yang lebih baru, menggunakan fungsi berikut:

• dynamicLightColorScheme
• dynamicDarkColorScheme

Tipografi

Sistem tipografi di M3 berbeda dengan M2. Jumlah parameter tipografi kurang lebih sama, tetapi memiliki nama dan pemetaan yang berbeda untuk komponen M3. Di Compose, ini berlaku untuk class Typography M2 dan class Typography M3:

import androidx.compose.material.Typography

val AppTypography = Typography(
    // M2 TextStyle parameters
)

import androidx.compose.material3.Typography

val AppTypography = Typography(
    // M3 TextStyle parameters
)

Pemetaan parameter TextStyle berikut direkomendasikan sebagai titik awal:

Bentuk

Sistem bentuk di M3 berbeda dengan M2. Jumlah parameter bentuk telah meningkat, diberi nama berbeda dan dipetakan berbeda ke komponen M3. Di Compose, ini berlaku untuk class Shapes M2 dan class Shapes M3:

import androidx.compose.material.Shapes

val AppShapes = Shapes(
    // M2 Shape parameters
)

import androidx.compose.material3.Shapes

val AppShapes = Shapes(
    // M3 Shape parameters
)

Pemetaan parameter Shape berikut direkomendasikan sebagai titik awal:

Komponen dan tata letak

Sebagian besar komponen dan tata letak dari M2 tersedia di M3. Namun, ada beberapa yang hilang serta yang baru dan tidak ada di M2. Selain itu, beberapa komponen M3 memiliki lebih banyak variasi dibandingkan dengan yang setara di M2. Secara umum, antarmuka API M3 berupaya semirip mungkin dengan persamaan terdekatnya di M2.

Dengan sistem warna, tipografi, dan bentuk terbaru, komponen M3 cenderung dipetakan secara berbeda ke nilai tema baru. Sebaiknya lihat direktori token di kode sumber Compose Material 3 sebagai sumber kebenaran untuk pemetaan ini.

Meskipun beberapa komponen memerlukan pertimbangan khusus, pemetaan fungsi berikut direkomendasikan sebagai titik awal:

API tidak ada:

API yang Diganti:

API yang berganti nama:

Semua API lainnya:

Lihat komponen dan tata letak M3 terbaru di ringkasan Referensi API Compose Material 3, dan pantau terus halaman rilis untuk API baru dan yang diupdate.

Scaffold, snackbar, dan panel navigasi

Scaffold di M3 berbeda dengan M2. Pada M2 dan M3, composable tata letak utama bernama Scaffold, tetapi paket dan parameter impor berbeda:

import androidx.compose.material.Scaffold

Scaffold(
    // M2 scaffold parameters
)

import androidx.compose.material3.Scaffold

Scaffold(
    // M3 scaffold parameters
)

Scaffold M2 yang berisi parameter backgroundColor kini diberi nama containerColor di Scaffold M3:

import androidx.compose.material.Scaffold

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

import androidx.compose.material3.Scaffold

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

Class ScaffoldState M2 tidak ada lagi di M3 karena berisi parameter drawerState yang tidak diperlukan lagi. Untuk menampilkan snackbar dengan Scaffold M3, gunakan 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(…)
        }
    }
)

Semua parameter drawer* dari Scaffold M2 telah dihapus dari Scaffold M3. Hal ini mencakup parameter seperti drawerShape dan drawerContent. Untuk menampilkan panel samping dengan Scaffold M3, gunakan composable panel navigasi, seperti ModalNavigationDrawer, sebagai gantinya:

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

Panel aplikasi atas

Panel aplikasi atas di M3 berbeda dengan yang ada di M2. Dalam M2 dan M3, composable panel aplikasi atas utama diberi nama TopAppBar, tetapi paket dan parameter impornya berbeda:

import androidx.compose.material.TopAppBar

TopAppBar(…)

import androidx.compose.material3.TopAppBar

TopAppBar(…)

Sebaiknya gunakan CenterAlignedTopAppBar M3 jika sebelumnya Anda meletakkan konten di tengah-tengah TopAppBar M2. Sebaiknya Anda juga mengetahui MediumTopAppBar dan LargeTopAppBar.

Panel aplikasi atas M3 berisi parameter scrollBehavior baru untuk memberikan fungsi yang berbeda saat men-scroll melalui class TopAppBarScrollBehavior, seperti perubahan elevasi. Hal ini berfungsi bersama dengan konten scroll melalui Modifer.nestedScroll. Hal ini dapat dilakukan dalam TopAppBar M2 dengan mengubah parameter elevation secara manual:

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

Navigasi bawah/Menu navigasi

Navigasi bawah di M2 telah diganti namanya menjadi menu navigasi di M3. Di M2 terdapat composable BottomNavigation dan BottomNavigationItem, sedangkan di M3 terdapat composable NavigationBar dan 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(…)
}

Tombol, tombol ikon, dan FAB

Tombol, tombol ikon, dan tombol tindakan mengambang (FAB) di M3 berbeda dengan yang ada di M2. M3 mencakup semua composable tombol 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 juga menyertakan variasi tombol baru. Lihat di ringkasan Referensi API Compose Material 3.

Tombol alih

Tombol alih di M3 berbeda dengan M2. Pada M2 dan M3, composable tombol alih diberi nama Switch, tetapi paket impornya berbeda:

import androidx.compose.material.Switch

Switch(…)

import androidx.compose.material3.Switch

Switch(…)

Permukaan dan elevasi

Sistem permukaan dan elevasi di M3 berbeda dengan M2. Ada dua jenis elevasi di M3:

• Elevasi bayangan (menambahkan bayangan, sama seperti di M2)
• Elevasi warna (mengubah warnanya, baru di M3)

Di Compose, ini berlaku untuk fungsi Surface M2 dan fungsi Surface M3:

import androidx.compose.material.Surface

Surface(
    elevation = …
) { … }

import androidx.compose.material3.Surface

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

Anda dapat menggunakan nilai Dp elevation di M2 untuk shadowElevation dan/atau tonalElevation di M3, bergantung pada preferensi desain UX/UI. Surface adalah composable pendukung di balik sebagian besar komponen, sehingga composable komponen juga dapat menampilkan parameter elevasi yang harus Anda migrasikan dengan cara yang sama.

Elevasi warna di M3 menggantikan konsep overlay elevasi di tema gelap M2. Akibatnya, ElevationOverlay dan LocalElevationOverlay tidak ada di M3 dan LocalAbsoluteElevation dalam M2 telah diubah menjadi LocalAbsoluteTonalElevation di M3.

Penekanan dan alfa konten

Penekanan di M3 berbeda secara signifikan dengan M2. Di M2, penekanan melibatkan penggunaan warna “aktif” dengan nilai alfa tertentu untuk membedakan konten seperti teks dan ikon. Di M3, kini ada beberapa pendekatan yang berbeda:

• Menggunakan warna “aktif” beserta warna “varian aktif” dari sistem warna M3 yang diperluas.
• Penggunaan ketebalan font yang berbeda untuk teks.

Akibatnya, ContentAlpha dan LocalContentAlpha tidak ada di M3 dan harus diganti.

Pemetaan berikut direkomendasikan sebagai titik awal:

Berikut adalah contoh penekanan ikon di M2 vs. 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(…)
}

Berikut adalah contoh penekanan teks di M2 vs. 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
    )
}

Latar belakang dan penampung

Latar belakang di M2 diberi nama “container” di M3. Secara umum, Anda dapat mengganti parameter background* di M2 dengan container* di M3, menggunakan nilai yang sama. Contoh:

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

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

Interoperabilitas Views

Jika aplikasi Anda menyertakan interoperabilitas Views atau XML dan menggunakan library MDC-Android Compose Theme Adapter, Anda harus menggunakan versi M3:

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

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

Lihat versi terbaru di halaman rilis MDC-Android Compose Theme Adapter.

Perbedaan utama antara versi M2 dan M3 adalah composable MdcTheme dan Mdc3Theme masing-masing:

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

MdcTheme {
    // M2 content
}

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

Mdc3Theme {
    // M3 content
}

Lihat README untuk informasi selengkapnya.

Lihat panduan Migrasi ke Desain Material 3 untuk mengetahui informasi selengkapnya tentang migrasi dari Material 2 ke Material 3 di Views.

Link penting

Untuk mempelajari migrasi dari M2 ke M3 di Compose lebih lanjut, lihat referensi tambahan berikut.

Dokumen

• Desain Material 3 di Compose

Aplikasi contoh

• Aplikasi contoh Reply M3
• Migrasi aplikasi contoh Jetchat M2 ke M3
  • Migrasi alpha01 awal
  • Menindaklanjuti update alpha10
• Migrasi aplikasi contoh Jetnews M2 ke M3
• Migrasi aplikasi contoh Jetsurvey M2 ke M3
• Modul :core-designsystem aplikasi hero Android M3 Now in Android

Video

• Mengimplementasikan Material You Menggunakan Jetpack Compose

Referensi API dan kode sumber

• Referensi API Compose Material 3
• Contoh Compose Material 3 dalam kode sumber