Đối tượng sửa đổi cho thao tác cuộn

Lưu ý: Nếu bạn muốn hiển thị một danh sách các mục, hãy cân nhắc sử dụng LazyColumn và LazyRow thay vì các API này. LazyColumn và LazyRow có tính năng cuộn, đồng thời hiệu quả hơn nhiều so với phương thức sửa đổi chức năng cuộn vì chúng chỉ tạo các mục khi cần thiết. Vui lòng xem Tài liệu về lưới và danh sách để biết thêm thông tin chi tiết.

Đối tượng sửa đổi verticalScroll và horizontalScroll cung cấp cách đơn giản nhất để người dùng cuộn một phần tử khi nội dung của phần tử đó lớn hơn giới hạn kích thước tối đa. Với phương thức sửa đổi verticalScroll và horizontalScroll, bạn không cần dịch hoặc bù trừ phần nội dung.

@Composable
private fun ScrollBoxes() {
    Column(
        modifier = Modifier
            .background(Color.LightGray)
            .size(100.dp)
            .verticalScroll(rememberScrollState())
    ) {
        repeat(10) {
            Text("Item $it", modifier = Modifier.padding(2.dp))
        }
    }
}
GesturesSnippets.kt

Hình 1. Một danh sách theo chiều dọc đang phản hồi lại cử chỉ cuộn.

ScrollState cho phép bạn thay đổi vị trí thanh cuộn hoặc xem trạng thái hiện tại của vị trí thanh cuộn. Để tạo lớp này với các tham số mặc định, hãy sử dụng rememberScrollState().

@Composable
private fun ScrollBoxesSmooth() {
    // Smoothly scroll 100px on first composition
    val state = rememberScrollState()
    LaunchedEffect(Unit) { state.animateScrollTo(100) }

    Column(
        modifier = Modifier
            .background(Color.LightGray)
            .size(100.dp)
            .padding(horizontal = 8.dp)
            .verticalScroll(state)
    ) {
        repeat(10) {
            Text("Item $it", modifier = Modifier.padding(2.dp))
        }
    }
}
GesturesSnippets.kt

Đối tượng sửa đổi cho vùng có thể cuộn

Đối tượng sửa đổi scrollableArea là một thành phần cơ bản để tạo vùng chứa có thể cuộn tuỳ chỉnh. Thành phần này cung cấp một lớp trừu tượng cấp cao hơn đối với đối tượng sửa đổi scrollable, xử lý các yêu cầu phổ biến như diễn giải delta cử chỉ, cắt nội dung và hiệu ứng cuộn quá mức.

Mặc dù scrollableArea được dùng cho các phương thức triển khai tuỳ chỉnh, nhưng nhìn chung, bạn nên ưu tiên các giải pháp có sẵn như verticalScroll, horizontalScroll hoặc các thành phần kết hợp như LazyColumn cho danh sách cuộn chuẩn. Các thành phần cấp cao hơn này đơn giản hơn cho các trường hợp sử dụng phổ biến và được xây dựng bằng cách sử dụng scrollableArea.

Sự khác biệt giữa đối tượng sửa đổi scrollableArea và scrollable

Sự khác biệt chính giữa scrollableArea và scrollable nằm ở cách các thành phần này diễn giải cử chỉ cuộn của người dùng:

• scrollable (delta thô): Delta phản ánh trực tiếp chuyển động vật lý của hoạt động đầu vào của người dùng (ví dụ: kéo con trỏ) trên màn hình.
• scrollableArea (delta hướng nội dung): delta được đảo ngược về mặt ngữ nghĩa để thể hiện thay đổi đã chọn ở vị trí cuộn, giúp nội dung có vẻ như di chuyển theo cử chỉ của người dùng, thường ngược với chuyển động của con trỏ.

