Wear OS için Compose'da Materyal 2.5'ten Materyal 3'e geçme

Material 3 Expressive, Materyal Tasarım'ın bir sonraki aşamasıdır. Güncellenmiş temalar, bileşenler ve dinamik renk gibi kişiselleştirme özellikleri içerir.

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

Yaklaşımlar

Uygulama kodunuzu M2.5'ten M3'e taşımak için Compose Material taşıma telefon kılavuzunda açıklanan yaklaşımı uygulayın. Özellikle şunlara dikkat edin:

• Tek bir uygulamada uzun vadeli olarak hem M2.5 hem de M3'ü kullanmamanız gerekir.
• Artık Horologist Composables, Compose Layout veya Compose Material kitaplıklarını kullanmamanız gerekir. Bunun yerine M3'teki bileşenleri kullanın.
• Aşamalı bir yaklaşım benimseyin.

Bağımlılıklar

M3'ün, M2.5'ten ayrı bir paketi ve sürümü vardır:

implementation("androidx.wear.compose:compose-material:1.4.0")

implementation("androidx.wear.compose:compose-material3:1.8.0-alpha03")

En yeni M3 sürümlerini Wear Compose sürümleri sayfasında bulabilirsiniz.

Wear Compose Foundation kitaplığının 1.8.0-alpha03 sürümünde, Material 3 bileşenleriyle çalışacak şekilde tasarlanmış bazı yeni bileşenler kullanıma sunuldu. Benzer şekilde, Wear Compose Navigation kitaplığındaki SwipeDismissableNavHost, Wear OS 6 (API düzeyi 36) veya sonraki sürümlerde çalışırken güncellenmiş bir animasyona sahiptir. Wear Compose Material 3 sürümüne güncellerken Wear Compose Foundation ve Navigation kitaplıklarını da güncellemenizi öneririz:

implementation("androidx.wear.compose:compose-foundation:1.8.0-alpha03")
implementation("androidx.wear.compose:compose-navigation:1.8.0-alpha03")

Tema

Hem M2.5 hem de M3'te tema composable'ı MaterialTheme olarak adlandırılır ancak içe aktarma paketleri ve parametreleri farklıdır. M3'te Colors parametresi ColorScheme olarak yeniden adlandırıldı ve geçişleri uygulamak için MotionScheme kullanıma sunuldu.

import androidx.wear.compose.material.MaterialTheme

MaterialTheme(
    colors = AppColors,
    typography = AppTypography,
    shapes = AppShapes,
    content = content
)

import androidx.wear.compose.material3.MaterialTheme
// ...
    MaterialTheme(
        colorScheme = ColorScheme(),
        typography = Typography(),
        shapes = Shapes(),
        motionScheme = MotionScheme.standard(),
        content = { /*content here*/ }
    )
Theme.kt

Renk

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

import androidx.wear.compose.material.Colors

val appColorScheme: Colors = Colors(
   // M2.5 Color parameters
)

import androidx.wear.compose.material3.ColorScheme
// ...
    val appColorScheme: ColorScheme = ColorScheme(
        // M3 ColorScheme parameters
    )
Color.kt

Aşağıdaki tabloda M2.5 ile M3 arasındaki temel farklar açıklanmaktadır:

Dinamik renk teması

M3'teki yeni özelliklerden biri dinamik renk temasıdır. Kullanıcılar kadran renklerini değiştirirse kullanıcı arayüzündeki renkler de buna göre değişir.

Dinamik renk şemasını uygulamak için dynamicColorScheme işlevini kullanın ve dinamik renk şeması kullanılamıyorsa yedek olarak defaultColorScheme sağlayın.

@Composable
fun myApp() {
    val dynamicColorScheme = dynamicColorScheme(LocalContext.current)
    MaterialTheme(colorScheme = dynamicColorScheme ?: myBrandColors) {}
}

internal val myBrandColors: ColorScheme = ColorScheme( /* Specify colors here */)
Color.kt

Yazı biçimi

M3'teki tipografi sistemi, M2.5'ten farklıdır ve aşağıdaki özellikleri içerir:

• Dokuz yeni metin stili
• Farklı ağırlıklar, genişlikler ve yuvarlaklıklar için yazı tipi ölçeklerinin özelleştirilmesine olanak tanıyan esnek yazı tipleri

• Esnek yazı tiplerinin kullanıldığı AnimatedText

import androidx.wear.compose.material.Typography

val Typography = Typography(
   // M2.5 TextStyle parameters
)

import androidx.wear.compose.material3.Typography

val Typography = Typography(
    // M3 TextStyle parameters
)
Typography.kt

Flex yazı tipleri

