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

Materyal Tasarım 3, Materyal Tasarım'ın bir sonraki evrimidir. Güncellenen temalar, bileşenler ve dinamik renk gibi Material You kişiselleştirme özellikleri bu sürüme dahildir. Material Design 2'nin güncellenmiş bir sürümüdür ve Android 12 ve sonraki sürümlerdeki yeni görsel stil ve sistem kullanıcı arayüzüyle uyumludur.

Bu kılavuzda, Compose Material (androidx.compose.material) Jetpack kitaplığından Compose Material 3 (androidx.compose.material3) Jetpack kitaplığına geçiş ele alınmaktadır.

Yaklaşımlar

Genel olarak tek bir uygulamada hem M2 hem de M3'ü uzun süreli olarak kullanmamalısınız. Bunun nedeni, iki tasarım sisteminin ve ilgili kitaplıkların kullanıcı deneyimi/kullanıcı arayüzü tasarımları ve Compose uygulamaları açısından önemli ölçüde farklı olmasıdır.

Uygulamanız, Figma kullanılarak oluşturulan bir tasarım sistemi gibi bir tasarım sistemi kullanabilir. Bu tür durumlarda, sizin veya tasarım ekibinizin, Oluşturma taşıma işlemini başlatmadan önce bu öğeyi M2'den M3'e taşımanızı önemle tavsiye ederiz. Kullanıcı deneyimi/kullanıcı arayüzü tasarımı M2'ye dayalı olan bir uygulamanın M3'e taşınması anlamlı değildir.

Ayrıca, taşımaya yaklaşımınız uygulamanızın boyutuna, karmaşıklığına ve kullanıcı deneyimi/kullanıcı arayüzü tasarımına bağlı olarak değişmelidir. Bu, kod tabanınızın üzerindeki etkiyi en aza indirmenize yardımcı olur. Geçiş sürecine aşamalı bir yaklaşım benimsemeniz gerekir.

Ne zaman taşıma işlemi yapmalısınız?

Taşıma işlemini en kısa sürede başlatmanız gerekir. Ancak uygulamanızın M2'den M3'e tamamen taşınmaya uygun olup olmadığını değerlendirmeniz önemlidir. Başlamadan önce incelemeniz gereken bazı engelleyici senaryolar vardır:

Senaryo Önerilen yaklaşım
Engelleyici yok Aşamalı taşıma işlemine başlama
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şıma işlemine başlama
Siz veya tasarım ekibiniz, uygulamanın tasarım sistemini M2'den M3'e taşımadıysanız Tasarım sistemini M2'den M3'e taşıyın, ardından aşamalı taşıma işlemine başlayın

Yukarıdaki senaryolardan etkilenmiş olsanız bile, uygulama güncellemesini kaydetmeden ve yayınlamadan önce taşıma işlemini aşamalı olarak gerçekleştirmeniz gerekir. Bu gibi durumlarda, M2 ve M3'ü yan yana kullanır ve M3'e geçiş yaparken M2'yi kademeli olarak kullanımdan kaldırırsınız.

Aşamalı yaklaşım

Aşamalı taşıma işleminin genel adımları şunlardır:

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

Bağımlılıklar

M3, M2'den ayrı bir pakete ve sürüme sahiptir:

M2

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

M3

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

En son M3 sürümlerini Compose Material 3 sürümleri sayfasında bulabilirsiniz.

Ana M2 ve M3 kitaplıkları dışındaki diğer materyal bağımlılıkları değişmedi. M2 ve M3 paketlerinin ve sürümlerinin bir karışımını kullanıyorlar ancak bu, taşıma işlemini etkilemez. Bunlar M3 ile olduğu gibi kullanılabilir:

Kitaplık Paket ve sürüm
Materyal simgesi oluşturma androidx.compose.material:material-icons-*:$m2-version
Materyal dalga oluşturma androidx.compose.material:material-ripple:$m2-version

Deneysel API'ler

Bazı M3 API'leri deneysel olarak kabul edilir. Bu gibi durumlarda, ExperimentalMaterial3Api ek açıklamasını kullanarak işlev veya dosya düzeyinde 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 tema bileşeni MaterialTheme olarak adlandırılır 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 ve M3 renk sistemlerinin karşılaştırması
Şekil 1. M2 renk sistemi (solda) ve M3 renk sistemi (sağda).

