Oluşturma'da Materyal 2'den Materyal 3'e geçme

Materyal Tasarım 3, Materyal Tasarım'ın yeni evrimidir. Bu sürüm; güncellenmiş tema, bileşenler ve dinamik renk gibi Material You kişiselleştirme özelliklerini içerir. Bu, Materyal Tasarım 2'nin bir güncellemesidir ve Android 12 ve sonraki sürümlerin yeni görsel stil ve sistem kullanıcı arayüzüyle uyumludur.

Bu kılavuz, Compose Material (androidx.compose.material) Jetpack kitaplığından Compose Material 3 (androidx.compose.material3) Jetpack kitaplığına geçişe odaklanır.

Yaklaşımlar

Genel olarak tek bir uygulamada hem M2 hem de M3'ü uzun süre kullanmamalısınız. Bunun nedeni, iki tasarım sistemi ile ilgili kitaplığın UX/kullanıcı arayüzü tasarımları ve Compose uygulamaları açısından önemli ölçüde farklılık göstermesidir.

Uygulamanızda, Figma kullanılarak oluşturulan sistem gibi bir tasarım sistemi kullanılıyor olabilir. Bu tür durumlarda Compose taşıma işlemine başlamadan önce sizin veya tasarım ekibinizin M2'den M3'e taşımasını kesinlikle öneririz. Kullanıcı deneyimi/kullanıcı arayüzü tasarımı M2'ye dayanıyorsa bir uygulamayı M3'e taşımak mantıklı değildir.

Ayrıca, taşıma yaklaşımınız uygulamanızın boyutuna, karmaşıklığına ve kullanıcı arayüzü/kullanıcı arayüzü tasarımına bağlı olarak farklılık göstermelidir. Böylece kod tabanınız üzerindeki etkiyi en aza indirebilirsiniz. Taşıma için aşamalı bir yaklaşım benimsemelisiniz.

Taşıma zamanı

Taşıma işlemini en kısa sürede başlatmanız gerekir. Ancak uygulamanızın M2'den M3'e tamamen geçiş için gerçekçi bir konumda olup olmadığını göz önünde bulundurmak önemlidir. Başlamadan önce araştırabileceğiniz bazı "engelleyici" senaryolar vardır:

Senaryo Önerilen yaklaşım
“blocker” yok Aşamalı taşımaya başla
M2'deki bir bileşen henüz M3'te kullanılamaz. Aşağıdaki Bileşenler ve düzenler bölümüne bakın. Aşamalı taşımaya başla
Siz veya tasarım ekibiniz, uygulamanın tasarım sistemini M2'den M3'e taşımadınız. Tasarım sistemini M2'den M3'e taşıyın, ardından aşamalı taşımaya başlayın

Yukarıdaki senaryolardan etkilenmiş olsanız bile bir uygulama güncellemesi yapmadan ve yayınlamadan önce geçiş için aşamalı bir yaklaşım benimsemelisiniz. Bu tür durumlarda, M2 ile M3'ü yan yana kullanırsınız ve M3'e geçiş yaparken M2'yi aşamalı olarak kullanımdan kaldırırsınız.

Aşamalı yaklaşım

Aşamalı taşıma için uygulanması gereken genel adımlar şunlardır:

  1. M2 bağımlılığının yanı sıra M3 bağımlılığını ekleyin.
  2. Uygulamanızın temalarının M2 sürümlerini ve M2 sürümlerini ekleyin.
  3. Uygulamanızın boyutuna ve karmaşıklığına bağlı olarak modülleri, ekranları veya composable'ları M3'e tek tek taşıyın (ayrıntılar için aşağıdaki bölümlere bakın).
  4. Tamamen taşındıktan sonra, uygulama temalarınızın M2 sürümlerini kaldırın.
  5. M2 bağımlılığını kaldırın.

Bağımlılıklar

M3'ün ayrı bir paketi ve M2 sürümü vardır:

M2

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

M3

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

En son M3 sürümlerine Material Material 3 sürüm sayfasından göz atın.

