عمليات نقل العناصر المشتركة في Compose

تعد انتقالات العناصر المشتركة طريقة سلسة للانتقال بين العناصر القابلة للإنشاء التي تحتوي على محتوى متسق بينها. ويتم استخدامها غالبًا للتنقّل، ما يتيح لك ربط الشاشات المختلفة بشكل مرئي أثناء تنقّل المستخدمين بينها.

على سبيل المثال، في الفيديو التالي، يمكنك رؤية صورة ومقدّمة عن الطعم المشترَكَين من صفحة البيانات إلى صفحة التفاصيل.

الشكل 1. عرض توضيحي للعنصر المشترَك في Jetsnack

في Compose، تتوفر بعض واجهات برمجة التطبيقات عالية المستوى التي تساعدك في إنشاء عناصر مشتركة:

  • SharedTransitionLayout: التصميم الخارجي المطلوب لتنفيذ عمليات نقل العناصر المشتركة. يوفّر SharedTransitionScope. يجب أن تكون العناصر القابلة للتعديل في SharedTransitionScope لاستخدام عناصر تعديل العناصر المشتركة.
  • Modifier.sharedElement(): المُعدِّل الذي يُعلِم SharedTransitionScope بالعنصر القابل للتجميع الذي يجب مطابقته بعنصر قابل للتجميع آخر.
  • Modifier.sharedBounds(): المُعدِّل الذي يُعلم SharedTransitionScope بأنّه يجب استخدام حدود هذا المكوّن القابل للتجميع كحدود الحاوية التي يجب أن يحدث فيها الانتقال وعلى النقيض من sharedElement()، تم تصميم sharedBounds() للمحتوى المختلف مرئيًا.

من المفاهيم المهمة عند إنشاء العناصر المشتركة في Compose طريقة عملها مع العناصر المركّبة والاقتصاص. اطّلِع على قسم الاقتصاص والتراكبات للتعرّف على مزيد من المعلومات حول هذا الموضوع المهم.

الاستخدام الأساسي

سيتم إنشاء الانتقال التالي في هذا القسم، للانتقال من عنصر "القائمة" الأصغر، إلى العنصر التفصيلي الأكبر:

الشكل 2. مثال أساسي على انتقال عنصر مشترَك بين عنصرَين قابلَين للتجميع

وأفضل طريقة لاستخدام علامة Modifier.sharedElement() هي أن تستخدم الترميز AnimatedContent أو AnimatedVisibility أو NavHost لأنّها تدير عملية الانتقال بين العناصر القابلة للإنشاء تلقائيًا نيابةً عنك.

نقطة البداية هي AnimatedContent أساسي حالي يحتوي على MainContent وDetailsContent قابلَين للتركيب قبل إضافة عناصر مشترَكة:

الشكل 3. سيتم بدء AnimatedContent بدون أي عمليات نقل للعناصر المشتركة.

  1. لجعل العناصر المشتركة تتحرك بين التنسيقين، إحاطة AnimatedContent بالعنصر القابل للإنشاء باستخدام SharedTransitionLayout. يتم تمرير النطاقَين من SharedTransitionLayout وAnimatedContent إلى MainContent وDetailsContent:

    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. أضِف Modifier.sharedElement() إلى سلسلة التعديل القابلة للإنشاء على العنصرَين القابلَين للإنشاء المطابقَين. أنشئ كائن SharedContentState وتذكّره باستخدام rememberSharedContentState(). يحفظ الكائن SharedContentState المفتاح الفريد الذي يحدّد العناصر التي تتم مشاركتها. أدخِل مفتاحًا فريدًا لتحديد المحتوى، واستخدِم rememberSharedContentState() للعنصر الذي تريد تذكره. يتم تمرير AnimatedContentScope إلى المُعدّل، والذي يستخدم لتنسيق الحركة.

    @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

للحصول على معلومات حول ما إذا حدثت مطابقة لعنصر مشترَك، استخرِج rememberSharedContentState() في متغيّر وابحث عن isMatchFound.

ما ينتج عنه الحركة التلقائية التالية:

الشكل 4. مثال أساسي على انتقال عنصر مشترك بين عنصرَين قابلَين للإنشاء.

قد تلاحظ أنّ لون الخلفية وحجم الحاوية بالكامل لا يزالان يستخدمان إعدادات AnimatedContent التلقائية.

الحدود المشتركة في مقابل العنصر المشترَك