M3'teki renk sistemi, M2'den önemli ölçüde farklıdır. Renk parametrelerinin sayısı arttı, farklı adlara sahipler ve M3 bileşenleriyle farklı şekilde eşleniyorlar. Oluşturma'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 farklılıklar göz önüne alındığında, Color parametreleri için makul bir eşleme yoktur. Bunun yerine, M3 renk şeması oluşturmak için Material Theme Builder aracını kullanın. Araçtaki temel kaynak renkler olarak M2 renklerini kullanın. Araç, M2 renk şeması tarafından kullanılan ton paletlerine genişletir. Başlangıç noktası olarak aşağıdaki eşlemeler önerilir:

M2 Material Theme Builder
primary Birincil
primaryVariant İkincil
secondary Üçüncül
surface veya background Normal
M3 renk şeması oluşturmak için Material Theme Builder'da kullanılan M2 renkleri
Şekil 2. M3 renk şeması oluşturmak için Material Theme Builder'da kullanılan Jetchat'in M2 renkleri.

Açık ve koyu temalar için renk onaltılık kod değerlerini araçtan kopyalayıp M3 ColorScheme örneğini uygulamak üzere kullanabilirsiniz. Alternatif olarak, Material Theme Builder da Compose kodunu dışa aktarabilir.

isLight

M2 Colors sınıfının aksine M3 ColorScheme sınıfı isLight parametresi içermez. Genel olarak, bu bilgilere 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'daki özel tasarım sistemleri kılavuzuna bakın.

Dinamik renk

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

Yazı biçimi

M2 ve M3 yazım sistemlerinin karşılaştırması
Şekil 3. M3 yazım sistemi (solda) ve M2 yazım sistemi (sağda)

M3'teki tipografi sistemi, M2'den farklıdır. Yaklaşık olarak aynı sayıda yazı tipi parametresi vardır ancak bunların adları farklıdır ve M3 bileşenleriyle farklı şekilde eşlenir. Oluşturma'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ırması
Şekil 4. M2 şekil sistemi (solda) ve M3 şekil sistemi (sağda)

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şlendiler. Oluşturma'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 bileşenlerin ve düzenlerin çoğu M3'te kullanılabilir. Ancak M2'de bulunmayan bazı özellikler de M3'te mevcuttur. Ayrıca, bazı M3 bileşenleri M2'deki eşdeğerlerine kıyasla daha fazla varyasyona sahiptir. 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, yazı tipi ve şekil sistemleri göz önüne alındığında, M3 bileşenleri yeni tema değerleriyle farklı şekilde eşlenir. Bu eşlemeler için doğru kaynak olarak Compose Material 3 kaynak kodundaki token dizinindeki öğelere göz atabilirsiniz.

Bazı bileşenler için özel hususlar dikkate alınmalıdır. Başlangıç noktası olarak aşağıdaki işlev eşlemelerini kullanabilirsiniz:

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çin
androidx.compose.material.BottomDrawer M3 eşdeğeri yok, bunun yerine ModalBottomSheet'e geçin

Yeniden adlandırılan 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 referanslarına genel bakış bölümünde en son M3 bileşenlerini ve düzenlerini inceleyin. Yeni ve güncellenmiş API'ler için sürümler sayfasını takip edin.

İskelet, bilgi çubuğu ve gezinme çekmecesi

M2 ve M3 iskeletinin, bilgi çubuğu ve gezinme çekmecesini içeren karşılaştırması
Şekil 5. M2 iskeleti (sol) ve M3 iskeleti (sağ) arasında gezinme menüsü ve bilgi çubuğu karşılaştırması.

M3'teki iskele, M2'dekinden farklıdır. Hem M2 hem de M3'te ana düzen bileşeni Scaffold olarak adlandırılır ancak 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, backgroundColor parametresi içeriyor. Bu parametre, M3 Scaffold'te containerColor olarak adlandırıldı:

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 bilgi çubuğu göstermek için bunun yerine SnackbarHostState 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'deki tüm drawer* parametreleri M3 Scaffold'ten kaldırıldı. drawerShape ve drawerContent gibi parametreler buna dahildir. M3 Scaffold içeren bir çekmece göstermek için bunun yerine ModalNavigationDrawer gibi bir gezinme çekmecesi bileşeni kullanın:

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ılabilir liste içeren M2 ve M3 iskeletinin karşılaştırması
Şekil 6. Üst uygulama çubuğu ve kaydırılabilir liste içeren M2 iskeleti (solda) ile üst uygulama çubuğu ve kaydırılabilir liste içeren M3 iskeleti (sağda)