Ana M2 ve M3 kitaplıklarının dışındaki diğer Materyal bağımlılıkları değişmedi. M2 ve M3 paketleri ve sürümlerinin bir karışımını kullanırlar ancak bu durumun taşımayı etkilemez. Bunlar M3 ile olduğu gibi kullanılabilir:

Kitaplık Paket ve sürüm
Materyal Simgeleri Oluşturma androidx.compose.material:material-icons-*:$m2-version
Materyal Dalgası Oluşturma androidx.compose.material:material-ripple:$m2-version
Compose Material 3 Pencere Boyutu Sınıfı androidx.compose.material3:material3-window-size-class:$m3-version

Deneysel API'ler

Bazı M3 API'ler deneysel olarak kabul edilir. Bu tür durumlarda, ExperimentalMaterial3Api ek açıklamasını kullanarak işlev veya dosya düzeyinde özelliği etkinleştirmeniz gerekir:

import androidx.compose.material3.ExperimentalMaterial3Api

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

Tema oluşturma

Hem M2 hem de M3'te, composable temanın adı MaterialTheme ancak içe aktarma paketleri ve parametreleri farklıdır:

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
}

Renk

M2-M3 renk sistemlerinin karşılaştırılması
Şekil 1. M2 renk sistemi (sol) ve M3 renk sistemi (sağ).

M3'teki renk sistemi, M2'den önemli ölçüde farklıdır. Renk parametrelerinin sayısı arttı, farklı isimlere sahipler ve M3 bileşenlerine farklı şekilde eşleniyorlar. Compose'da bu durum M2 Colors sınıfı, M3 ColorScheme sınıfı ve ilgili işlevler için geçerlidir:

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 ve M3 renk sistemleri arasındaki önemli farklar göz önünde bulundurulduğunda, Color parametreleri için makul bir eşleme yoktur. Bunun yerine, M3 renk şeması oluşturmak için Malzeme Tema Oluşturucu aracını kullanın. Araçta "temel" kaynak renkler olarak M2 renklerini kullanın. Araç, M3 renk şeması tarafından kullanılan ton paletlerine genişletilir. Başlangıç noktası olarak aşağıdaki eşlemeler önerilir:

M2 Malzeme Teması Oluşturucu
primary Birincil
primaryVariant İkincil
secondary Üçüncül
surface veya background Normal
Malzeme Tema Oluşturucu'da M3 renk şeması oluşturmak için M2 renkleri kullanılır
Şekil 2. Jetchat'in M2 renkleri, M3 renk şeması oluşturmak için Materyal Tema Oluşturucu'da kullanıldı.

Araçtan açık ve koyu temalar için rengin onaltılık kod değerlerini kopyalayabilir ve bir M3 ColorScheme örneği uygulamak için kullanabilirsiniz. Alternatif olarak, Materyal Tema Oluşturucu Oluştur kodunu dışa aktarabilir.

isLight

M2 Colors sınıfından farklı olarak M3 ColorScheme sınıfı bir isLight parametresi içermez. Genel olarak, bu bilgiye ihtiyaç duyan her şeyi tema düzeyinde modellemeye çalışmalısınız. Örnek:

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

Daha fazla bilgi için Oluşturma kılavuzundaki özel tasarım sistemlerine bakın.

Dinamik renk

M3'teki yeni bir özellik de dinamik renktir. M3 ColorScheme, Android 12 ve sonraki sürümlerde özel renkler yerine aşağıdaki işlevleri kullanarak cihazın duvar kağıdı renklerini kullanabilir:

Yazı biçimi

M2 ve M3 tipografi sistemlerinin karşılaştırılması
Şekil 3. M3 tipografi sistemi (sol) ve M2 tipografi sistemi (sağ) karşılaştırması

M3'teki yazım sistemi M2'den farklıdır. Tipografi parametrelerinin sayısı aşağı yukarı aynıdır, ancak farklı adları vardır ve M3 bileşenleriyle farklı şekilde eşlenirler. Compose'da bu durum M2 Typography sınıfı ve M3 Typography sınıfı için geçerlidir:

M2

import androidx.compose.material.Typography

val AppTypography = Typography(
    // M2 TextStyle parameters
)

M3

import androidx.compose.material3.Typography