Hãy nghĩ theo cách này: scrollable cho bạn biết cách con trỏ di chuyển, trong khi scrollableArea chuyển đổi chuyển động của con trỏ đó thành cách nội dung sẽ di chuyển trong một khung hiển thị có thể cuộn thông thường. Sự đảo ngược này là lý do khiến scrollableArea có cảm giác tự nhiên hơn khi triển khai vùng chứa có thể cuộn tiêu chuẩn.

Bảng sau đây tóm tắt các dấu hiệu delta cho các trường hợp phổ biến:

Cử chỉ của người dùng	delta được scrollable báo cáo cho dispatchRawDelta	mức chênh lệch do scrollableArea báo cáo cho dispatchRawDelta*
Con trỏ di chuyển LÊN	Negative	Tích cực
Con trỏ di chuyển XUỐNG	Tích cực	Negative
Con trỏ di chuyển sang TRÁI	Negative	Dương (Âm đối với RTL)
Con trỏ di chuyển sang PHẢI	Tích cực	Âm (Dương đối với RTL)

(*) Lưu ý về scrollableArea dấu delta: Dấu delta từ scrollableArea không chỉ là một phép đảo ngược đơn giản. Công cụ này xem xét một cách thông minh:

1. Hướng: Dọc hoặc ngang.
2. LayoutDirection: LTR hoặc RTL (đặc biệt quan trọng đối với thao tác cuộn ngang).
3. Cờ reverseScrolling: Cho biết hướng cuộn có bị đảo ngược hay không.

Ngoài việc đảo ngược delta cuộn, scrollableArea cũng cắt bớt nội dung theo ranh giới của bố cục và xử lý việc kết xuất hiệu ứng cuộn quá mức. Theo mặc định, hàm này sử dụng hiệu ứng do LocalOverscrollFactory cung cấp. Bạn có thể tuỳ chỉnh hoặc tắt tính năng này bằng cách sử dụng phương thức nạp chồng scrollableArea chấp nhận tham số OverscrollEffect.

Trường hợp sử dụng đối tượng sửa đổi scrollableArea

Bạn nên sử dụng đối tượng sửa đổi scrollableArea khi cần tạo một thành phần cuộn tuỳ chỉnh mà các đối tượng sửa đổi horizontalScroll hoặc verticalScroll hoặc bố cục Lazy không đáp ứng được. Điều này thường liên quan đến các trường hợp có:

• Logic bố cục tuỳ chỉnh: Khi cách sắp xếp các mục thay đổi linh động dựa trên vị trí cuộn.
• Hiệu ứng hình ảnh độc đáo: Áp dụng các phép biến đổi, điều chỉnh tỷ lệ hoặc các hiệu ứng khác cho các thành phần con khi chúng cuộn.
• Kiểm soát trực tiếp: Cần kiểm soát chi tiết cơ chế cuộn ngoài những gì verticalScroll hoặc bố cục Lazy hiển thị.

Tạo danh sách tuỳ chỉnh giống như bánh xe bằng scrollableArea

Mẫu sau đây minh hoạ cách sử dụng scrollableArea để tạo danh sách dọc tuỳ chỉnh, trong đó các mục thu nhỏ khi di chuyển ra xa trung tâm, tạo hiệu ứng hình ảnh "giống như bánh xe". Kiểu biến đổi phụ thuộc vào thao tác cuộn này là một trường hợp sử dụng hoàn hảo cho scrollableArea.

Hình 2. Danh sách dọc tuỳ chỉnh sử dụng scrollableArea.

