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

Materyal Tasarım 3, Materyal Tasarım'ın yeni evrimidir. Güncellenmiş temalar, bileşenler ve dinamik renk gibi Material You kişiselleştirme özelliklerini içerir. Materyal Tasarım 2 için bir güncellemedir. Android 12 ve sonraki sürümlerdeki 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 odaklanmaktadır.

Yaklaşımlar

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

Uygulamanızda, Figma kullanılarak oluşturulan gibi bir tasarım sistemi kullanılıyor olabilir. Bu tür durumlarda, sizin veya tasarım ekibinizin Compose taşıma işlemine başlamadan önce 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şıma konusundaki 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 farklılık göstermelidir. Böylece kod tabanınız üzerindeki etkiyi en aza indirebilirsiniz. Taşıma işlemi için aşamalı bir yaklaşım benimsemeniz gerekir.

Taşınma zamanı

Taşıma işlemini en kısa sürede başlatmanız gerekir. Bununla birlikte, uygulamanızın M2'den M3'e tamamen geçiş yapmak için gerçekçi bir konumda olup olmadığını değerlendirmek önemlidir. Başlamadan önce göz önünde bulundurabileceğiniz bazı “engelleyici” senaryoları vardır:

Senaryo Önerilen yaklaşım
"Engelleyen" yok Aşamalı taşımaya başlayın
M2'den bir bileşen henüz M3'te kullanılamıyor. Aşağıdaki Bileşenler ve düzenler bölümüne bakın. Aşamalı taşımaya başlayın
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ıp aşamalı taşımaya başlayın

Yukarıdaki senaryolardan etkilenseniz bile bir uygulama güncellemesi gerçekleştirmeden ve yayınlamadan önce taşıma işleminde aşamalı bir yaklaşım benimsemelisiniz. Bu durumda M2 ve M3'ü yan yana kullanır, M3'e geçerken ise M2'yi kademeli olarak kullanımdan kaldırırsınız.

Aşamalı yaklaşım

Aşamalı taşımanın genel adımları şunlardır:

  1. M2 bağımlılığıyla birlikte M3 bağımlılığı ekleyin.
  2. Uygulamanızın temalarının M2 sürümleriyle birlikte uygulama temalarınızın M3 sürümlerini ekleyin.
  3. Uygulamanızın boyutuna ve karmaşıklığına bağlı olarak bağımsız modülleri, ekranları veya composable'ları 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'ü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"

Materyal 3 oluşturma sürümleri sayfasında en son M3 sürümlerine bakı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 ile sürümlerinin karışımını kullanırlar ancak bu durum taşıma işlemini etkilemez. M3'te olduğu gibi kullanılabilirler:

Kitaplık Paket ve sürüm
Materyal Simgeleri Oluşturma androidx.compose.material:material-icons-*:$m2-version
Material Ripple Oluşturma androidx.compose.material:material-ripple:$m2-version
Oluşturma Malzeme 3 Pencere Boyutu Sınıfı androidx.compose.material3:material3-window-size-class:$m3-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, composable tema MaterialTheme olarak adlandırılır ancak içe aktarma paketleri ve parametreleri birbirinden 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 (sol) ve M3 renk sistemi (sağ) karşılaştırması.

M3'teki renk sistemi, M2'den önemli ölçüde farklıdır. Renk parametrelerinin sayısı artmış, farklı adları vardır ve M3 bileşenleriyle farklı şekilde eşlenmiştir. Bu durum Compose'da 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 düşünüldüğünde, Color parametreleri için makul bir eşleme yoktur. Bunun yerine, bir M3 renk şeması oluşturmak için Materyal Tema Oluşturucu aracını kullanın. Araçta M2 renklerini "temel" kaynak renkler olarak 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 Tema 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 kullanılan M2 renkleri
Şekil 2. Jetchat'in M2 renkleri, M3 renk şeması oluşturmak için Material Theme Builder'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şturma 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'da özel tasarım sistemleri kılavuzuna bakın.

Dinamik renk

M3'teki yeni bir özellik dinamik renk'tir. M3 ColorScheme, özel renkler yerine aşağıdaki işlevleri kullanarak Android 12 ve sonraki sürümlerde cihaz duvar kağıdı renklerinden yararlanabilir:

Yazı biçimi

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

M3'teki tipografi sistemi M2'den farklıdır. Tipografi parametrelerinin sayısı yaklaşık olarak aynıdır ancak farklı adlara sahiptir ve M3 bileşenleriyle farklı şekilde eşlenirler. Bu durum, Compose'da M2 Typography 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 (sol) - M3 şekil sistemi (sağ)

M3'teki şekil sistemi, M2'den farklıdır. Şekil parametrelerinin sayısı arttı, farklı şekilde adlandırılmış ve M3 bileşenleriyle farklı şekilde eşleniyorlar. Bu durum, Compose'da M2 Shapes 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 M2'de var olmayan bazı eksiklikler veya yeniler var. Ayrıca bazı M3 bileşenleri, M2'deki eşdeğerlerinden 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, tipografi ve şekil sistemleri dikkate alındığında, M3 bileşenleri yeni tema oluşturma değerleriyle farklı şekilde eşleşme eğilimindedir. Bu eşlemeler için bilgi kaynağı olarak Compose Material 3 kaynak kodundaki jetonlar dizinine göz atmak iyi bir fikirdir.

Bazı bileşenler için özel dikkat edilmesi gerekir. Bununla birlikte, 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çin
androidx.compose.material.BottomDrawer M3 eşdeğeri yok, bunun yerine ModalBottomSheet'e 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ış sayfasında en yeni M3 bileşenlerini ve düzenlerini inceleyin. Ayrıca yeni ve güncellenmiş API'ler için sürümler sayfasına göz atın.

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