val AppTypography = Typography(
    // M3 TextStyle parameters
)

Başlangıç noktası olarak aşağıdaki TextStyle parametre eşlemeleri önerilir:

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

Şekil

M2 ve M3 şekil sistemlerinin karşılaştırılması
Şekil 4. M2 şekil sistemi (sol) - M3 şekil sistemi (sağ)

M3'teki şekil sistemi M2'den farklıdır. Şekil parametrelerinin sayısı arttı, farklı şekilde adlandırıldılar ve M3 bileşenleriyle farklı şekilde eşlenirler. Compose'da bu durum M2 Shapes sınıfı ve M3 Shapes sınıfı için geçerlidir:

M2

import androidx.compose.material.Shapes

val AppShapes = Shapes(
    // M2 Shape parameters
)

M3

import androidx.compose.material3.Shapes

val AppShapes = Shapes(
    // M3 Shape parameters
)

Başlangıç noktası olarak aşağıdaki Shape parametre eşlemeleri önerilir:

M2 M3
Yok extraSmall
small small
medium medium
large large
Yok extraLarge

Bileşenler ve düzenler

M2'deki çoğu bileşen ve düzen M3'te mevcuttur. Ancak bazıları eksik olduğu gibi M2'de bulunmayan yenileri de var. Dahası, bazı M3 bileşenlerinin M2'deki eşdeğerlerinden daha fazla varyasyonu vardır. Genel olarak M3 API yüzeyleri, M2'deki en yakın eşdeğerlerine mümkün olduğunca benzer olmaya çalışır.

Güncellenen renk, tipografi ve şekil sistemleri göz önünde bulundurulduğunda, M3 bileşenleri yeni tema değerleriyle farklı şekilde eşlenir. Bu eşlemeler için veri kaynağı olarak Compose Material 3 kaynak kodunda jetonlar dizinine göz atmak iyi bir fikirdir.

Bazı bileşenler için özel durumlar gerekse de başlangıç noktası olarak aşağıdaki işlev eşlemeleri önerilir:

Eksik API'ler:

M2 M3
androidx.compose.material.swipeable Henüz kullanılamıyor

Değiştirilen API'ler:

M2 M3
androidx.compose.material.BackdropScaffold M3 eşdeğeri yok. Bunun yerine Scaffold veya BottomSheetScaffold'e geçiş yapın
androidx.compose.material.BottomDrawer M3 eşdeğeri yok, bunun yerine ModalBottomSheet sürümüne geçin

Yeniden adlandırılmış API'ler:

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 veya androidx.compose.material3.SuggestionChip
androidx.compose.material.ModalBottomSheetLayout androidx.compose.material3.ModalBottomSheet
androidx.compose.material.ModalDrawer androidx.compose.material3.ModalNavigationDrawer

Diğer tüm API'ler:

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.BottomSheetScaffold androidx.compose.material3.BottomSheetScaffold
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

Compose Material 3 API referansına genel bakış bölümünde en yeni M3 bileşenleri ve düzenlerini inceleyin. Ayrıca yeni ve güncellenmiş API'ler için sürümler sayfasını da takip edin.

İskele, atıştırmalık çubukları ve gezinme çekmecesi

Snackbar ve gezinme çekmecesi ile M2 ve M3 iskelelerinin karşılaştırması
Şekil 5. Snackbar ve gezinme çekmecesi (solda) bulunan M2 iskelesi, atıştırma çubuğu ve gezinme çekmecesi (sağda) bulunan M3 iskelesi.

M3'teki iskele, M2'den farklıdır. Hem M2 hem de M3'te, composable ana düzenin adı Scaffold olsa da içe aktarma paketleri ve parametreleri farklıdır:

M2

import androidx.compose.material.Scaffold

Scaffold(
    // M2 scaffold parameters
)

M3

import androidx.compose.material3.Scaffold

Scaffold(
    // M3 scaffold parameters
)

M2 Scaffold, M3'te artık containerColor olarak adlandırılan bir backgroundColor parametresi içeriyor Scaffold:

M2

import androidx.compose.material.Scaffold

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

M3