@Composable
private fun ScrollableAreaSample() {
    // ...
    Layout(
        modifier =
            Modifier
                .size(150.dp)
                .scrollableArea(scrollState, Orientation.Vertical)
                .background(Color.LightGray),
        // ...
    ) { measurables, constraints ->
        // ...
        // Update the maximum scroll value to not scroll beyond limits and stop when scroll
        // reaches the end.
        scrollState.maxValue = (totalHeight - viewportHeight).coerceAtLeast(0)

        // Position the children within the layout.
        layout(constraints.maxWidth, viewportHeight) {
            // The current vertical scroll position, in pixels.
            val scrollY = scrollState.value
            val viewportCenterY = scrollY + viewportHeight / 2

            var placeableLayoutPositionY = 0
            placeables.forEach { placeable ->
                // This sample applies a scaling effect to items based on their distance
                // from the center, creating a wheel-like effect.
                // ...
                // Place the item horizontally centered with a layer transformation for
                // scaling to achieve wheel-like effect.
                placeable.placeRelativeWithLayer(
                    x = constraints.maxWidth / 2 - placeable.width / 2,
                    // Offset y by the scroll position to make placeable visible in the viewport.
                    y = placeableLayoutPositionY - scrollY,
                ) {
                    scaleX = scaleFactor
                    scaleY = scaleFactor
                }
                // Move to the next item's vertical position.
                placeableLayoutPositionY += placeable.height
            }
        }
    }
}
// ...
GesturesSnippets.kt

Đối tượng sửa đổi cho các mục cuộn được (scrollable)

Lưu ý: scrollable là một đối tượng sửa đổi cấp thấp, xử lý các cử chỉ nhập thao tác cuộn cấp thấp mà không có các hành vi khác thường dùng cho vùng chứa có thể cuộn. Để tạo vùng chứa có thể cuộn, hãy xem bài viết androidx.compose.foundation.scrollableArea. scrollableArea cắt nội dung theo ranh giới, hiển thị hiệu ứng cuộn quá mức và điều chỉnh hướng của cử chỉ cuộn để xác minh rằng nội dung di chuyển theo cử chỉ của người dùng.

Đối tượng sửa đổi scrollable khác với đối tượng sửa đổi thao tác cuộn ở chỗ scrollable phát hiện các cử chỉ cuộn và ghi lại các delta, nhưng không tự động bù trừ phần nội dung. Thay vào đó, việc này được uỷ quyền cho người dùng thông qua ScrollableState , cần thiết để đối tượng sửa đổi này hoạt động chính xác.

Khi xây dựng ScrollableState, bạn phải cung cấp một hàm consumeScrollDelta, hàm này sẽ được gọi trong mỗi bước cuộn (thông qua cử chỉ nhập, cuộn hoặc hất nhẹ) với delta được tính bằng pixel. Hàm này phải trả về khoảng cách đã cuộn để đảm bảo truyền sự kiện đúng cách trong trường hợp có các phần tử lồng nhau có đối tượng sửa đổi scrollable.

Lưu ý: Phương thức sửa đổi scrollable không ảnh hưởng đến bố cục của phần tử được áp dụng. Tức là mọi thay đổi đến bố cục phần tử hoặc phần tử con của phần tử đó đều phải được xử lý thông qua delta do ScrollableState cung cấp. Một điều quan trọng cần lưu ý là scrollable không quan tâm đến bố cục của phần tử con, nghĩa là nó không cần phải đo lường bố cục của phần tử con để truyền delta cuộn.

Đoạn mã sau đây phát hiện các cử chỉ và cho thấy một giá trị dạng số cho một phần bù trừ, nhưng không bù trừ phần tử nào:

@Composable
private fun ScrollableSample() {
    // actual composable state
    var offset by remember { mutableFloatStateOf(0f) }
    Box(
        Modifier
            .size(150.dp)
            .scrollable(
                orientation = Orientation.Vertical,
                // Scrollable state: describes how to consume
                // scrolling delta and update offset
                state = rememberScrollableState { delta ->
                    offset += delta
                    delta
                }
            )
            .background(Color.LightGray),
        contentAlignment = Alignment.Center
    ) {
        Text(offset.toString())
    }
}
GesturesSnippets.kt

Hình 3. Một phần tử trên giao diện người dùng phát hiện thao tác nhấn ngón tay và hiển thị giá trị dạng số cho vị trí của ngón tay.