Oluşturma bölümünde paylaşılan öğe geçişleri

Paylaşılan öğe geçişleri, aralarında tutarlı içerik bulunan composable'lar arasında sorunsuz bir geçiş yöntemidir. Genellikle gezinme için kullanılırlar ve kullanıcı farklı ekranlar arasında gezinirken bu ekranları görsel olarak birbirine bağlamanıza olanak tanırlar.

Örneğin, aşağıdaki videoda atıştırmalığın resminin ve başlığının listeleme sayfasından ayrıntılar sayfasına paylaşıldığını görebilirsiniz.

Şekil 1. Jetsnack paylaşılan öğe demosu.

Compose'da, paylaşılan öğeler oluşturmanıza yardımcı olan birkaç üst düzey API vardır:

• SharedTransitionLayout: Paylaşılan öğe geçişlerini uygulamak için gereken en dıştaki düzendir. SharedTransitionScope sağlar. Birleştirilebilir öğelerin, paylaşılan öğe değiştiricileri kullanabilmesi için SharedTransitionScope içinde olması gerekir.
• Modifier.sharedElement(): SharedTransitionScope'e başka bir composable ile eşleştirilmesi gereken composable'ı işaretleyen değiştirici.
• Modifier.sharedBounds(): SharedTransitionScope öğesine, bu composable'ın sınırlarının geçişin gerçekleşeceği kapsayıcı sınırları olarak kullanılması gerektiğini bildiren değiştirici. sharedElement() ile karşılaştırıldığında sharedBounds(), görsel olarak farklı içerikler için tasarlanmıştır.

Oluşturma'da ortak öğeler oluştururken önemli bir kavram, bunların yer paylaşımları ve kırpma ile nasıl çalıştığıdır. Bu önemli konu hakkında daha fazla bilgi edinmek için Kırpma ve yer paylaşımları bölümüne bakın.

Temel kullanım

Bu bölümde, daha küçük "liste" öğesinden daha büyük ayrıntılı öğeye geçişi sağlayan aşağıdaki geçiş oluşturulacaktır:

Şekil 2. İki composable arasında paylaşılan öğe geçişinin temel bir örneği.

Modifier.sharedElement() öğesini kullanmanın en iyi yolu, AnimatedContent, AnimatedVisibility veya NavHost ile birlikte kullanmaktır. Bu sayede, composable'lar arasındaki geçiş sizin için otomatik olarak yönetilir.

Başlangıç noktası, paylaşılan öğeler eklenmeden önce MainContent ve DetailsContent composable'ına sahip mevcut bir temel AnimatedContent'dir:

Şekil 3. AnimatedContent, paylaşılan öğe geçişleri olmadan başlatılıyor.

1. Paylaşılan öğelerin iki düzen arasında animasyonlu geçiş yapması için AnimatedContent composable'ı SharedTransitionLayout ile sarmalayın. SharedTransitionLayout ve AnimatedContent kapsamları, MainContent ve DetailsContent'e aktarılır:

   var showDetails by remember {
       mutableStateOf(false)
   }
   SharedTransitionLayout {
       AnimatedContent(
           showDetails,
           label = "basic_transition"
       ) { targetState ->
           if (!targetState) {
               MainContent(
                   onShowDetails = {
                       showDetails = true
                   },
                   animatedVisibilityScope = this@AnimatedContent,
                   sharedTransitionScope = this@SharedTransitionLayout
               )
           } else {
               DetailsContent(
                   onBack = {
                       showDetails = false
                   },
                   animatedVisibilityScope = this@AnimatedContent,
                   sharedTransitionScope = this@SharedTransitionLayout
               )
           }
       }
   }
   BasicSharedElementSnippets.kt

