Xây dựng bố cục danh sách-chi tiết

implementation("androidx.compose.material3.adaptive:adaptive")
implementation("androidx.compose.material3.adaptive:adaptive-layout")
implementation("androidx.compose.material3.adaptive:adaptive-navigation")

implementation 'androidx.compose.material3.adaptive:adaptive'
implementation 'androidx.compose.material3.adaptive:adaptive-layout'
implementation 'androidx.compose.material3.adaptive:adaptive-navigation'

• thích ứng: Các thành phần cấp thấp như HingeInfo và Posture
• adaptive-layout: Bố cục thích ứng, chẳng hạn như ListDetailPaneScaffold và SupportingPaneScaffold
• adaptive-navigation: Các thành phần kết hợp để điều hướng trong và giữa các ngăn, cũng như bố cục thích ứng hỗ trợ điều hướng theo mặc định, chẳng hạn như NavigableListDetailPaneScaffold và NavigableSupportingPaneScaffold

Đảm bảo dự án của bạn có compose-material3-adaptive phiên bản 1.1.0-beta1 trở lên.

Chọn sử dụng tính năng xem trước thao tác quay lại

Để bật ảnh động xem trước thao tác quay lại trong Android 15 trở xuống, bạn phải chọn sử dụng tính năng hỗ trợ xem trước thao tác quay lại. Để chọn sử dụng, hãy thêm android:enableOnBackInvokedCallback="true" vào thẻ <application> hoặc các thẻ <activity> riêng lẻ trong tệp AndroidManifest.xml. Để biết thêm thông tin, hãy xem phần Chọn sử dụng tính năng xem trước thao tác quay lại.

Khi ứng dụng của bạn nhắm đến Android 16 (cấp độ API 36) trở lên, tính năng xem trước thao tác quay lại sẽ được bật theo mặc định.

Cách sử dụng cơ bản

Triển khai NavigableListDetailPaneScaffold như sau:

1. Sử dụng một lớp đại diện cho nội dung đã chọn. Sử dụng lớp Parcelable để hỗ trợ lưu và khôi phục mục danh sách đã chọn. Sử dụng trình bổ trợ kotlin-parcelize để tạo mã cho bạn.
2. Tạo một ThreePaneScaffoldNavigator bằng rememberListDetailPaneScaffoldNavigator.

Trình điều hướng này được dùng để di chuyển giữa danh sách, chi tiết và các ngăn bổ sung. Bằng cách khai báo một loại chung, trình điều hướng cũng theo dõi trạng thái của scaffold (tức là MyItem nào đang được hiển thị). Vì loại này có thể phân chia, nên trình điều hướng có thể lưu và khôi phục trạng thái để tự động xử lý các thay đổi về cấu hình.

1. Truyền trình điều hướng đến thành phần kết hợp NavigableListDetailPaneScaffold.

2. Cung cấp cách triển khai ngăn danh sách cho NavigableListDetailPaneScaffold. Sử dụng AnimatedPane để áp dụng ảnh động mặc định của ngăn trong quá trình điều hướng. Sau đó, hãy sử dụng ThreePaneScaffoldNavigator để chuyển đến ngăn chi tiết, ListDetailPaneScaffoldRole.Detail và hiển thị mục đã truyền.

3. Đưa phương thức triển khai ngăn chi tiết vào NavigableListDetailPaneScaffold.

Khi quá trình điều hướng hoàn tất, currentDestination sẽ chứa ngăn mà ứng dụng của bạn đã điều hướng đến, bao gồm cả nội dung hiển thị trong ngăn. Thuộc tính contentKey có cùng loại được chỉ định trong lệnh gọi ban đầu để bạn có thể truy cập vào mọi dữ liệu cần hiển thị.

1. Bạn có thể thay đổi defaultBackBehavior trong NavigableListDetailPaneScaffold. Theo mặc định, NavigableListDetailPaneScaffold sử dụng PopUntilScaffoldValueChange cho defaultBackBehavior.

Nếu ứng dụng của bạn yêu cầu một mẫu điều hướng quay lại khác, bạn có thể ghi đè hành vi này bằng cách chỉ định một tuỳ chọn BackNavigationBehavior khác.

Tuỳ chọn BackNavigationBehavior

Phần sau đây sử dụng ví dụ về một ứng dụng email có danh sách email trong một ngăn và chế độ xem chi tiết trong ngăn còn lại.

PopUntilScaffoldValueChange (Mặc định và nên dùng trong hầu hết các trường hợp)