Esnek yazı tipleri, tasarımcıların belirli boyutlar için yazı genişliğini ve kalınlığını belirlemesine olanak tanır.

Metin stilleri

M3'te aşağıdaki TextStyle'lar kullanılabilir. Bunlar, çeşitli M3 bileşenleri tarafından varsayılan olarak kullanılır.

Şekil

M3'teki şekil sistemi, M2.5'ten farklıdır. Şekil parametrelerinin sayısı arttı, farklı şekilde adlandırılıyorlar ve M3 bileşenleriyle farklı şekilde eşleniyorlar. Aşağıdaki şekil boyutları kullanılabilir:

• Çok küçük
• Küçük
• Orta
• Büyük
• Çok büyük

Compose'da bu, M2.5 Shapes sınıfı ve M3 Shapes sınıfı için geçerlidir:

import androidx.wear.compose.material.Shapes

val Shapes = Shapes(
   // M2.5 Shapes parameters
)

import androidx.wear.compose.material3.Shapes

val Shapes = Shapes(
    // M3 Shapes parameters
)
Shape.kt

Başlangıç noktası olarak Compose'da Material 2'den Material 3'e geçiş bölümündeki şekil parametresi eşlemesini kullanın.

Şekil dönüştürme

M3, Şekil Dönüştürme özelliğini sunuyor: Şekiller artık etkileşimlere göre dönüşüyor.

Şekil Dönüştürme davranışı, çeşitli yuvarlak düğmelerde varyasyon olarak kullanılabilir. Şekil Dönüştürme'yi destekleyen düğmelerin listesini aşağıda bulabilirsiniz:

Bileşenler ve Düzen

M2.5'teki bileşenlerin ve düzenlerin çoğu M3'te kullanılabilir. Ancak bazı M3 bileşenleri ve düzenleri M2.5'te yoktu. Ayrıca bazı M3 bileşenleri, M2.5'teki eşdeğerlerinden daha fazla varyasyona sahiptir.

Bazı bileşenler özel olarak ele alınmalıdır ancak başlangıç noktası olarak aşağıdaki işlev eşlemeleri önerilir:

Yaygın olarak kullanılan Material 3 bileşenlerinin ve bunların Material 2.5'teki karşılıklarının listesini aşağıda bulabilirsiniz:

Son olarak, Wear Compose Foundation kitaplığındaki bazı alakalı bileşenlerin listesi:

Düğmeler

M3'teki düğmeler M2.5'ten farklıdır. M2.5 çip, düğmeyle değiştirildi. Button uygulaması, Text, maxLines ve textAlign için varsayılan değerler sağlar. Bu varsayılan değerler, Text öğesinde geçersiz kılınabilir.

import androidx.wear.compose.material.Chip

//M2.5 Buttons
Chip(...)
CompactChip(...)
Button(...)

//M3 Buttons
Button(onClick = { }){}
CompactButton(onClick = { }){}
IconButton(onClick = { }){}
TextButton(onClick = { }){}
Button.kt

M3'te yeni düğme varyasyonları da bulunur. Compose Material 3 API referansına genel bakış sayfasından bu bileşenlere göz atabilirsiniz.

M3'te yeni bir düğme bulunur: EdgeButton. EdgeButton, 4 farklı boyutta sunulur: ekstra küçük, küçük, orta ve büyük. EdgeButton uygulaması, boyuta bağlı olarak maxLines için özelleştirilebilen varsayılan bir değer sağlar.

TransformingLazyColumn veya ScalingLazyColumn kullanıyorsanız EdgeButton'yi son liste öğesi olarak eklemek yerine EdgeButton'yi ScreenScaffold içine aktarın. Böylece , kaydırma işlemiyle şeklini değiştirerek dönüşür. EdgeButton öğesini ScreenScaffold ve TransformingLazyColumn ile nasıl kullanacağınızı öğrenmek için aşağıdaki koda bakın.

val state = rememberTransformingLazyColumnState()
ScreenScaffold(
    scrollState = state,
    edgeButton = {
        EdgeButton(
            onClick = { },
            modifier = Modifier.scrollable(
                state,
                orientation = Orientation.Vertical,
                reverseDirection = true,
                // Apply overscroll to the EdgeButton for proper scrolling behavior.
                overscrollEffect = rememberOverscrollEffect(),
            ),
        ) {
            Text(stringResource(R.string.show))
        }
    },
) { contentPadding ->
    TransformingLazyColumn(state = state, contentPadding = contentPadding) {
        // additional code here
        // ...
    }
}
Button.kt

İskele

