การเลื่อนแบบ 2 มิติ: scrollable2D, draggable2D

ใน Jetpack Compose, scrollable2D และ draggable2D เป็นตัวปรับแต่งระดับต่ำที่ออกแบบมาเพื่อจัดการอินพุตเคอร์เซอร์ใน 2 มิติ แม้ว่าตัวแก้ไข 1 มิติมาตรฐาน scrollable และ draggable จะจำกัดให้ใช้ได้เฉพาะการวางแนวเดียว แต่ตัวแปร 2 มิติจะติดตามการเคลื่อนไหวทั้งแกน X และแกน Y พร้อมกัน

ตัวอย่างเช่น ตัวแก้ไข scrollable ที่มีอยู่จะใช้สำหรับการเลื่อนและการเหวี่ยงในแนวเดียว ส่วน scrollable2d จะใช้สำหรับการเลื่อนและการเหวี่ยงในแบบ 2 มิติ ซึ่งจะช่วยให้คุณสร้างเลย์เอาต์ที่ซับซ้อนมากขึ้นซึ่งเลื่อนได้ทุกทิศทาง เช่น สเปรดชีตหรือโปรแกรมดูรูปภาพ ตัวแก้ไข scrollable2d ยังรองรับการเลื่อนที่ฝังในสถานการณ์ 2 มิติด้วย

รูปที่ 1 การเลื่อนแผนที่แบบ 2 ทิศทาง

เลือก scrollable2D หรือ draggable2D

การเลือก API ที่เหมาะสมขึ้นอยู่กับองค์ประกอบ UI ที่คุณต้องการย้ายและลักษณะการทำงานทางกายภาพที่ต้องการสำหรับองค์ประกอบเหล่านี้

Modifier.scrollable2D: ใช้ตัวแก้ไขนี้กับคอนเทนเนอร์เพื่อย้ายเนื้อหาภายใน เช่น ใช้กับแผนที่ สเปรดชีต หรือโปรแกรมดูรูปภาพ ซึ่งเนื้อหาของคอนเทนเนอร์ต้องเลื่อนทั้งในแนวนอนและแนวตั้ง ซึ่งรวมถึงการรองรับการปัดในตัวเพื่อให้เนื้อหาเคลื่อนไหวต่อไปหลังจากปัด และประสานงานกับคอมโพเนนต์การเลื่อนอื่นๆ ในหน้า

Modifier.draggable2D: ใช้ตัวแก้ไขนี้เพื่อย้ายคอมโพเนนต์เอง ซึ่งเป็นตัวปรับแต่งที่ใช้ทรัพยากรน้อย การเคลื่อนไหวจึงหยุดลงทันทีที่นิ้วของผู้ใช้หยุด แต่ไม่รวมการรองรับการส่งเนื้อหา

หากต้องการทำให้คอมโพเนนต์ลากได้ แต่ไม่ต้องการการรองรับการเหวี่ยงหรือการเลื่อนที่ฝังอยู่ ให้ใช้ draggable2D

ใช้ตัวปรับแต่ง 2 มิติ

ส่วนต่อไปนี้จะแสดงตัวอย่างวิธีใช้ตัวแก้ไข 2 มิติ

การใช้งาน Modifier.scrollable2D

ใช้ตัวปรับแต่งนี้กับคอนเทนเนอร์ที่ผู้ใช้ต้องย้ายเนื้อหาไปในทุกทิศทาง

บันทึกข้อมูลการเคลื่อนไหวแบบ 2 มิติ

ตัวอย่างนี้แสดงวิธีบันทึกข้อมูลการเคลื่อนไหว 2 มิติแบบข้อมูลดิบและแสดงออฟเซ็ต 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()}",
                    // ...
                )
            }
        }
    }
}
TwoDimensionalScrollSnippets.kt

รูปที่ 2 กล่องสีม่วงที่ติดตามและแสดงออฟเซ็ตพิกัด X และ Y ปัจจุบันขณะที่ผู้ใช้ลากตัวชี้ไปทั่วพื้นผิว

ข้อมูลโค้ดก่อนหน้าจะทําสิ่งต่อไปนี้

• ใช้ offset เป็นสถานะที่เก็บระยะทางทั้งหมดที่ผู้ใช้เลื่อน
• ภายใน rememberScrollable2DState จะมีการกำหนดฟังก์ชัน Lambda เพื่อจัดการเดลต้าทุกรายการที่สร้างขึ้นโดยนิ้วของผู้ใช้ โค้ด offset.value += delta จะอัปเดตสถานะด้วยตนเองด้วยตำแหน่งใหม่
• คอมโพเนนต์ Text จะแสดงค่า X และ Y ปัจจุบันของสถานะ offset นั้น ซึ่งจะอัปเดตแบบเรียลไทม์เมื่อผู้ใช้ลาก

เลื่อนวิวพอร์ตขนาดใหญ่

