TV için kaydırılabilir düzenler oluşturma

TV uygulamalarında göz atma deneyimi, odak tabanlı etkili gezinmeye dayanır. Standart Compose Foundation tembel düzenlerini kullanarak, odaklanmaya dayalı kaydırmayı otomatik olarak işleyen ve etkin öğeleri görünür tutan yüksek performanslı dikey ve yatay listeler oluşturabilirsiniz.

TV için optimize edilmiş varsayılan kaydırma davranışı

Compose Foundation 1.7.0'dan itibaren standart yavaş düzenler (ör. LazyRow ve LazyColumn), odak konumlandırma özellikleri için yerleşik destek içerir. Bu yöntem, odaklanılan öğelerin görünür kalmasına ve kullanıcı için sezgisel olarak konumlandırılmasına yardımcı olduğundan TV uygulamaları için katalog oluşturmanın önerilen yoludur.

Temel bir kaydırılabilir liste uygulamak için standart tembel bileşenleri kullanın. Bu bileşenler, D-pad ile gezinmeyi otomatik olarak işler ve odaklanılan öğeyi görünür hale getirir.

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 */ }
            )
        }
    }
}

BringIntoViewSpec ile kaydırma davranışını özelleştirme

Tasarımınızda belirli bir "pivot" noktası gerekiyorsa (örneğin, odaklanılan öğenin sol kenardan tam olarak% 30 uzakta olması) BringIntoViewSpec kullanarak kaydırma davranışını özelleştirebilirsiniz. Bu işlev, odaklanılan bir öğeyi barındırmak için görüntü alanının tam olarak nasıl kaydırılması gerektiğini tanımlamanıza olanak tanıyarak eski pivotOffsets işlevinin yerini alır.

1. Özel BringIntoViewSpec tanımlama

Aşağıdaki yardımcı composable, üst ve alt kesirlere göre bir "pivot" tanımlamanıza olanak tanır. parentFraction, öğenin kapsayıcıda nereye yerleştirileceğini, childFraction ise öğenin hangi bölümünün bu noktayla hizalanacağını belirler.

@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,
    )
}

2. Özel spesifikasyonu uygulama

Konumlandırmayı uygulamak için düzenlerinizi yardımcıyla sarmalayın. Bu özellik, kataloğunuzun farklı satırlarında "tutarlı bir odak çizgisi" oluşturmak için yararlıdır.

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 { ... }
        }
    }
}

3. Belirli iç içe yerleşimler için devre dışı bırakma

Özel pivotunuz yerine standart kaydırma davranışını kullanması gereken belirli bir iç içe yerleştirilmiş düzeniniz varsa DefaultBringIntoViewSpec değerini sağlayın:

private val DefaultBringIntoViewSpec = object : BringIntoViewSpec {}

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

Boş bir BringIntoViewSpec iletmek, çerçevenin varsayılan davranışının devreye girmesini sağlar.

TV Foundation'dan Compose Foundation'a geçiş

androidx.tv.foundation içindeki TV'ye özel tembel düzenler, standart Compose Foundation düzenleri lehine desteği sonlandırılmıştır.

Bağımlılık güncellemeleri

build.gradle'nızın aşağıdaki özellikler için 1.7.0 veya sonraki bir sürümü kullandığını doğrulayın:

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

Bileşen eşleme

Taşımak için içe aktarma işlemlerinizi güncelleyin ve bileşenlerinizdeki Tv önekini kaldırın:

Desteği sonlandırılmış TV bileşeni Compose Foundation'ın yerine geçen ürün
TvLazyRow LazyRow
TvLazyColumn LazyColumn
TvLazyHorizontalGrid LazyHorizontalGrid
TvLazyVerticalGrid LazyVerticalGrid
pivotOffsets BringIntoViewSpec (LocalBringIntoViewSpec üzerinden)