2. Eşleşen iki composable'da composable değiştirici zincirinize Modifier.sharedElement() ekleyin. SharedContentState nesnesi oluşturun ve rememberSharedContentState() ile hatırlayın. SharedContentState nesnesi, paylaşılan öğeleri belirleyen benzersiz anahtarı depolar. İçeriği tanımlamak için benzersiz bir anahtar sağlayın ve öğenin hatırlanması için rememberSharedContentState() kullanın. AnimatedContentScope, animasyonu koordine etmek için kullanılan değiştiriciye iletilir.

   @Composable
   private fun MainContent(
       onShowDetails: () -> Unit,
       modifier: Modifier = Modifier,
       sharedTransitionScope: SharedTransitionScope,
       animatedVisibilityScope: AnimatedVisibilityScope
   ) {
       Row(
           // ...
       ) {
           with(sharedTransitionScope) {
               Image(
                   painter = painterResource(id = R.drawable.cupcake),
                   contentDescription = "Cupcake",
                   modifier = Modifier
                       .sharedElement(
                           rememberSharedContentState(key = "image"),
                           animatedVisibilityScope = animatedVisibilityScope
                       )
                       .size(100.dp)
                       .clip(CircleShape),
                   contentScale = ContentScale.Crop
               )
               // ...
           }
       }
   }
   
   @Composable
   private fun DetailsContent(
       modifier: Modifier = Modifier,
       onBack: () -> Unit,
       sharedTransitionScope: SharedTransitionScope,
       animatedVisibilityScope: AnimatedVisibilityScope
   ) {
       Column(
           // ...
       ) {
           with(sharedTransitionScope) {
               Image(
                   painter = painterResource(id = R.drawable.cupcake),
                   contentDescription = "Cupcake",
                   modifier = Modifier
                       .sharedElement(
                           rememberSharedContentState(key = "image"),
                           animatedVisibilityScope = animatedVisibilityScope
                       )
                       .size(200.dp)
                       .clip(CircleShape),
                   contentScale = ContentScale.Crop
               )
               // ...
           }
       }
   }
   BasicSharedElementSnippets.kt

Paylaşılan öğe eşleşmesi olup olmadığı hakkında bilgi edinmek için rememberSharedContentState() değerini bir değişkene ayıklayın ve isMatchFound değerini sorgulayın.

Önemli: Bu değiştiricinin değiştirici zincirinde yerleştirildiği sıra önemlidir. Paylaşılmasını istemediğiniz her şeyi, değiştirici zincirindeki sharedElement() simgesinden

önceye yerleştirin.

Bu durumda aşağıdaki otomatik animasyon oluşturulur:

Şekil 4. İki composable arasında paylaşılan öğe geçişinin temel bir örneği.

Tüm kapsayıcının arka plan rengi ve boyutunun hâlâ varsayılan AnimatedContent ayarlarını kullandığını fark edebilirsiniz.

Paylaşılan sınırlar ve paylaşılan öğe

Modifier.sharedBounds(), Modifier.sharedElement() ile benzer. Ancak değiştiriciler aşağıdaki şekillerde farklılık gösterir:

• sharedBounds(), görsel olarak farklı olan ancak durumlar arasında aynı alanı paylaşması gereken içerikler için kullanılırken sharedElement(), içeriğin aynı olmasını bekler.
• sharedBounds() ile ekrana giren ve ekrandan çıkan içerik, iki durum arasındaki geçiş sırasında görünürken sharedElement() ile yalnızca hedef içerik, dönüşüm sınırları içinde oluşturulur. Modifier.sharedBounds(), AnimatedContent işlevine benzer şekilde içeriğin nasıl geçiş yapacağını belirten enter ve exit parametrelerine sahiptir.
• sharedBounds() için en yaygın kullanım alanı kapsayıcı dönüşüm kalıbıdır. sharedElement() için örnek kullanım alanı ise hero geçişidir.
• Text composable'ları kullanırken italik ve kalın arasında geçiş veya renk değişiklikleri gibi yazı tipi değişikliklerini desteklemek için sharedBounds() tercih edilir.