Modifier.sharedBounds() يشبه Modifier.sharedElement(). مع ذلك، تختلف المعدِّلات في الطرق التالية:

  • يُستخدَم sharedBounds() للمحتوى الذي يختلف من الناحية المرئية ولكن يجب أن يتضمّن المنطقة نفسها بين الولايات، في حين يتوقع sharedElement() أن يكون المحتوى متطابقًا.
  • باستخدام sharedBounds()، يكون المحتوى الذي يدخل الشاشة ويخرج منها مرئيًا أثناء الانتقال بين الحالتَين، في حين أنّه باستخدام sharedElement()، يتم عرض المحتوى المستهدَف فقط في حدود التحوّل . يحتوي Modifier.sharedBounds() على مَعلمتَي enter وexit لتحديد كيفية انتقال المحتوى، تمامًا مثل طريقة عمل AnimatedContent.
  • تتمثّل حالة الاستخدام الأكثر شيوعًا لعنصر sharedBounds() في نمط تحويل الحاوية ، في حين أنّ مثال حالة الاستخدام لعنصر sharedElement() هو انتقال العنصر الرئيسي.
  • عند استخدام العناصر القابلة للتجميع Text، يُفضَّل استخدام sharedBounds() لتفعيل ميزة تغييرات الخط، مثل الانتقال بين الخط المائل والخط الغامق أو تغييرات اللون.

من المثال السابق، ستتيح لنا إضافة Modifier.sharedBounds() إلى Row وColumn في السيناريوهين المختلفين مشاركة حدودهما وتنفيذ الحركة الانتقالية، ما يسمح لنا بالنمو بين بعضهما البعض:

@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

الشكل 5: الحدود المشتركة بين عنصرَي تركيب

فهم النطاقات

لاستخدام Modifier.sharedElement()، يجب أن يكون العنصر القابل للإنشاء في SharedTransitionScope. توفّر الوحدات القابلة للتجميع من النوع SharedTransitionLayout العناصر التالية: SharedTransitionScope. تأكد من وضعها في نفس نقطة المستوى الأعلى في التسلسل الهرمي لواجهة المستخدم الخاص بك والتي تحتوي على العناصر التي تريد مشاركتها.

بشكل عام، يجب أيضًا وضع العناصر القابلة للإنشاء في AnimatedVisibilityScope. يتم عادةً توفير ذلك باستخدام AnimatedContent للتبديل بين العناصر القابلة للتجميع أو عند استخدام AnimatedVisibility مباشرةً، أو باستخدام الدالة القابلة للتجميع NavHost، ما لم تكن تدير مستوى العرض يدويًا. ولاستخدام نطاقات متعددة، يمكنك حفظ النطاقات المطلوبة في SubscriptionLocal، أو استخدام أدوات استقبال السياق في Kotlin، أو تمرير النطاقات كمعلَمات إلى الدوال.

ويمكنك استخدام CompositionLocals في السيناريو الذي يكون لديك فيه نطاقات متعددة تريد تتبّعها، أو في تسلسل هرمي متداخل بشكل كبير. ويتيح لك CompositionLocal اختيار النطاقات المحدّدة لحفظها واستخدامها. ومن ناحية أخرى، عند استخدام أدوات استقبال السياق، قد تلغي التنسيقات الأخرى في التسلسل الهرمي النطاقات المتوفرة عن طريق الخطأ. على سبيل المثال، إذا كان لديك عدة AnimatedContent مدمَجة، يمكن إلغاء النطاقات.

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

بدلاً من ذلك، إذا لم يكن التسلسل الهرمي متداخلًا بشكل عميق، يمكنك تمرير النطاقات للأسفل كمَعلمات:

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

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

العناصر التي تمت مشاركتها مع "AnimatedVisibility"

عرضت الأمثلة السابقة كيفية استخدام العناصر المشتركة مع AnimatedContent، لكن العناصر المشتركة تعمل مع AnimatedVisibility أيضًا.

على سبيل المثال، في مثال الشبكة البطيئة هذا، يتم لف كل عنصر في AnimatedVisibility. عند النقر على العنصر، يكون للمحتوى التأثير المرئي لأنّه يتم سحبه من واجهة المستخدم إلى مكوّن شبيه بمربّع الحوار.

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(
                            state = rememberSharedContentState(key = snack.name),
                            animatedVisibilityScope = this@AnimatedVisibility
                        ),
                        onClick = {
                            selectedSnack = snack
                        }
                    )
                }
            }
        }
    }
    // Contains matching AnimatedContent with sharedBounds modifiers.
    SnackEditDetails(
        snack = selectedSnack,
        onConfirmClick = {
            selectedSnack = null
        }
    )
}
AnimatedVisibilitySharedElementSnippets.kt

الشكل 6: العناصر المشتركة مع AnimatedVisibility

ترتيب مفاتيح التعديل