import androidx.compose.material3.Scaffold

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

Artık ihtiyaç duyulmayan bir drawerState parametresi içerdiği için M2 ScaffoldState sınıfı M3'te mevcut değildir. M3 Scaffold ile atıştırmalık çubuklarını göstermek için bunun yerine SnackbarHostState işlevini kullanın:

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 Scaffold içindeki tüm drawer* parametreleri, Scaffold M3'ten kaldırıldı. Bunlara drawerShape ve drawerContent gibi parametreler dahildir. M3 Scaffold ile bir çekmeceyi göstermek için, bunun yerine ModalNavigationDrawer gibi bir gezinme çekmecesi oluşturun:

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

Üst uygulama çubuğu

Üst uygulama çubuğu ve kaydırılmış liste ile M2 ve M3 iskelelerinin karşılaştırması
Şekil 6. Üst uygulama çubuğu ve kaydırılmış liste (solda) bulunan M2 iskelesi, üst uygulama çubuğu ve kaydırılmış liste (sağda) içeren M3 iskelesi

M3'teki en popüler uygulama çubukları, M2'dekilerden farklıdır. Hem M2 hem de M3'te, composable ana üst uygulama çubuğu TopAppBar olarak adlandırılır ancak içe aktarma paketleri ve parametreleri farklıdır:

M2

import androidx.compose.material.TopAppBar

TopAppBar(…)

M3

import androidx.compose.material3.TopAppBar

TopAppBar(…)

Önceden içeriği M2 TopAppBar içerisinde ortaladıysanız M3 CenterAlignedTopAppBar kullanmayı düşünebilirsiniz. MediumTopAppBar ve LargeTopAppBar hakkında bilgi sahibi olmakta fayda vardır.

M3 üst uygulama çubukları, TopAppBarScrollBehavior sınıfında ilerlemeyi değiştirme gibi farklı işlevler sunmak için yeni bir scrollBehavior parametresi içeriyor. Bu, Modifer.nestedScroll üzerinden kaydırma içeriği ile birlikte çalışır. Bu, TopAppBar M2'sinde elevation parametresini manuel olarak değiştirerek mümkündü:

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

Alt gezinme / Gezinme çubuğu

M2 alt gezinme çubuğu ile M3 gezinme çubuğunun karşılaştırması
Şekil 7. M2 alt gezinme çubuğu (sol) ile M3 gezinme çubuğu (sağ) karşılaştırması.

M2'de alt gezinme, M3'te gezinme çubuğu olarak yeniden adlandırıldı. M2'de BottomNavigation ve BottomNavigationItem composable'ları, M2'de ise NavigationBar ve NavigationBarItem composable'ları vardır:

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

Düğmeler, simge düğmeleri ve FAB'lar

M2 ve M3 düğmelerinin karşılaştırması
Şekil 8. M2 düğmeleri (sol) ve M3 düğmeleri (sağ) karşılaştırması

M3'teki düğmeler, simge düğmeleri ve kayan işlem düğmeleri (FAB'lar) M2'dekilerden farklıdır. M3, tüm M2 düğmesi composable'larını içerir:

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'te yeni düğme varyasyonları da bulunur. Bunları Compose Material 3 API referansına genel bakış bölümünde inceleyin.

Switch

M2 ve M3 anahtarlarının karşılaştırılması
Şekil 9. M2 anahtarı (sol) ve M3 anahtarı (sağ).

M3'teki anahtar, M2'den farklıdır. Hem M2 hem de M3'te, composable'ın adı Switch olsa da içe aktarma paketleri farklıdır:

M2

import androidx.compose.material.Switch

Switch(…)

M3

import androidx.compose.material3.Switch

Switch(…)

Yüzeyler ve yükseklik

Açık ve koyu temalarda M2 yüzey yüksekliği ile M3 yüzey yüksekliğinin karşılaştırılması
Şekil 10. Açık temada (sol) ve koyu temada (sağ) M2 yüzey yüksekliği ile M3 yüzey yüksekliği karşılaştırması.