Snackbar ve gezinme çekmecesi ile M2 ve M3 iskelenin karşılaştırması
Şekil 5. Snackbar ve gezinme çekmecesi olan M2 iskelet (solda) ile atıştırmalık çubuğu ve gezinme çekmecesi olan M3 iskelet.

M3'teki iskele, M2'den farklıdır. Hem M2 hem de M3'te, composable ana düzen Scaffold olarak adlandırılır ancak içe aktarma paketleri ve parametreleri birbirinden 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, artık M3'te Scaffold olarak containerColor olarak adlandırılmış bir backgroundColor parametresi içeriyor:

M2

import androidx.compose.material.Scaffold

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

M3

import androidx.compose.material3.Scaffold

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

M2 ScaffoldState sınıfı, artık gerekli olmayan bir drawerState parametresi içerdiğinden M3'te mevcut değildir. M3 Scaffold ile atıştırmalık çubuklarını göstermek için 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 öğesindeki tüm drawer* parametreleri, M3 Scaffold öğesinden kaldırıldı. Bunlar, drawerShape ve drawerContent gibi parametreleri içerir. M3 Scaffold içeren bir çekmece göstermek için bunun yerine ModalNavigationDrawer gibi bir gezinme çekmecesi 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ılan liste ile M2 ve M3 yapı iskelesinin karşılaştırması
Şekil 6. Üst uygulama çubuğu ve kaydırılmış liste içeren M2 iskelet (solda) ile üst uygulama çubuğu ve kaydırılmış liste içeren M3 iskelet (sağ)

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

M2

import androidx.compose.material.TopAppBar

TopAppBar(…)

M3

import androidx.compose.material3.TopAppBar

TopAppBar(…)

Daha önce içeriği M2 TopAppBar içinde ortaladıysanız M3'ü CenterAlignedTopAppBar kullanabilirsiniz. MediumTopAppBar ve LargeTopAppBar özelliklerini de bilmenizde fayda vardır.

M3 üst uygulama çubukları, TopAppBarScrollBehavior sınıfında gezinirken yüksekliği değiştirmek gibi farklı işlevler sağlamak için yeni bir scrollBehavior parametresi içerir. Bu işlem, Modifer.nestedScroll aracılığıyla kayan içerikle birlikte çalışır. Bu, M2 TopAppBar'de elevation parametresini manuel olarak değiştirerek mümkün olmuştur:

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 ile M3 gezinme çubuğunun karşılaştırması
Şekil 7. M2 alt gezinme (sol) ve 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, M3'te ise NavigationBar ve NavigationBarItem composable'lar 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 (sol) ve M3 düğmeleri (sağ)

M3'teki düğmeler, simge düğmeleri ve kayan işlem düğmeleri (FAB'ler), M2'dekilerden farklıdır. M3, tüm M2 düğme 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, yeni düğme varyasyonları da içerir. Bunları Compose Material 3 API referansına genel bakış bölümünde inceleyebilirsiniz.

Geçiş yap

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

M3'teki Switch, M2'den farklıdır. Hem M2 hem de M3'te, composable'ın adı Switch olsa da içe aktarma paketleri farklı şekilde adlandırılı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 (sol) ve koyu temadaki (sağ) M2 yüzey yüksekliği ile M3 yüzey yüksekliği karşılaştırması.

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

  • Gölge rakımı (M2 ile aynı şekilde bir gölge oluşturur)
  • Ton rakımı (bir rengi kaplar, M3'te yeni)

Compose'da bu, 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, M3'te hem shadowElevation hem de/veya tonalElevation için M2'deki elevation Dp değerlerini kullanabilirsiniz. Surface, çoğu bileşenin arkasındaki composable'dır. Bu nedenle, bileşen composable'lar, aynı şekilde taşımanız gereken yükseklik parametrelerini de gösterebilir.

M3'te ton yükselmesi, M2 koyu temalarda yükseklik bindirme kavramının yerini alır . Bu nedenle, M3'te ElevationOverlay ve LocalElevationOverlay yoktur. M2'deki LocalAbsoluteElevation ise M3'te LocalAbsoluteTonalElevation olarak değiştirilmiştir.

Vurgu ve içerik alfa

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

M3'teki vurgu M2'den önemli ölçüde farklıdır. M2'de vurgu, metin ve simge gibi içerikleri ayırt etmek için belirli alfa değerleriyle "açık" renklerin kullanılmasını içerir. Artık M3'te birkaç farklı yaklaşım var:

  • Genişletilmiş M3 renk sistemindeki "varyant açık" renkleriyle birlikte "açık" renkleri kullandılar.
  • Metin için farklı yazı tipi ağırlıkları kullanma.

Bu nedenle, ContentAlpha ve LocalContentAlpha M3'te mevcut olmadığından bunların değiştirilmesi gerekiyor.

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)

Aşağıda, M2 ve M3'te simge vurgusunun bir örneği verilmiştir:

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

Aşağıda, M2 ve M3'te metin vurgusu örneği 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'de arka planlar, M3'te "kapsayıcılar" olarak adlandırılır. Genel olarak, aynı değerleri kullanarak M2'deki background* parametrelerini M3'teki container* ile değiştirebilirsiniz. Örnek:

M2

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

M3

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

Görünümlerin birlikte çalışabilirliği

Uygulamanız, Görünümler veya XML birlikte çalışabilirliği içeriyorsa ve MDC-Android Oluşturma 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"

En son sürümleri MDC-Android Compose Theme Adapter sürümleri sayfasında bulabilirsiniz.

M2 ve M3 sürümleri arasındaki en önemli fark 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 edinmek için BENİOKU sayfasını inceleyin.

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ş rehberine bakın.

Compose'da M2'den M3'e geçiş 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