M3'teki üst uygulama çubukları, M2'dekilerden farklıdır. Hem M2 hem de M3'te, ana üst uygulama çubuğu bileşeni 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(…)

Daha önce M2'de TopAppBariçerikleri ortalıyorsanız M3'ü CenterAlignedTopAppBar kullanmayı düşünün. MediumTopAppBar ve LargeTopAppBar seçeneklerini de göz önünde bulundurabilirsiniz.

M3 üst uygulama çubukları, TopAppBarScrollBehavior sınıfında kaydırırken farklı işlevler (ör. yüksekliği değiştirme) sağlamak için yeni bir scrollBehavior parametresi içerir. Bu özellik, Modifer.nestedScroll ile içerik kaydırmayla birlikte çalışır. M2 TopAppBar'te bu, elevation parametresini manuel olarak değiştirerek yapılabiliyordu:

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 menüsü ile M3 gezinme çubuğunun karşılaştırması
Şekil 7. M2 alt gezinme menüsü (solda) ve M3 gezinme çubuğu (sağda).

M2'deki alt gezinme, M3'te gezinme çubuğu olarak yeniden adlandırıldı. M2'de BottomNavigation ve BottomNavigationItem bileşenleri, M3'te ise NavigationBar ve NavigationBarItem bileşenleri bulunur:

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'ler

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

M3'teki düğmeler, simge düğmeleri ve kayan işlem düğmeleri (FAB'ler), M2'dekilerden farklıdır. M3, M2 düğme bileşenlerinin tümü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, yeni düğme varyantları da içerir. Compose Material3 API referansına genel bakış başlıklı makalede bu bilgilere göz atabilirsiniz.

Geçiş yap

M2 ve M3 anahtarlarının karşılaştırması
Şekil 9. M2 anahtarı (solda) ve M3 anahtarı (sağda).

M3'teki anahtar, M2'deki anahtardan farklıdır. Hem M2 hem de M3'te anahtar bileşeni Switch olarak adlandırılır ancak 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ırması
Şekil 10. Açık tema (solda) ve koyu temada (sağda) M2 yüzey yüksekliği ve 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 yükseklik vardır:

  • Gölge yüksekliği (M2 ile aynı şekilde gölge oluşturur)
  • Ton yükseltme (M3'te yeni olan bir renk yer paylaşımı)

Oluşturma işleminde 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'deki elevation Dp değerlerini M3'teki hem shadowElevation hem de tonalElevation için kullanabilirsiniz. Surface, çoğu bileşenin arkasındaki destekleyici bileşendir. Bu nedenle, bileşen bileşenleri de aynı şekilde taşımanız gereken yükseklik parametrelerini gösterebilir.

M3'teki tonlu yükseklik, M2 koyu temalarındaki yükseklik yer paylaşımı kavramının yerini alır . Sonuç olarak, ElevationOverlay ve LocalElevationOverlay M3'te mevcut değildir ve M2'deki LocalAbsoluteElevation, M3'te LocalAbsoluteTonalElevation olarak değiştirilmiştir.

Vurgu ve içerik alfa değeri

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

M3'teki vurgu, M2'den önemli ölçüde farklıdır. M2'de vurgu, metin ve simgeler gibi içerikleri birbirinden ayırt etmek için belirli alfa değerlerine sahip açık renklerin kullanılmasıydı. M3'te artık birkaç farklı yaklaşım mevcuttur:

  • Genişletilmiş M3 renk sisteminden açık renklerin yanı sıra açık varyant renklerini kullanma
  • Metin için farklı yazı tipi kalınlıkları kullanma

Sonuç olarak, ContentAlpha ve LocalContentAlpha M3'te mevcut değildir ve değiştirilmesi 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 örnek olarak aşağıdaki görseli inceleyebilirsiniz:

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 vurgusuna örnekler 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 kapsayıcı olarak adlandırılır. Genel olarak, aynı değerleri kullanarak M2'deki background* parametrelerini M3'teki container* parametreleriyle değiştirebilirsiniz. Örnek:

M2

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

M3

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

Compose'da M2'den M3'e geçiş hakkında daha fazla bilgi edinmek için aşağıdaki ek kaynaklara göz atın.

Dokümanlar

Örnek uygulamalar

Videolar

API referansı ve kaynak kodu