من خلال Modifier.sharedElement() وModifier.sharedBounds()، يكون ترتيب سلسلة التعديل مهمًا، كما هو الحال مع بقية عناصر Compose. يمكن أن يتسبب الموضع غير الصحيح للمفاتيح التي تؤثر على الحجم في انتقال مرئي غير متوقع أثناء مطابقة العناصر المشتركة.

على سبيل المثال، إذا وضعت أداة تعديل المساحة المتروكة في موضع مختلف على عنصرين مشتركين، فهناك اختلاف مرئي في الرسوم المتحركة.

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

الحدود المطابقة

الحدود غير المطابقة: لاحظ أنّ الصورة المتحركة للعنصر المشترَك تظهر بشكل غير صحيح بعض الشيء لأنّه يجب تغيير حجمها لتتلاءم مع الحدود غير الصحيحة.

من خلال مفاتيح التعديل المستخدَمة قبل عناصر تعديل العناصر المشتركة، يتم فرض قيود على مفاتيح التعديل التي تتم مشاركتها، ويتم بعدها استخدام هذه القيود لاشتقاق الحدود الأولية والمستهدفة، وبالتالي رسم الحدود.

إنّ المُعدِّلات المستخدَمة بعد مُعدِّلات العناصر المشترَكة تستخدِم القيود من قبل لقياس واحتساب الحجم المستهدَف للعنصر الفرعي. تُنشئ عناصر تعديل العنصر المشترَك سلسلة من القيود المتحركة لتحويل العنصر التابع تدريجيًا من الحجم الأولي إلى الحجم المستهدَف.

ويستثنى من ذلك استخدام resizeMode = ScaleToBounds() للصورة المتحركة، أو Modifier.skipToLookaheadSize() في عنصر قابل للإنشاء. في هذه الحالة، يحدد Compose الطفل باستخدام القيود المستهدفة، ويستخدم بدلاً من ذلك عامل قياس لتنفيذ الرسوم المتحركة بدلاً من تغيير حجم التخطيط بنفسه.

المفاتيح الفريدة

عند العمل مع عناصر مشترَكة معقّدة، من الممارسات الجيدة إنشاء مفتاح ليس سلسلة، لأنّ السلاسل قد تكون عرضة للخطأ في المطابقة. يجب أن يكون كل مفتاح فريدًا لحدوث التطابقات. على سبيل المثال، في Jetsnack، لدينا يلي: العناصر المشتركة:

الشكل 7. صورة تعرض Jetsnack مع تعليقات توضيحية لكل جزء من واجهة المستخدم.

يمكنك إنشاء مصنّف للتمثيل نوع العنصر المشترَك. في هذا المثال، يمكن أن تظهر بطاقة الوجبات الخفيفة بأكملها أيضًا من عدة أماكن مختلفة على الشاشة الرئيسية، على سبيل المثال في القسم "محتوى رائج" وقسم "الفيديوهات المقترحة". يمكنك إنشاء مفتاح يتضمّن snackId وorigin ("رائج" / "مقترَح") وtype للعنصر المشترَك الذي ستتم مشاركته:

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() و isEquals().

إدارة مستوى ظهور العناصر المشتركة يدويًا

وفي الحالات التي لا تستخدم فيها AnimatedVisibility أو AnimatedContent، يمكنك إدارة إذن الوصول إلى العنصر المشترَك بنفسك. استخدِم Modifier.sharedElementWithCallerManagedVisibility() وأدخِل شرطك الخاص الذي يحدّد متى يجب أن يكون العنصر مرئيًا أو لا:

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

القيود الحالية

هناك بعض القيود على واجهات برمجة التطبيقات هذه. أبرزها:

  • لا تتوفّر إمكانية التشغيل التفاعلي بين طرق العرض وميزة "إنشاء". ويشمل ذلك أي عنصر قابل للتجميع يلف AndroidView، مثل Dialog.
  • لا تتوفّر ميزة الصور المتحركة التلقائية في ما يلي:
    • العناصر القابلة للتجميع من الصور المشتركة:
      • لا يكون ContentScale متحركًا تلقائيًا. يستقرّ مع الطرف المحدَّد ContentScale.
    • قص الأشكال - ليس هناك دعم مدمج لتحريك العنصر تلقائيًا بين الأشكال - على سبيل المثال، تحريك العناصر من مربع إلى دائرة أثناء انتقال العنصر.
    • بالنسبة إلى الحالات غير المتوافقة، استخدِم Modifier.sharedBounds() بدلاً من sharedElement() وأضِف Modifier.animateEnterExit() إلى العناصر.
التالي
تخصيص