إنشاء تصاميم قابلة للتمرير على التلفزيون

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

تحسين سلوك التنقّل التلقائي للتلفزيون

بدءًا من الإصدار 1.7.0 من Compose Foundation، تتضمّن التنسيقات العادية التي تتيح التحميل الكسول (مثل LazyRow وLazyColumn) دعمًا مدمجًا لميزات تحديد موضع التركيز. هذه هي الطريقة المقترَحة لإنشاء قوائم لتطبيقات البث التلفزيوني لأنّها تساعد في إبقاء العناصر التي يتم التركيز عليها مرئية وموضوعة بشكل بديهي للمستخدم.

لتنفيذ قائمة أساسية قابلة للتمرير، استخدِم المكوّنات العادية للتحميل الكسول. تتعامل هذه المكوّنات تلقائيًا مع التنقّل باستخدام لوحة التحكّم وتعرض العنصر الذي يتم التركيز عليه.

import androidx.compose.foundation.lazy.LazyRow
import androidx.compose.foundation.lazy.items

@Composable
fun MovieCatalog(movies: List<Movie>) {
    LazyRow {
        items(movies) { movie ->
            MovieCard(
                movie = movie,
                onClick = { /* Handle click */ }
            )
        }
    }
}
Lists.kt

تخصيص سلوك الانتقال باستخدام BringIntoViewSpec

إذا كان تصميمك يتطلّب نقطة "محورية" معيّنة (على سبيل المثال، إبقاء العنصر الذي تم التركيز عليه على بُعد% 30 بالضبط من الحافة اليسرى)، يمكنك تخصيص سلوك الانتقال باستخدام BringIntoViewSpec. يحلّ هذا محلّ وظيفة pivotOffsets القديمة من خلال السماح لك بتحديد كيفية انتقال إطار العرض بدقة لاستيعاب عنصر مركّز.

1. تحديد BringIntoViewSpec مخصّص

تتيح لك الدالة المساعدة المركّبة التالية تحديد "نقطة محورية" استنادًا إلى الأجزاء الرئيسية والفرعية. تحدّد السمة parentFraction مكان وضع العنصر في الحاوية، وتحدّد السمة childFraction الجزء من العنصر الذي تتم محاذاته مع تلك النقطة.

@OptIn(ExperimentalFoundationApi::class)
@Composable
fun PositionFocusedItemInLazyLayout(
    parentFraction: Float = 0.3f,
    childFraction: Float = 0f,
    content: @Composable () -> Unit,
) {
    val bringIntoViewSpec = remember(parentFraction, childFraction) {
        object : BringIntoViewSpec {
            override fun calculateScrollDistance(
                offset: Float,       // Item's initial position
                size: Float,         // Item's size
                containerSize: Float // Container's size
            ): Float {
                // Calculate the offset position of the item's leading edge.
                val initialTargetForLeadingEdge =
                    parentFraction * containerSize - (childFraction * size)
                // If the item fits in the container, and scrolling would cause
                // its trailing edge to be clipped, adjust targetForLeadingEdge
                // to prevent over-scrolling near the end of list.
                val targetForLeadingEdge = if (size <= containerSize &&
                    (containerSize - initialTargetForLeadingEdge) < size) {
                    // If clipped, align the item's trailing edge with the
                    // container's trailing edge.
                    containerSize - size
                } else {
                    initialTargetForLeadingEdge
                }
                // Return scroll distance relative to initial item position.
                return offset - targetForLeadingEdge
            }
        }
    }

    // Apply the spec to all scrollables in the hierarchy
    CompositionLocalProvider(
        LocalBringIntoViewSpec provides bringIntoViewSpec,
        content = content,
    )
}
Lists.kt

2. تطبيق المواصفات المخصّصة

يمكنك تضمين التنسيقات في المساعد لتطبيق تحديد الموضع. ويُعدّ ذلك مفيدًا لإنشاء "خط تركيز متّسق" على مستوى الصفوف المختلفة في الكتالوج.

PositionFocusedItemInLazyLayout(
    parentFraction = 0.3f, // Pivot 30% from the edge
    childFraction = 0.5f   // Center of the item aligns with the pivot
) {
    LazyColumn {
        items(sectionList) { section ->
            // This row and its items will respect the 30% pivot
            LazyRow { /* ... */ }
        }
    }
}
Lists.kt

3- إيقاف التنسيقات المدمجة المحدّدة

إذا كان لديك تنسيق مدمج معيّن يجب أن يستخدم سلوك الانتقال العادي بدلاً من المحور المخصّص، يُرجى تقديم DefaultBringIntoViewSpec:

private val DefaultBringIntoViewSpec = object : BringIntoViewSpec {}

PositionFocusedItemInLazyLayout {
    LazyColumn {
        item {
            // This row will ignore the custom pivot and use default behavior
            CompositionLocalProvider(LocalBringIntoViewSpec provides DefaultBringIntoViewSpec) {
                LazyRow { /* ... */ }
            }
        }
    }
}
Lists.kt

في الواقع، من خلال تمرير BringIntoViewSpec فارغ، يتم تفعيل الإعداد التلقائي لإطار العمل.

نقل البيانات من TV Foundation إلى Compose Foundation

تم إيقاف التنسيقات الكسولة الخاصة بالتلفزيون في androidx.tv.foundation نهائيًا لصالح تنسيقات Compose Foundation العادية.

تحديثات التبعيات

تأكَّد من أنّ build.gradle يستخدم الإصدار 1.7.0 أو إصدارًا أحدث لما يلي:

• androidx.compose.foundation
• androidx.compose.runtime

ربط المكوّنات

للنقل، يُرجى تعديل عمليات الاستيراد وإزالة البادئة Tv من المكوّنات:

مكوّن تلفزيون متوقف نهائيًا	بديل Compose Foundation
TvLazyRow	LazyRow
TvLazyColumn	LazyColumn
TvLazyHorizontalGrid	LazyHorizontalGrid
TvLazyVerticalGrid	LazyVerticalGrid
pivotOffsets	BringIntoViewSpec (عبر LocalBringIntoViewSpec)