ตัวอย่างนี้แสดงวิธีใช้ข้อมูลที่เลื่อนได้แบบ 2 มิติที่บันทึกไว้ และใช้ translationX และ translationY กับเนื้อหาที่มีขนาดใหญ่กว่าคอนเทนเนอร์หลัก

@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
        )
    }
}
TwoDimensionalScrollSnippets.kt

รูปที่ 3 วิวพอร์ตรูปภาพแบบเลื่อนได้ 2 ทิศทางที่สร้างด้วย Modifier.scrollable2D

รูปที่ 4 วิวพอร์ตข้อความแบบเลื่อน 2 ทิศทางที่สร้างด้วย Modifier.scrollable2D

ข้อมูลโค้ดก่อนหน้าประกอบด้วยข้อมูลต่อไปนี้

• คอนเทนเนอร์ได้รับการตั้งค่าเป็นขนาดคงที่ (600x400dp) ในขณะที่เนื้อหาได้รับขนาดที่ใหญ่กว่ามาก (1200x800dp) เพื่อหลีกเลี่ยงไม่ให้ปรับขนาดเป็นขนาดระดับบนสุด
• ตัวแก้ไข clipToBounds() ในคอนเทนเนอร์ช่วยให้มั่นใจว่าส่วนใดก็ตามของเนื้อหาขนาดใหญ่ที่อยู่นอกกล่อง 600x400 จะถูกซ่อนจากมุมมอง
• scrollable2D จะไม่ย้ายเนื้อหาให้คุณโดยอัตโนมัติ ซึ่งต่างจากคอมโพเนนต์ระดับสูงอย่าง LazyColumn แต่คุณต้องใช้ offset ที่ติดตามกับเนื้อหาแทน โดยใช้การเปลี่ยนรูปแบบ graphicsLayer หรือออฟเซ็ตเลย์เอาต์
• ภายในบล็อก graphicsLayer translationX = offset.value.x และ translationY = offset.value.y จะเปลี่ยนตำแหน่งการวาดของรูปภาพหรือข้อความตามการเคลื่อนไหวของนิ้ว ซึ่งจะสร้างเอฟเฟกต์ภาพของการเลื่อน

ใช้การเลื่อนที่ฝังด้วย scrollable2D

ตัวอย่างนี้แสดงวิธีผสานรวมคอมโพเนนต์แบบ 2 ทิศทางเข้ากับคอมโพเนนต์หลักแบบมิติเดียวมาตรฐาน เช่น ฟีดข่าวแนวตั้ง

โปรดคำนึงถึงประเด็นต่อไปนี้เมื่อใช้การเลื่อนที่ซ้อนกัน

• แลมบ์ดาสำหรับ rememberScrollable2DState ควรแสดงเฉพาะเดลต้าที่ใช้ไป เพื่อให้รายการหลักรับช่วงต่อตามธรรมชาติเมื่อรายการย่อยถึงขีดจำกัด
• เมื่อผู้ใช้ทำการเหวี่ยงในแนวทแยง ระบบจะแชร์ความเร็ว 2 มิติ หากองค์ประกอบย่อยถึงขอบเขตระหว่างภาพเคลื่อนไหว โมเมนตัมที่เหลือจะส่งต่อไปยังองค์ประกอบหลักเพื่อให้เลื่อนต่อไปได้อย่างเป็นธรรมชาติ

@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)
        )
    }
}
TwoDimensionalScrollSnippets.kt

รูปที่ 5 กล่องสีม่วงภายในรายการเลื่อนแนวตั้งที่อนุญาตให้มีการเคลื่อนไหวแบบ 2 มิติภายใน แต่ส่งผ่านการควบคุมการเลื่อนแนวตั้งไปยังรายการหลักเมื่อออฟเซ็ต Y ภายในของกล่องถึงขีดจำกัด 300 พิกเซล

ในข้อมูลโค้ดก่อนหน้า

• คอมโพเนนต์ 2 มิติสามารถใช้การเคลื่อนไหวแกน X เพื่อเลื่อนภายในขณะที่ส่งการเคลื่อนไหวแกน Y ไปยังรายการหลักพร้อมกันเมื่อถึงขอบเขตแนวตั้งของรายการย่อยเอง
• แทนที่จะดักผู้ใช้ไว้ภายในพื้นผิว 2 มิติ ระบบจะคำนวณเดลต้าที่ใช้ไปและส่งส่วนที่เหลือขึ้นไปตามลำดับชั้น ซึ่งจะช่วยให้ผู้ใช้เลื่อนดูส่วนที่เหลือของหน้าต่อไปได้โดยไม่ต้องยกนิ้วขึ้น

การใช้งาน Modifier.draggable2D

ดูข้อมูลเกี่ยวกับวิธีใช้ Modifier.draggable2D ได้ที่ลากใน 2 มิติด้วย Modifier.draggable2D