M3'teki Scaffold, M2.5'ten farklıdır. M3'te, AppScaffold ve yeni ScreenScaffold composable'ı, Scaffold'un yerini aldı. AppScaffold ve ScreenScaffold, ekranın yapısını düzenler ve ScrollIndicator ile TimeText bileşenlerinin geçişlerini koordine eder.

AppScaffold, kaydırarak kapatma gibi uygulama içi geçişler sırasında TimeText gibi statik ekran öğelerinin görünür kalmasını sağlar. Ana uygulama içeriği için bir alan sağlar. Bu alan genellikle SwipeDismissableNavHost gibi bir gezinme bileşeni tarafından sağlanır.

Etkinlik için bir AppScaffold bildirir ve her ekran için bir ScreenScaffold kullanırsınız. AppScaffold, ekranlara varsayılan bir TimeText bileşeni ekler. timeText parametresini kullanarak özelleştirmek isterseniz bu değeri geçersiz kılabilirsiniz.

import androidx.wear.compose.material.Scaffold

Scaffold {...}

    AppScaffold {
        val navController = rememberSwipeDismissableNavController()
        SwipeDismissableNavHost(
            navController = navController,
            startDestination = "message_list"
        ) {
            composable("message_list") {
                MessageList(onMessageClick = { id ->
                    navController.navigate("message_detail/$id")
                })
            }
            composable("message_detail/{id}") {
                MessageDetail(id = it.arguments?.getString("id")!!)
            }
        }
    }
}

