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ümde 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 lazy bileşenlerini 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ı (ör. odaklanılan öğenin sol kenardan tam olarak% 30 uzaklıkta olması) gerekiyorsa BringIntoViewSpec kullanarak kaydırma davranışını özelleştirebilirsiniz. Bu özellik, 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, aslında çerçevenin varsayılan davranışının devreye girmesini sağlar.

TV Foundation'dan Compose Foundation'a taşıma

androidx.tv.foundation içindeki TV'ye özel tembel düzenler, standart Compose Foundation düzenleri lehine kullanımdan kaldırıldı.

Bağımlılık güncellemeleri

build.gradle cihazı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şenlerinizden Tv önekini kaldırın:

Kullanımdan kaldırılan TV bileşeni Compose Foundation'ın yerine geçen ürün
TvLazyRow LazyRow
TvLazyColumn LazyColumn
TvLazyHorizontalGrid LazyHorizontalGrid
TvLazyVerticalGrid LazyVerticalGrid
pivotOffsets BringIntoViewSpec (LocalBringIntoViewSpec üzerinden)