Xây dựng bố cục ngăn bổ trợ

Bố cục chính tắc của ngăn bổ trợ tập trung sự chú ý của người dùng vào nội dung chính của ứng dụng, đồng thời hiển thị nội dung bổ trợ phù hợp. Ví dụ: ngăn nội dung chính có thể hiển thị thông tin về một bộ phim gần đây, còn ngăn bổ trợ hiển thị danh sách các bộ phim khác có chủ đề tương tự hoặc có cùng đạo diễn hoặc diễn viên đóng vai chính. Để biết thêm thông tin về bố cục chuẩn của ngăn bổ trợ, hãy xem Nguyên tắc của ngăn bổ trợ Material 3.

Triển khai ngăn bổ trợ

SupportingPaneScaffold bao gồm tối đa 3 ngăn: ngăn chính, ngăn bổ trợ và ngăn bổ sung không bắt buộc. Scaffold xử lý mọi phép tính để phân bổ không gian cửa sổ cho 3 ngăn. Trên màn hình lớn, Scaffold hiển thị ngăn chính với ngăn bổ trợ ở bên cạnh. Trên màn hình nhỏ, Scaffold sẽ hiển thị toàn màn hình của ngăn chính hoặc ngăn bổ trợ.

Thêm phần phụ thuộc

SupportingPaneScaffold là một phần của Thư viện bố cục thích ứng Material 3.

Thêm 3 phần phụ thuộc liên quan sau đây vào tệp build.gradle của ứng dụng hoặc mô-đun:

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ư SupportingPaneScaffold
• adaptive-navigation – Các thành phần kết hợp để di chuyển trong và giữa các ngăn

Tạo trình điều hướng và Scaffold

Trong các cửa sổ nhỏ, mỗi lần chỉ hiển thị một ngăn, vì vậy, hãy sử dụng ThreePaneScaffoldNavigator để di chuyển đến và đi từ các ngăn. Tạo một thực thể của trình điều hướng bằng rememberSupportingPaneScaffoldNavigator. Để xử lý các cử chỉ quay lại, hãy sử dụng BackHandler để kiểm tra canNavigateBack() và gọi navigateBack():

val navigator = rememberSupportingPaneScaffoldNavigator()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}
SampleSupportingPaneScaffold.kt

Scaffold yêu cầu một PaneScaffoldDirective để kiểm soát cách chia đôi màn hình và khoảng cách sử dụng, cũng như ThreePaneScaffoldValue cung cấp trạng thái hiện tại của các ngăn (chẳng hạn như chúng đang được mở rộng hay bị ẩn). Đối với hành vi mặc định, hãy sử dụng scaffoldDirective và scaffoldValue của trình điều hướng tương ứng:

SupportingPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    mainPane = { /*...*/ },
    supportingPane = { /*...*/ },
)
SampleSupportingPaneScaffold.kt

Ngăn chính và ngăn bổ trợ là các thành phần kết hợp chứa nội dung của bạn. Sử dụng AnimatedPane để áp dụng các ảnh động của ngăn mặc định trong khi điều hướng. Sử dụng giá trị Scaffold để kiểm tra xem ngăn bổ trợ có bị ẩn hay không. Nếu có, hãy hiển thị nút gọi navigateTo(ThreePaneScaffoldRole.Secondary) để cho thấy ngăn bổ trợ.

Sau đây là cách triển khai hoàn chỉnh Scaffold:

val navigator = rememberSupportingPaneScaffoldNavigator()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}

SupportingPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    mainPane = {
        AnimatedPane(modifier = Modifier.safeContentPadding()) {
            // Main pane content
            if (navigator.scaffoldValue[SupportingPaneScaffoldRole.Supporting] == PaneAdaptedValue.Hidden) {
                Button(
                    modifier = Modifier.wrapContentSize(),
                    onClick = {
                        navigator.navigateTo(SupportingPaneScaffoldRole.Supporting)
                    }
                ) {
                    Text("Show supporting pane")
                }
            } else {
                Text("Supporting pane is shown")
            }
        }
    },
    supportingPane = {
        AnimatedPane(modifier = Modifier.safeContentPadding()) {
            // Supporting pane content
            Text("Supporting pane")
        }
    },
)
SampleSupportingPaneScaffold.kt

Trích xuất các thành phần kết hợp của ngăn

Trích xuất các ngăn riêng lẻ của SupportingPaneScaffold thành các thành phần kết hợp riêng để có thể sử dụng lại và kiểm thử. Sử dụng ThreePaneScaffoldScope để truy cập AnimatedPane nếu bạn muốn tạo ảnh động mặc định:

@Composable
fun ThreePaneScaffoldScope.MainPane(
    shouldShowSupportingPaneButton: Boolean,
    onNavigateToSupportingPane: () -> Unit,
    modifier: Modifier = Modifier,
) {
    AnimatedPane(modifier = modifier.safeContentPadding()) {
        // Main pane content
        if (shouldShowSupportingPaneButton) {
            Button(onClick = onNavigateToSupportingPane) {
                Text("Show supporting pane")
            }
        } else {
            Text("Supporting pane is shown")
        }
    }
}

@Composable
fun ThreePaneScaffoldScope.SupportingPane(
    modifier: Modifier = Modifier,
) {
    AnimatedPane(modifier = modifier.safeContentPadding()) {
        // Supporting pane content
        Text("This is the supporting pane")
    }
}
SampleSupportingPaneScaffold.kt

Việc trích xuất các ngăn thành các thành phần kết hợp giúp đơn giản hoá việc sử dụng SupportingPaneScaffold (so sánh nội dung sau đây với cách triển khai đầy đủ của Scaffold trong phần trước):

val navigator = rememberSupportingPaneScaffoldNavigator()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}

SupportingPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    mainPane = {
        MainPane(
            shouldShowSupportingPaneButton = navigator.scaffoldValue.secondary == PaneAdaptedValue.Hidden,
            onNavigateToSupportingPane = { navigator.navigateTo(ThreePaneScaffoldRole.Secondary) }
        )
    },
    supportingPane = { SupportingPane() },
)
SampleSupportingPaneScaffold.kt