// Implementation of one of the screens in the navigation
@Composable
fun MessageDetail(id: String) {
    // .. Screen level content goes here
    val scrollState = rememberTransformingLazyColumnState()
    val transformationSpec = rememberTransformationSpec()

    ScreenScaffold(
        scrollState = scrollState,
    ) { contentPadding ->
        // Screen content goes here
        // ...
Navigation.kt

HorizontalPageIndicator ile HorizontalPager kullanıyorsanız HorizontalPagerScaffold'e geçiş yapabilirsiniz. HorizontalPagerScaffold, AppScaffold içine yerleştirilir. AppScaffold ve HorizontalPagerScaffold, bir sayfa gezgininin yapısını düzenler ve HorizontalPageIndicator ile TimeText bileşenlerinin geçişlerini koordine eder.

HorizontalPagerScaffold, varsayılan olarak ekranın orta-alt kısmında HorizontalPageIndicator öğesini gösterir ve Pager öğesinin sayfalanıp sayfalanmadığına göre TimeText ve HorizontalPageIndicator öğelerinin gösterilmesini ve gizlenmesini koordine eder. Bu, PagerState tarafından belirlenir.

Ayrıca, sayfa gezginindeki bir sayfayı konumuna göre ölçeklendirme ve gölgeleme efektiyle animasyonlu hale getiren yeni bir AnimatedPage bileşeni de var.

AppScaffold {
    val pagerState = rememberPagerState(pageCount = { 10 })

    HorizontalPagerScaffold(pagerState = pagerState) {
        HorizontalPager(
            state = pagerState,
            flingBehavior =
                PagerScaffoldDefaults.snapWithSpringFlingBehavior(
                    state = pagerState
                ),
        ) { page ->
            AnimatedPage(pageIndex = page, pagerState = pagerState) {
                val columnState = rememberTransformingLazyColumnState()
                val transformationSpec = rememberTransformationSpec()

                ScreenScaffold(
                    scrollState = columnState,
                ) { contentPadding ->
                    TransformingLazyColumn(
                        state = columnState,
                        contentPadding = contentPadding,
                    ) {
                        item {
                            ListHeader(
                                modifier = Modifier
                                    .fillMaxWidth()
                                    .transformedHeight(this, transformationSpec)
                                    .minimumVerticalContentPadding(
                                        ListHeaderDefaults.minimumTopListContentPadding
                                    ),
                                transformation = SurfaceTransformation(transformationSpec),
                            ) {
                                Text(text = "Pager sample")
                            }
                        }
                        item {
                            Card(
                                modifier = Modifier
                                    .fillMaxWidth()
                                    .transformedHeight(this, transformationSpec)
                                    .minimumVerticalContentPadding(
                                        CardDefaults.minimumVerticalListContentPadding
                                    ),
                                transformation = SurfaceTransformation(transformationSpec),
                            ) {
                                if (page == 0) {
                                    Text(text = "Page #$page. Swipe right")
                                } else {
                                    Text(text = "Page #$page. Swipe left and right")
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
Pager.kt

Son olarak M3, HorizontalPagerScaffold ile aynı kalıbı izleyen bir VerticalPagerScaffold sunar:

@Composable
fun VerticalPagerScaffoldSample() {
    AppScaffold {
        val pagerState = rememberPagerState(pageCount = { 10 })

        VerticalPagerScaffold(pagerState = pagerState) {
            VerticalPager(
                state = pagerState,
                flingBehavior =
                    PagerScaffoldDefaults.snapWithSpringFlingBehavior(
                        state = pagerState
                    ),
            ) { page ->
                AnimatedPage(pageIndex = page, pagerState = pagerState) {
                    ScreenScaffold {
                        Column(
                            modifier = Modifier.fillMaxSize(),
                            horizontalAlignment = Alignment.CenterHorizontally,
                            verticalArrangement = Arrangement.Center,
                        ) {
                            Text(text = "Page #$page")
                            Spacer(modifier = Modifier.height(8.dp))
                            Text(text = "Swipe up and down")
                        }
                    }
                }
            }
        }
    }
}
Pager.kt

Yer tutucu

M2.5 ve M3 arasında bazı API değişiklikleri vardır. M3, iki yer tutucu değiştirici sağlar:

• Henüz yüklenmemiş içeriklerin yerine çizilen Modifier.placeholder
• Verilerin yüklenmesini beklerken animasyon döngüsünde çalışan bir yer tutucu parıltı efekti sağlayan yer tutucu parıltı efekti Modifier.placeholderShimmer.

Placeholder bileşeninde yapılan diğer değişiklikler için aşağıdaki tabloya bakın.

SwipeDismissableNavHost

SwipeDismissableNavHost, wear.compose.navigation kapsamındadır. Bu bileşen M3 ile kullanıldığında M3 MaterialTheme, LocalSwipeToDismissBackgroundScrimColor ve LocalSwipeToDismissContentScrimColor değerlerini günceller.

TransformingLazyColumn

TransformingLazyColumn, androidx.wear.compose.foundation.lazy'in bir parçasıdır ve kaydırma sırasında liste öğelerinde animasyonları ölçeklendirme ve dönüştürme desteği ekleyerek kullanıcı deneyimini iyileştirir. Uygulamaların ScalingLazyColumn yerine TransformingLazyColumn kullanmaya başlaması önemle tavsiye edilir.

ScalingLazyColumn gibi, birleştirmelerde hatırlanan bir TransformingLazyColumnState oluşturmak için rememberTransformingLazyColumnState() sağlar.

Ölçeklendirme ve şekil değiştirme animasyonları eklemek için her liste öğesine aşağıdakileri ekleyin:

• Modifier.transformedHeight, TransformationSpec kullanarak öğelerin dönüştürülmüş yüksekliğini hesaplamanıza olanak tanır. Daha fazla özelleştirmeye ihtiyacınız yoksa rememberTransformationSpec() kullanabilirsiniz.
• SurfaceTransformation

Listenin üst ve alt kısmındaki dolgunun doğru olduğunu doğrulamak için minimumVerticalContentPadding değiştiricisini kullanın.

val columnState = rememberTransformingLazyColumnState()
val transformationSpec = rememberTransformationSpec()
ScreenScaffold(
    scrollState = columnState
) { contentPadding ->
    TransformingLazyColumn(
        state = columnState,
        contentPadding = contentPadding
    ) {
        item {
            ListHeader(
                modifier = Modifier
                    .fillMaxWidth()
                    .transformedHeight(this, transformationSpec)
                    .minimumVerticalContentPadding(ListHeaderDefaults.minimumTopListContentPadding),
                transformation = SurfaceTransformation(transformationSpec)
            ) {
                Text(text = "Header")
            }
        }
        // ... other items
        item {
            Button(
                modifier = Modifier
                    .fillMaxWidth()
                    .transformedHeight(this, transformationSpec)
                    .minimumVerticalContentPadding(ButtonDefaults.minimumVerticalListContentPadding),
                transformation = SurfaceTransformation(transformationSpec),
                onClick = { /* ... */ },
                icon = {
                    Icon(
                        imageVector = Icons.Default.Build,
                        contentDescription = "build",
                    )
                },
            ) {
                Text(
                    text = "Build",
                    maxLines = 1,
                    overflow = TextOverflow.Ellipsis,
                )
            }
        }
    }
}
List.kt

Faydalı bağlantılar

Compose'da M2.5'ten M3'e geçiş hakkında daha fazla bilgi edinmek için aşağıdaki ek kaynakları inceleyin.

Örnekler

• GitHub'daki Wear OS örnekleri
• Wear OS için Compose codelab
• Jetcaster örneği

API referansı ve kaynak kodu

• Compose Material 3 API referansı
• Kaynak kodundaki Compose Material 3 örnekleri

Tasarım

• Tasarım rehberliği