Trong Jetpack Compose, scrollable2D và draggable2D là các đối tượng sửa đổi cấp thấp được thiết kế để xử lý hoạt động nhập bằng con trỏ theo hai chiều. Trong khi các đối tượng sửa đổi 1D tiêu chuẩn scrollable và draggable bị giới hạn ở một hướng duy nhất, thì các biến thể 2D theo dõi chuyển động trên cả hai trục X và Y cùng một lúc.
Ví dụ: đối tượng sửa đổi scrollable hiện có được dùng để cuộn và vuốt theo một hướng, trong khi scrollable2d được dùng để cuộn và vuốt theo 2D. Điều này cho phép bạn tạo các bố cục phức tạp hơn, di chuyển theo mọi hướng, chẳng hạn như bảng tính hoặc trình xem hình ảnh. Đối tượng sửa đổi scrollable2d cũng hỗ trợ thao tác cuộn lồng nhau trong các trường hợp 2D.
Chọn scrollable2D hoặc draggable2D
Việc chọn API phù hợp phụ thuộc vào các phần tử trên giao diện người dùng mà bạn muốn di chuyển và hành vi vật lý ưu tiên cho các phần tử này.
Modifier.scrollable2D: Sử dụng đối tượng sửa đổi này trên một vùng chứa để di chuyển nội dung bên trong vùng chứa đó. Ví dụ: sử dụng thành phần này với bản đồ, bảng tính hoặc chế độ xem ảnh, trong đó nội dung của vùng chứa cần cuộn theo cả hướng ngang và dọc. Thành phần này tích hợp sẵn tính năng hỗ trợ vuốt nhanh để nội dung tiếp tục di chuyển sau khi vuốt, đồng thời phối hợp với các thành phần cuộn khác trên trang.
Modifier.draggable2D: Sử dụng đối tượng sửa đổi này để di chuyển chính thành phần. Đây là một đối tượng sửa đổi gọn nhẹ, vì vậy, chuyển động sẽ dừng chính xác khi ngón tay của người dùng dừng lại. Thành phần này không hỗ trợ thao tác hất.
Nếu bạn muốn đặt một thành phần ở chế độ có thể kéo nhưng không cần hỗ trợ thao tác hất hoặc cuộn lồng nhau, hãy sử dụng draggable2D.
Triển khai đối tượng sửa đổi 2D
Các phần sau đây cung cấp ví dụ minh hoạ cách sử dụng đối tượng sửa đổi 2D.
Triển khai Modifier.scrollable2D
Sử dụng đối tượng sửa đổi này cho các vùng chứa mà người dùng cần di chuyển nội dung theo mọi hướng.
Ghi lại dữ liệu chuyển động 2D
Ví dụ này cho thấy cách thu thập dữ liệu chuyển động 2D thô và hiển thị độ lệch X,Y:
@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()}", // ... ) } } } }
Đoạn mã trước đó thực hiện những việc sau:
- Sử dụng
offsetlàm trạng thái lưu giữ tổng khoảng cách mà người dùng đã cuộn. - Bên trong
rememberScrollable2DState, một hàm lambda được xác định để xử lý mọi delta do ngón tay của người dùng tạo ra. Mãoffset.value += deltacập nhật trạng thái thủ công bằng vị trí mới. - Các thành phần
Texthiển thị giá trị X và Y hiện tại của trạng tháioffsetđó, cập nhật theo thời gian thực khi người dùng kéo.
Lia khung nhìn lớn
Ví dụ này cho thấy cách sử dụng dữ liệu có thể cuộn 2D đã chụp và áp dụng translationX và translationY cho nội dung lớn hơn vùng chứa mẹ:
@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.Modifier.scrollable2D.Đoạn mã trước đó bao gồm:
- Vùng chứa được đặt thành kích thước cố định (
600x400dp), trong khi nội dung được đặt thành kích thước lớn hơn nhiều (1200x800dp) để tránh việc nội dung đổi kích thước thành kích thước của vùng chứa mẹ. - Đối tượng sửa đổi
clipToBounds()trên vùng chứa đảm bảo rằng mọi phần của nội dung lớn nằm ngoài hộp600x400đều bị ẩn khỏi khung hiển thị. - Không giống như các thành phần cấp cao như
LazyColumn,scrollable2Dkhông tự động di chuyển nội dung cho bạn. Thay vào đó, bạn phải áp dụngoffsetđược theo dõi cho nội dung của mình, bằng cách sử dụng phép biến đổigraphicsLayerhoặc độ lệch bố cục. - Bên trong khối
graphicsLayer,translationX = offset.value.xvàtranslationY = offset.value.ysẽ dịch chuyển vị trí vẽ của hình ảnh hoặc văn bản dựa trên chuyển động của ngón tay, tạo ra hiệu ứng hình ảnh khi cuộn.
Triển khai thao tác cuộn lồng nhau bằng scrollable2D
Ví dụ này minh hoạ cách tích hợp một thành phần hai chiều vào một thành phần mẹ một chiều tiêu chuẩn, chẳng hạn như nguồn cấp tin tức dọc.
Hãy lưu ý những điểm sau khi triển khai tính năng cuộn lồng nhau:
- Hàm lambda cho
rememberScrollable2DStatechỉ nên trả về delta đã sử dụng để cho phép danh sách mẹ tiếp quản một cách tự nhiên khi danh sách con đạt đến giới hạn. - Khi người dùng thực hiện thao tác vuốt nhanh theo đường chéo, vận tốc 2D sẽ được chia sẻ. Nếu thành phần con chạm đến ranh giới trong ảnh động, thì động lượng còn lại sẽ được truyền đến thành phần mẹ để tiếp tục cuộn một cách tự nhiên.
@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) ) } }
Trong đoạn mã trước:
- Thành phần 2D có thể sử dụng chuyển động của trục X để kéo và di chuyển nội bộ, đồng thời gửi chuyển động của trục Y đến danh sách mẹ sau khi đạt đến ranh giới dọc của thành phần con.
- Thay vì giữ người dùng trong nền tảng 2D, hệ thống sẽ tính toán delta đã sử dụng và chuyển phần còn lại lên hệ phân cấp. Điều này đảm bảo người dùng có thể tiếp tục cuộn qua phần còn lại của trang mà không cần nhấc ngón tay lên.
Triển khai Modifier.draggable2D
Để biết thông tin về cách sử dụng Modifier.draggable2D, hãy xem bài viết Kéo theo hai chiều bằng Modifier.draggable2D.