Jetpack Compose'da scrollable2D ve draggable2D, işaretçi girişini iki boyutta işlemek için tasarlanmış alt düzey değiştiricilerdir. Standart 1D değiştiriciler scrollable ve draggable tek bir yönle sınırlıyken 2D varyantlar hem X hem de Y eksenindeki hareketi aynı anda izler.
Örneğin, mevcut scrollable değiştiricisi tek yönlü kaydırma ve fırlatma için kullanılırken scrollable2d, 2D'de kaydırma ve fırlatma için kullanılır. Bu sayede, e-tablolar veya resim görüntüleyiciler gibi her yöne hareket eden daha karmaşık düzenler oluşturabilirsiniz. scrollable2d değiştirici, 2D senaryolarda iç içe yerleştirilmiş kaydırmayı da destekler.
scrollable2D veya draggable2D seçeneğini belirleyin
Doğru API'yi seçmek, taşımak istediğiniz kullanıcı arayüzü öğelerine ve bu öğeler için tercih edilen fiziksel davranışa bağlıdır.
Modifier.scrollable2D: İçeriği taşımak için bu değiştiriciyi bir kapsayıcıda kullanın. Örneğin, kapsayıcı içeriğinin hem yatay hem de dikey yönde kaydırılması gereken haritalar, e-tablolar veya fotoğraf görüntüleyicilerle kullanın. Kaydırma işleminden sonra içeriğin hareket etmeye devam etmesini sağlayan yerleşik kaydırma desteği içerir ve sayfadaki diğer kaydırma bileşenleriyle uyumludur.
Modifier.draggable2D: Bir bileşeni taşımak için bu değiştiriciyi kullanın. Bu, hafif bir değiştiricidir. Bu nedenle, kullanıcının parmağı durduğunda hareket de tam olarak durur. Fling desteği yoktur.
Bir bileşeni sürüklenebilir hale getirmek istiyorsanız ancak kaydırma veya iç içe yerleştirilmiş kaydırma desteğine ihtiyacınız yoksa draggable2D kullanın.
2D değiştiricileri uygulama
Aşağıdaki bölümlerde, 2D değiştiricilerin nasıl kullanılacağını gösteren örnekler verilmiştir.
Modifier.scrollable2D uygulayın
Kullanıcının içeriği her yöne taşıması gereken kapsayıcılar için bu değiştiriciyi kullanın.
2D hareket verilerini yakalama
Bu örnekte, ham 2D hareket verilerinin nasıl yakalanacağı ve X,Y ofsetinin nasıl gösterileceği açıklanmaktadır:
@Composable private fun Scrollable2DSample() { // 1. Manually track the total distance the user has moved in both X and Y directions var offset by remember { mutableStateOf(Offset.Zero) } Box( modifier = Modifier .fillMaxSize() // ... contentAlignment = Alignment.Center ) { Box( modifier = Modifier .size(200.dp) // 2. Attach the 2D scroll logic to capture XY movement deltas .scrollable2D( state = rememberScrollable2DState { delta -> // 3. Update the cumulative offset state with the new movement delta offset += delta // Return the delta to indicate the entire movement was handled by this box delta } ) // ... contentAlignment = Alignment.Center ) { Column(horizontalAlignment = Alignment.CenterHorizontally) { // 4. Display the current X and Y values from the offset state in real-time Text( text = "X: ${offset.x.roundToInt()}", // ... ) Spacer(modifier = Modifier.height(8.dp)) Text( text = "Y: ${offset.y.roundToInt()}", // ... ) } } } }
Yukarıdaki snippet şunları yapar:
- Kullanıcının kaydırdığı toplam mesafeyi tutan bir durum olarak
offsetkullanılır. rememberScrollable2DStateiçinde, kullanıcının parmağıyla oluşturulan her delta değerini işlemek için bir lambda işlevi tanımlanır.offset.value += deltakodu, manuel durumu yeni konumla günceller.Textbileşenleri, kullanıcının sürüklemesiyle gerçek zamanlı olarak güncellenenoffsetdurumunun mevcut X ve Y değerlerini gösterir.
Büyük bir görüntü alanını kaydırma
Bu örnekte, yakalanan 2D kaydırılabilir verilerin nasıl kullanılacağı ve üst kapsayıcısından daha büyük olan içeriğe translationX ve translationY öğelerinin nasıl uygulanacağı gösterilmektedir:
@Composable private fun Panning2DImage() { // Manually track the total distance the user has moved in both X and Y directions val offset = remember { mutableStateOf(Offset.Zero) } // Define how gestures are captured. The lambda is called for every finger movement val scrollState = rememberScrollable2DState { delta -> offset.value += delta delta } // The Viewport (Container): A fixed-size box that acts as a window into the larger content Box( modifier = Modifier .size(600.dp, 400.dp) // The visible area dimensions // ... // Hide any parts of the large content that sit outside this container's boundaries .clipToBounds() // Apply the 2D scroll modifier to intercept touch and fling gestures in all directions .scrollable2D(state = scrollState), contentAlignment = Alignment.Center, ) { // The Content: An image given a much larger size than the container viewport Image( painter = painterResource(R.drawable.cheese_5), contentDescription = null, modifier = Modifier .requiredSize(1200.dp, 800.dp) // Manual Scroll Effect: Since scrollable2D doesn't move content automatically, // we use graphicsLayer to shift the drawing position based on the tracked offset. .graphicsLayer { translationX = offset.value.x translationY = offset.value.y }, contentScale = ContentScale.FillBounds ) } }
Modifier.scrollable2D ile oluşturulan, çift yönlü kaydırma özellikli resim görüntüleme alanı.Modifier.scrollable2D ile oluşturulan, iki yönlü kaydırılabilir metin görüntüleme alanı.Yukarıdaki snippet'te şunlar yer alır:
- Kapsayıcı sabit bir boyuta (
600x400dp) ayarlanmışken içeriğe, üst öğe boyutuna yeniden boyutlandırılmasını önlemek için çok daha büyük bir boyut (1200x800dp) veriliyor. - Kapsayıcıdaki
clipToBounds()değiştiricisi,600x400kutusunun dışında kalan büyük içeriğin herhangi bir bölümünün görünümden gizlenmesini sağlar. LazyColumngibi üst düzey bileşenlerin aksinescrollable2D, içeriği sizin için otomatik olarak taşımaz. Bunun yerine,graphicsLayerdönüşümlerini veya düzen ofsetlerini kullanarak izlenenoffsetöğesini içeriğinize uygulamanız gerekir.graphicsLayerbloğunun içinde,translationX = offset.value.xvetranslationY = offset.value.y, parmağınızın hareketine göre resmin veya metnin çizim konumunu değiştirerek kaydırma görsel efektini oluşturur.
scrollable2D ile iç içe yerleştirilmiş kaydırma uygulama
Bu örnekte, çift yönlü bir bileşenin dikey bir haber feed'i gibi standart tek boyutlu bir üst öğeye nasıl entegre edilebileceği gösterilmektedir.
İç içe yerleştirilmiş kaydırma özelliğini uygularken aşağıdaki noktaları göz önünde bulundurun:
rememberScrollable2DStateiçin lambda, çocuğun sınırına ulaştığında üst listenin doğal olarak devralmasına olanak tanımak için yalnızca tüketilen delta değerini döndürmelidir.- Kullanıcı çapraz kaydırma yaptığında 2D hız paylaşılır. Alt öğe, animasyon sırasında bir sınıra ulaşırsa kalan momentum, kaydırma işleminin doğal bir şekilde devam etmesi için üst öğeye yayılır.
@Composable private fun NestedScrollable2DSample() { var offset by remember { mutableStateOf(Offset.Zero) } val maxScrollDp = 250.dp val maxScrollPx = with(LocalDensity.current) { maxScrollDp.toPx() } Column( modifier = Modifier .fillMaxSize() .verticalScroll(rememberScrollState()) .background(Color(0xFFF5F5F5)), horizontalAlignment = Alignment.CenterHorizontally ) { Text( "Scroll down to find the 2D Box", modifier = Modifier.padding(top = 100.dp, bottom = 500.dp), style = TextStyle(fontSize = 18.sp, color = Color.Gray) ) // The Child: A 2D scrollable box with nested scroll coordination Box( modifier = Modifier .size(250.dp) .scrollable2D( state = rememberScrollable2DState { delta -> val oldOffset = offset // Calculate new potential offset and clamp it to our boundaries val newX = (oldOffset.x + delta.x).coerceIn(-maxScrollPx, maxScrollPx) val newY = (oldOffset.y + delta.y).coerceIn(-maxScrollPx, maxScrollPx) val newOffset = Offset(newX, newY) // Calculate exactly how much was consumed by the child val consumed = newOffset - oldOffset offset = newOffset // IMPORTANT: Return ONLY the consumed delta. // The remaining (unconsumed) delta propagates to the parent Column. consumed } ) // ... contentAlignment = Alignment.Center ) { Column(horizontalAlignment = Alignment.CenterHorizontally) { val density = LocalDensity.current Text("2D Panning Zone", color = Color.White.copy(alpha = 0.7f), fontSize = 12.sp) Spacer(Modifier.height(8.dp)) Text("X: ${with(density) { offset.x.toDp().value.roundToInt() }}dp", color = Color.White, fontWeight = FontWeight.Bold) Text("Y: ${with(density) { offset.y.toDp().value.roundToInt() }}dp", color = Color.White, fontWeight = FontWeight.Bold) } } Text( "Once the Purple Box hits Y: 250 or -250,\nthis parent list will take over the vertical scroll.", textAlign = TextAlign.Center, modifier = Modifier.padding(top = 40.dp, bottom = 800.dp), style = TextStyle(fontSize = 14.sp, color = Color.Gray) ) } }
Önceki snippet'te:
- 2D bileşen, dahili olarak kaydırmak için X ekseni hareketini kullanabilir. Aynı zamanda, alt öğenin kendi dikey sınırlarına ulaşıldığında Y ekseni hareketini üst öğe listesine gönderebilir.
- Sistem, kullanıcıyı 2D yüzeyde tutmak yerine tüketilen delta değerini hesaplar ve kalanı hiyerarşide yukarıya geçirir. Bu sayede kullanıcı, parmağını kaldırmadan sayfanın geri kalanında kaydırmaya devam edebilir.
Modifier.draggable2D uygulayın
Modifier.draggable2D simgesini kullanma hakkında bilgi edinmek için Modifier.draggable2D ile iki boyutta sürükleme başlıklı makaleyi inceleyin.