Önceki örnekte, iki farklı senaryoda Row ve Column öğelerine Modifier.sharedBounds() eklediğimizde ikisinin sınırlarını paylaşabilir ve geçiş animasyonunu gerçekleştirerek birbirleri arasında büyümelerini sağlayabiliriz:

@Composable
private fun MainContent(
    onShowDetails: () -> Unit,
    modifier: Modifier = Modifier,
    sharedTransitionScope: SharedTransitionScope,
    animatedVisibilityScope: AnimatedVisibilityScope
) {
    with(sharedTransitionScope) {
        Row(
            modifier = Modifier
                .padding(8.dp)
                .sharedBounds(
                    rememberSharedContentState(key = "bounds"),
                    animatedVisibilityScope = animatedVisibilityScope,
                    enter = fadeIn(),
                    exit = fadeOut(),
                    resizeMode = SharedTransitionScope.ResizeMode.scaleToBounds()
                )
                // ...
        ) {
            // ...
        }
    }
}

@Composable
private fun DetailsContent(
    modifier: Modifier = Modifier,
    onBack: () -> Unit,
    sharedTransitionScope: SharedTransitionScope,
    animatedVisibilityScope: AnimatedVisibilityScope
) {
    with(sharedTransitionScope) {
        Column(
            modifier = Modifier
                .padding(top = 200.dp, start = 16.dp, end = 16.dp)
                .sharedBounds(
                    rememberSharedContentState(key = "bounds"),
                    animatedVisibilityScope = animatedVisibilityScope,
                    enter = fadeIn(),
                    exit = fadeOut(),
                    resizeMode = SharedTransitionScope.ResizeMode.scaleToBounds()
                )
                // ...

        ) {
            // ...
        }
    }
}
SharedBoundsSnippets.kt

Şekil 5. İki composable arasında paylaşılan sınırlar.

Kapsamları anlama

Modifier.sharedElement() öğesini kullanmak için composable'ın SharedTransitionScope içinde olması gerekir. SharedTransitionLayout composable'ı, SharedTransitionScope sağlar. Bu bileşeni, kullanıcı arayüzü hiyerarşinizde paylaşmak istediğiniz öğeleri içeren aynı üst düzey noktaya yerleştirdiğinizden emin olun.

Genellikle, composable'lar bir AnimatedVisibilityScope içine de yerleştirilmelidir. Bu, genellikle composable'lar arasında geçiş yapmak için AnimatedContent kullanılarak veya doğrudan AnimatedVisibility kullanılarak ya da NavHost composable işlevi tarafından sağlanır (görünürlüğü manuel olarak yönetmediğiniz sürece). Birden fazla kapsam kullanmak için gerekli kapsamlarınızı bir CompositionLocal içine kaydedin, Kotlin'de bağlam alıcıları kullanın veya kapsamları işlevlerinize parametre olarak iletin.

Takip etmeniz gereken birden fazla kapsam veya derinlemesine iç içe yerleştirilmiş bir hiyerarşi varsa CompositionLocals kullanın. CompositionLocal, kaydedilecek ve kullanılacak tam kapsamları seçmenize olanak tanır. Öte yandan, bağlam alıcılarını kullandığınızda hiyerarşinizdeki diğer düzenler, sağlanan kapsamları yanlışlıkla geçersiz kılabilir. Örneğin, birden fazla iç içe yerleştirilmiş AnimatedContent varsa kapsamlar geçersiz kılınabilir.

val LocalNavAnimatedVisibilityScope = compositionLocalOf<AnimatedVisibilityScope?> { null }
val LocalSharedTransitionScope = compositionLocalOf<SharedTransitionScope?> { null }