Hành vi này tập trung vào các thay đổi đối với cấu trúc bố cục tổng thể. Trong chế độ thiết lập nhiều ngăn, việc thay đổi nội dung email trong ngăn chi tiết sẽ không làm thay đổi cấu trúc bố cục cơ bản. Do đó, nút quay lại có thể thoát khỏi ứng dụng hoặc biểu đồ điều hướng hiện tại vì không có thay đổi nào về bố cục để huỷ bỏ trong bối cảnh hiện tại. Trong bố cục một ngăn, thao tác nhấn nút quay lại sẽ bỏ qua các thay đổi về nội dung trong chế độ xem chi tiết và quay lại chế độ xem danh sách, vì điều này thể hiện sự thay đổi rõ ràng về bố cục.

Hãy xem các ví dụ sau đây:

• Nhiều ngăn: Bạn đang xem một email (Mục 1) trong ngăn chi tiết. Khi bạn nhấp vào một email khác (Mục 2), ngăn chi tiết sẽ được cập nhật, nhưng ngăn danh sách và ngăn chi tiết vẫn hiển thị. Thao tác nhấn nút quay lại có thể thoát khỏi ứng dụng hoặc quy trình điều hướng hiện tại.
• Một ngăn: Bạn xem Mục 1, sau đó xem Mục 2, nhấn nút quay lại sẽ đưa bạn trực tiếp đến ngăn danh sách email.

Hãy sử dụng chế độ này khi bạn muốn người dùng nhận thấy các hiệu ứng chuyển đổi bố cục riêng biệt với mỗi thao tác quay lại.

PopUntilContentChange

Hành vi này ưu tiên nội dung được hiển thị. Nếu bạn xem Mục 1 rồi đến Mục 2, thì thao tác nhấn nút quay lại sẽ đưa bạn về Mục 1, bất kể bố cục.

Hãy xem các ví dụ sau đây:

• Nhiều ngăn: Bạn xem Mục 1 trong ngăn chi tiết, sau đó nhấp vào Mục 2 trong danh sách. Ngăn chi tiết sẽ cập nhật. Thao tác nhấn nút quay lại sẽ khôi phục ngăn chi tiết về Mục 1.
• Một ngăn: Nội dung cũng được khôi phục tương tự.

Hãy sử dụng chế độ này khi người dùng muốn quay lại nội dung đã xem trước đó bằng thao tác quay lại.

PopUntilCurrentDestinationChange

Hành vi này sẽ bật ngăn xếp lui cho đến khi đích điều hướng hiện tại thay đổi. Điều này áp dụng như nhau cho bố cục một và nhiều ngăn.

Hãy xem các ví dụ sau đây:

Bất kể bạn đang ở bố cục một hay nhiều ngăn, việc nhấn nút quay lại sẽ luôn di chuyển tiêu điểm từ phần tử điều hướng được làm nổi bật đến đích đến trước đó. Trong ứng dụng email, điều này có nghĩa là chỉ báo trực quan của ngăn đã chọn sẽ thay đổi.

Hãy sử dụng chế độ này khi việc duy trì chỉ báo hình ảnh rõ ràng về thành phần điều hướng hiện tại là yếu tố quan trọng đối với trải nghiệm người dùng.

PopLatest

Tuỳ chọn này chỉ xoá đích đến gần đây nhất khỏi ngăn xếp lui. Sử dụng tuỳ chọn này để điều hướng quay lại mà không bỏ qua các trạng thái trung gian.

Sau khi bạn triển khai các bước này, mã của bạn sẽ có dạng như sau:

NavigableListDetailPaneScaffold(
    navigator = navigator,
    listPane = {
        AnimatedPane {
            ListContent(
                words = sampleWords,
                selectionState = navigator.currentDestination?.contentKey?.let {
                    SelectionVisibilityState.ShowSelection(it)
                } ?: SelectionVisibilityState.NoSelection,
                onWordClick = { word ->
                    scope.launch {
                        navigator.navigateTo(ListDetailPaneScaffoldRole.Detail, word)
                    }
                },
                animatedVisibilityScope = this@AnimatedPane,
                sharedTransitionScope = this@SharedTransitionLayout
            )
        }
    },
    detailPane = {
        AnimatedPane {
            DetailContent(
                definedWord = navigator.currentDestination?.contentKey,
                animatedVisibilityScope = this@AnimatedPane,
                sharedTransitionScope = this@SharedTransitionLayout,
                onClosePane = {
                    scope.launch {
                        navigator.navigateBack(
                            backNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange
                        )

                    }
                }
            )
        }
    }
ListDetailSample.kt