M3'teki yüzey ve yükseklik sistemleri M2'den farklıdır. M3'te iki tür rakım bulunur:

  • Gölge yüksekliği (M2'ye benzer şekilde gölge oluşturur)
  • Ton yüksekliği (M3'te yeni bir renkle yer paylaşımlıdır)

Compose'da bu durum M2 Surface işlevi ve M3 Surface işlevi için geçerlidir:

M2

import androidx.compose.material.Surface

Surface(
    elevation = …
) { … }

M3

import androidx.compose.material3.Surface

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

Kullanıcı deneyimi/kullanıcı arayüzü tasarım tercihine bağlı olarak M2'de elevation Dp değerlerini M3'te hem shadowElevation hem de tonalElevation için kullanabilirsiniz. Surface, çoğu bileşenin arka planında bulunan composable'dır. Bu nedenle bileşen composable, aynı şekilde taşımanız gereken yükseklik parametrelerini de ortaya çıkarabilir.

M3'te ton yükselmesi, M2 koyu temadaki yükseklik katmanları kavramının yerini almıştır . Sonuç olarak, ElevationOverlay ve LocalElevationOverlay M3'te mevcut değil. M2'de LocalAbsoluteElevation ise M3'te LocalAbsoluteTonalElevation olarak değiştirildi.

Vurgu ve içerik alfa

M2 ve M3 simgesi ile metin vurgularının karşılaştırması
Şekil 11. M2 simgesi ve metin vurgusu (solda) ile M3 simgesi ve metin vurgusu (sağda) karşılaştırması (sağ)

M3'teki vurgu, M2'den önemli ölçüde farklıdır. M2'de metin ve simgeler gibi içerikleri ayırt etmek için belirli alfa değerleriyle "açık" renklerinin kullanılması ön plana çıkar. M3'te artık birkaç farklı yaklaşım vardır:

  • Genişletilmiş M3 renk sistemindeki "açık" renkleriyle "varyant açık" renklerinin kullanılması.
  • Metin için farklı yazı tipi ağırlıkları kullanma.

Sonuç olarak ContentAlpha ve LocalContentAlpha M3'te mevcut değildir ve değiştirilmeleri gerekir.

Başlangıç noktası olarak aşağıdaki eşlemeler önerilir:

M2 M3
ContentAlpha.high ile onSurface Genel olarak onSurface, metin için FontWeight.Medium - FontWeight.Black
ContentAlpha.medium ile onSurface Genel olarak onSurfaceVariant, metin için FontWeight.Thin - FontWeight.Normal
ContentAlpha.disabled ile onSurface onSurface.copy(alpha = 0.38f)

M2 ve M3'te simge vurgusuna ilişkin bir örneği burada görebilirsiniz:

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 ve M3'te metin vurgusuyla ilgili bir örnek aşağıda verilmiştir:

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

Arka planlar ve kapsayıcılar

M2'deki arka planlar M3'te "kaplar" olarak adlandırılır. Genel olarak, M2'de background* parametrelerini M3'te container* ile değiştirmek için aynı değerleri kullanabilirsiniz. Örnek:

M2

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

M3

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

Görünümlerle birlikte çalışabilirlik

Uygulamanızda Görünümler veya XML birlikte çalışabilirliği özelliği varsa ve MDC-Android Tema Bağdaştırıcısı kitaplığını kullanıyorsa M3 sürümünü kullanmanız gerekir:

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 Tema Bağdaştırıcısı sürümleri sayfasında en son sürümlere bakın.

M2 ve M3 sürümleri arasındaki en önemli fark, ilgili MdcTheme ve Mdc3Theme composable'larıdır:

M2

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

MdcTheme {
    // M2 content
}

M3

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

Mdc3Theme {
    // M3 content
}

Daha fazla bilgi için BENİOKU sayfasına göz atın.

Görünümler'de Materyal 2'den Materyal 3'e geçiş hakkında daha fazla bilgi için Materyal Tasarım 3'e Geçiş Kılavuzu'na bakın.

Compose'da M2'den M3'e taşıma hakkında daha fazla bilgi edinmek için aşağıdaki ek kaynaklara bakın.

Dokümanlar

Örnek uygulamalar

Videolar

API referansı ve kaynak kodu