@Composable
private fun SharedElementScope_CompositionLocal() {
    // An example of how to use composition locals to pass around the shared transition scope, far down your UI tree.
    // ...
    SharedTransitionLayout {
        CompositionLocalProvider(
            LocalSharedTransitionScope provides this
        ) {
            // This could also be your top-level NavHost as this provides an AnimatedContentScope
            AnimatedContent(state, label = "Top level AnimatedContent") { targetState ->
                CompositionLocalProvider(LocalNavAnimatedVisibilityScope provides this) {
                    // Now we can access the scopes in any nested composables as follows:
                    val sharedTransitionScope = LocalSharedTransitionScope.current
                        ?: throw IllegalStateException("No SharedElementScope found")
                    val animatedVisibilityScope = LocalNavAnimatedVisibilityScope.current
                        ?: throw IllegalStateException("No AnimatedVisibility found")
                }
                // ...
            }
        }
    }
}
BasicSharedElementSnippets.kt

Alternatif olarak, hiyerarşiniz çok derin değilse kapsamları parametre olarak iletebilirsiniz:

@Composable
fun MainContent(
    animatedVisibilityScope: AnimatedVisibilityScope,
    sharedTransitionScope: SharedTransitionScope
) {
}

@Composable
fun Details(
    animatedVisibilityScope: AnimatedVisibilityScope,
    sharedTransitionScope: SharedTransitionScope
) {
}
BasicSharedElementSnippets.kt

AnimatedVisibility ile paylaşılan öğeler

Önceki örneklerde, paylaşılan öğelerin AnimatedContent ile nasıl kullanılacağı gösterilmişti ancak paylaşılan öğeler AnimatedVisibility ile de kullanılabilir.

Örneğin, bu geç yüklenen ızgara örneğinde her öğe AnimatedVisibility ile sarmalanmıştır. Öğe tıklandığında içerik, kullanıcı arayüzünden çıkarılarak iletişim kutusu benzeri bir bileşene yerleştirilmiş gibi görünür.

var selectedSnack by remember { mutableStateOf<Snack?>(null) }

SharedTransitionLayout(modifier = Modifier.fillMaxSize()) {
    LazyColumn(
        // ...
    ) {
        items(listSnacks) { snack ->
            AnimatedVisibility(
                visible = snack != selectedSnack,
                enter = fadeIn() + scaleIn(),
                exit = fadeOut() + scaleOut(),
                modifier = Modifier.animateItem()
            ) {
                Box(
                    modifier = Modifier
                        .sharedBounds(
                            sharedContentState = rememberSharedContentState(key = "${snack.name}-bounds"),
                            // Using the scope provided by AnimatedVisibility
                            animatedVisibilityScope = this,
                            clipInOverlayDuringTransition = OverlayClip(shapeForSharedElement)
                        )
                        .background(Color.White, shapeForSharedElement)
                        .clip(shapeForSharedElement)
                ) {
                    SnackContents(
                        snack = snack,
                        modifier = Modifier.sharedElement(
                            sharedContentState = rememberSharedContentState(key = snack.name),
                            animatedVisibilityScope = this@AnimatedVisibility
                        ),
                        onClick = {
                            selectedSnack = snack
                        }
                    )
                }
            }
        }
    }
    // Contains matching AnimatedContent with sharedBounds modifiers.
    SnackEditDetails(
        snack = selectedSnack,
        onConfirmClick = {
            selectedSnack = null
        }
    )
}
AnimatedVisibilitySharedElementSnippets.kt

Şekil 6. Öğeler AnimatedVisibility ile paylaşıldı.

Değiştirici sıralaması

Modifier.sharedElement() ve Modifier.sharedBounds() ile, Compose'un geri kalanında olduğu gibi değiştirici zincirinizin sırası önemlidir. Boyutu etkileyen değiştiricilerin yanlış yerleştirilmesi, paylaşılan öğe eşleştirme sırasında beklenmedik görsel sıçramalara neden olabilir.

Örneğin, iki paylaşılan öğede farklı bir konuma dolgu değiştirici yerleştirirseniz animasyonda görsel bir fark olur.

var selectFirst by remember { mutableStateOf(true) }
val key = remember { Any() }
SharedTransitionLayout(
    Modifier
        .fillMaxSize()
        .padding(10.dp)
        .clickable {
            selectFirst = !selectFirst
        }
) {
    AnimatedContent(targetState = selectFirst, label = "AnimatedContent") { targetState ->
        if (targetState) {
            Box(
                Modifier
                    .padding(12.dp)
                    .sharedBounds(
                        rememberSharedContentState(key = key),
                        animatedVisibilityScope = this@AnimatedContent
                    )
                    .border(2.dp, Color.Red)
            ) {
                Text(
                    "Hello",
                    fontSize = 20.sp
                )
            }
        } else {
            Box(
                Modifier
                    .offset(180.dp, 180.dp)
                    .sharedBounds(
                        rememberSharedContentState(
                            key = key,
                        ),
                        animatedVisibilityScope = this@AnimatedContent
                    )
                    .border(2.dp, Color.Red)
                    // This padding is placed after sharedBounds, but it doesn't match the
                    // other shared elements modifier order, resulting in visual jumps
                    .padding(12.dp)

            ) {
                Text(
                    "Hello",
                    fontSize = 36.sp
                )
            }
        }
    }
}
BasicSharedElementSnippets.kt

Eşleşen sınırlar	Eşleşmeyen sınırlar: Paylaşılan öğe animasyonunun, yanlış sınırlara göre yeniden boyutlandırılması gerektiği için biraz bozuk göründüğüne dikkat edin.

Paylaşılan öğe değiştiricilerden önce kullanılan değiştiriciler, paylaşılan öğe değiştiricilere kısıtlamalar sağlar. Bu kısıtlamalar, başlangıç ve hedef sınırları, ardından da sınır animasyonunu türetmek için kullanılır.

Paylaşılan öğe değiştiricilerden sonra kullanılan değiştiriciler, alt öğenin hedef boyutunu ölçmek ve hesaplamak için önceki kısıtlamaları kullanır. Paylaşılan öğe değiştiriciler, alt öğeyi ilk boyuttan hedef boyuta kademeli olarak dönüştürmek için bir dizi animasyonlu kısıtlama oluşturur.

Animasyon için resizeMode = ScaleToBounds() veya composable'da Modifier.skipToLookaheadSize() kullanıyorsanız bu durum geçerli değildir. Bu durumda Compose, hedef kısıtlamaları kullanarak alt öğeyi düzenler ve düzen boyutunu değiştirmek yerine animasyonu gerçekleştirmek için ölçeklendirme faktörü kullanır.

Önemli: Eşleşen öğelerdeki niteleyicilerin sırası tutarlı olmalıdır. requiredSize() kullanmadığınız sürece boyut değiştiricileri, paylaşılan öğe değiştiricilerden sonra yerleştirin. Ortak öğe değiştiricilerden sonra requiredSize() kullanırsanız ScaleToBounds() kullansanız bile dönüşüm sırasında alt öğeler yeniden düzenlenmez. Öte yandan, requiredSize(), paylaşılan öğe değiştiricilerden önce geliyorsa requiredSize() öğesinin üst öğesi, paylaşılan öğeleri animatedSize hiçbir zaman gözlemleyemez.

Benzersiz anahtarlar

Karmaşık paylaşılan öğelerle çalışırken dize olmayan bir anahtar oluşturmak iyi bir uygulamadır. Çünkü dizeler, eşleştirme sırasında hataya açık olabilir. Eşleşmelerin gerçekleşmesi için her anahtarın benzersiz olması gerekir. Örneğin, Jetsnack'te aşağıdaki ortak öğeler bulunur:

Şekil 7. Kullanıcı arayüzünün her bir bölümü için ek açıklamalar içeren Jetsnack'i gösteren resim.

Paylaşılan öğe türünü temsil eden bir enum oluşturabilirsiniz. Bu örnekte, tüm atıştırmalık kartı ana ekrandaki birden fazla farklı yerde de görünebilir. Örneğin, "Popüler" ve "Önerilen" bölümünde. Paylaşılacak öğenin snackId, origin ("Popüler" / "Önerilen") ve type değerlerini içeren bir anahtar oluşturabilirsiniz:

data class SnackSharedElementKey(
    val snackId: Long,
    val origin: String,
    val type: SnackSharedElementType
)

enum class SnackSharedElementType {
    Bounds,
    Image,
    Title,
    Tagline,
    Background
}

@Composable
fun SharedElementUniqueKey() {
    // ...
            Box(
                modifier = Modifier
                    .sharedElement(
                        rememberSharedContentState(
                            key = SnackSharedElementKey(
                                snackId = 1,
                                origin = "latest",
                                type = SnackSharedElementType.Image
                            )
                        ),
                        animatedVisibilityScope = this@AnimatedVisibility
                    )
            )
            // ...
}
BasicSharedElementSnippets.kt

hashCode() ve equals() uyguladıkları için anahtarlar için veri sınıfları önerilir.

Önemli: İçerik listeleriyle çalışırken öğe numarasını anahtara eklemeniz veya farklı bir benzersiz tanımlayıcı kullanmanız gerekir.

Paylaşılan öğelerin görünürlüğünü manuel olarak yönetme

AnimatedVisibility veya AnimatedContent kullanmadığınız durumlarda, paylaşılan öğe görünürlüğünü kendiniz yönetebilirsiniz. Modifier.sharedElementWithCallerManagedVisibility() kullanın ve bir öğenin ne zaman görünür olması gerektiğini belirleyen kendi koşulunuzu sağlayın:

var selectFirst by remember { mutableStateOf(true) }
val key = remember { Any() }
SharedTransitionLayout(
    Modifier
        .fillMaxSize()
        .padding(10.dp)
        .clickable {
            selectFirst = !selectFirst
        }
) {
    Box(
        Modifier
            .sharedElementWithCallerManagedVisibility(
                rememberSharedContentState(key = key),
                !selectFirst
            )
            .background(Color.Red)
            .size(100.dp)
    ) {
        Text(if (!selectFirst) "false" else "true", color = Color.White)
    }
    Box(
        Modifier
            .offset(180.dp, 180.dp)
            .sharedElementWithCallerManagedVisibility(
                rememberSharedContentState(
                    key = key,
                ),
                selectFirst
            )
            .alpha(0.5f)
            .background(Color.Blue)
            .size(180.dp)
    ) {
        Text(if (selectFirst) "false" else "true", color = Color.White)
    }
}
BasicSharedElementSnippets.kt

Önemli: Paylaşılan öğe, visible == false olsa bile kullanıcı arayüzü ağacında kalır. Paylaşılan öğe, etkin bir eşleşmesi olduğu için boyutu veya konumu değiştiğinde geçiş başlatır. Bu nedenle, geçiş tamamlandıktan sonra visible == false ile paylaşılan öğenin SharedTransitionScope.isTransitionActive gözlemlenerek ağaçtan kaldırılması önerilir.

Mevcut sınırlamalar

Bu API'lerin birkaç sınırlaması vardır. Özellikle:

• Görünümler ve Compose arasında birlikte çalışabilirlik desteklenmez. Dialog veya ModalBottomSheet gibi AndroidView öğesini sarmalayan tüm composable'lar buna dahildir.
• Aşağıdakiler için otomatik animasyon desteği yoktur:
  • Paylaşılan resim composable'ları:
    • ContentScale varsayılan olarak animasyonlu değildir. Belirlenen bitişe ContentScale sabitlenir.
  • Şekil kırpma: Şekiller arasında otomatik animasyon için yerleşik destek yoktur. Örneğin, öğe geçiş yaparken kareden daireye animasyon oluşturulamaz.
  • Desteklenmeyen durumlarda sharedElement() yerine Modifier.sharedBounds() kullanın ve öğelere Modifier.animateEnterExit() ekleyin.