Bố cục chuẩn

Canonical layouts are proven, versatile layouts that provide an optimal user experience on a variety of form factors.

The canonical layouts support small screen phones as well as tablets, foldables, and ChromeOS devices. Derived from Material Design guidance, the layouts are aesthetic as well as functional.

The Android framework includes specialized components that make implementation of the layouts straightforward and reliable.

The canonical layouts create engaging, productivity‑enhancing UIs that form the foundation of great apps.

List-detail

The list-detail layout enables users to explore lists of items that have descriptive, explanatory, or other supplementary information—the item detail.

The layout divides the app window into two side-by-side panes: one for the list, one for the detail. Users select items from the list to display the item detail. Deep links in the detail reveal additional content in the detail pane.

Expanded-width displays (see Use window size classes) accommodate both the list and detail at the same time. Selection of a list item updates the detail pane to show the related content for the selected item.

Medium- and compact-width displays show either the list or the detail, depending on user interaction with the app. When just the list is visible, selection of a list item displays the detail in place of the list. When just the detail is visible, pressing the back button redisplays the list.

Configuration changes such as device orientation changes or app window size changes can change the display's window size class. A list‑detail layout responds accordingly, preserving app state:

• If an expanded-width display showing both the list and detail panes narrows to medium or compact, the detail pane remains visible and the list pane is hidden
• If a medium- or compact-width display has just the detail pane visible and the window size class widens to expanded, the list and detail are shown together, and the list indicates that the item corresponding to the content in the detail pane is selected
• If a medium- or compact-width display has just the list pane visible and widens to expanded, the list and a placeholder detail pane are shown together

List-detail is ideal for messaging apps, contact managers, interactive media browsers or any app where the content can be organized as a list of items that reveal additional information.

Implementation

Mô hình khai báo của Compose hỗ trợ logic lớp kích thước cửa sổ xác định xem có hiện ngăn danh sách và ngăn thông tin chi tiết cùng một lúc hay không (khi lớp kích thước cửa sổ theo chiều rộng được mở rộng) hoặc chỉ hiện ngăn danh sách hoặc thông tin chi tiết (khi lớp kích thước cửa sổ theo chiều rộng là trung bình hoặc nhỏ gọn).

Để đảm bảo luồng dữ liệu một chiều, hãy chuyển tất cả trạng thái lên trên, bao gồm cả lớp kích thước cửa sổ hiện tại và thông tin chi tiết của mục danh sách đã chọn (nếu có), để tất cả thành phần kết hợp đều có quyền truy cập vào dữ liệu và có thể hiển thị chính xác.

Khi chỉ hiển thị ngăn thông tin chi tiết trên kích thước cửa sổ nhỏ, hãy thêm BackHandler để xoá ngăn thông tin chi tiết và chỉ hiện ngăn danh sách. BackHandler không thuộc phạm vi điều hướng tổng thể của ứng dụng vì trình xử lý phụ thuộc vào lớp kích thước cửa sổ và trạng thái thông tin chi tiết được chọn.

ListDetailPaneScaffold là một thành phần kết hợp cấp cao giúp đơn giản hoá việc triển khai bố cục danh sách-chi tiết. Thành phần này tự động xử lý logic ngăn dựa trên các lớp kích thước cửa sổ và hỗ trợ hoạt động điều hướng giữa các ngăn.

Dưới đây là một phương thức triển khai tối thiểu bằng cách sử dụng ListDetailPaneScaffold:

@OptIn(ExperimentalMaterial3AdaptiveApi::class)
@Composable
fun MyListDetailPaneScaffold() {
    val navigator = rememberListDetailPaneScaffoldNavigator()
    ListDetailPaneScaffold(
        directive = navigator.scaffoldDirective,
        value = navigator.scaffoldValue,
        listPane = {
            // Listing Pane
        },
        detailPane = {
            // Details Pane
        }
    )
}
CanonicalLayoutSamples.kt

Sau đây là các thành phần chính trong ví dụ này:

• rememberListDetailPaneScaffoldNavigator: Tạo một trình điều hướng để quản lý hoạt động điều hướng giữa ngăn danh sách và ngăn chi tiết.
• listPane: Hiển thị danh sách các mục.
• detailPane: Hiển thị nội dung của một mục đã chọn.

Để xem ví dụ chi tiết về cách triển khai, hãy xem:

• Hướng dẫn cho nhà phát triển Xây dựng bố cục danh sách-chi tiết
• Mẫu danh sách-chi tiết-soạn thư

Feed

A feed layout arranges equivalent content elements in a configurable grid for quick, convenient viewing of a large amount of content.

Size and position establish relationships among the content elements.

Content groups are created by making elements the same size and positioning them together. Attention is drawn to elements by making them larger than nearby elements.

Cards and lists are common components of feed layouts.

A feed layout supports displays of almost any size because the grid can adapt from a single, scrolling column to a multi‑column scrolling feed of content.

Feeds are especially well suited for news and social media apps.

Implementation

Nguồn cấp dữ liệu bao gồm một lượng lớn thành phần nội dung trong một vùng chứa cuộn theo chiều dọc được đặt trong lưới. Danh sách tải từng phần (lazy list) thể hiện hiệu quả một lượng lớn các mục trong cột hoặc hàng. Lưới tải từng phần (lazy grid) kết xuất các mục trong lưới, hỗ trợ cấu hình kích thước và khoảng (span) của mục.

Hãy định cấu hình các cột của bố cục lưới dựa trên phần hiển thị sẵn có để đặt chiều rộng tối thiểu cho phép cho các mục trong lưới. Khi xác định các mục trong lưới, hãy điều chỉnh khoảng cột để làm một số mục nổi bật hơn so với các mục khác.

Đối với phần tiêu đề, đường phân chia hoặc mục khác được thiết kế nhằm chiếm toàn bộ chiều rộng của nguồn cấp dữ liệu, hãy sử dụng maxLineSpan để chiếm toàn bộ chiều rộng của bố cục.

Trên màn hình có chiều rộng nhỏ gọn không đủ không gian để trình bày nhiều cột, LazyVerticalGrid sẽ hoạt động giống như LazyColumn.

Dưới đây là một phương thức triển khai tối thiểu bằng cách sử dụng LazyVerticalGrid:

@Composable
fun MyFeed(names: List<String>) {
    LazyVerticalGrid(
        // GridCells.Adaptive automatically adapts column count based on available width
        columns = GridCells.Adaptive(minSize = 180.dp),
    ) {
        items(names) { name ->
            Text(name)
        }
    }
}
CanonicalLayoutSamples.kt

Yếu tố then chốt của nguồn cấp dữ liệu thích ứng là cấu hình columns. GridCells.Adaptive(minSize = 180.dp) tạo một lưới trong đó mỗi cột có chiều rộng tối thiểu là 180.dp. Sau đó, lưới sẽ hiển thị nhiều cột nhất có thể trong không gian hiện có.

Hãy xem mẫu Nguồn cấp dữ liệu với Compose để tham khảo ví dụ về cách triển khai.

Supporting pane

Supporting pane layout organizes app content into primary and secondary display areas.

The primary display area occupies the majority of the app window (typically about two thirds) and contains the main content. The secondary display area is a pane that takes up the remainder of the app window and presents content that supports the main content.

Supporting pane layouts work well on expanded-width displays (see Use window size classes) in landscape orientation. Medium- or compact‑width displays support showing both the primary and secondary display areas if the content is adaptable to narrower display spaces, or if the additional content can be initially hidden in a bottom or side sheet accessible by means of a control such as a menu or button.

A supporting pane layout differs from a list‑detail layout in the relationship of the primary and secondary content. Secondary pane content is meaningful only in relation to the primary content; for example, a supporting pane tool window is irrelevant by itself. The supplementary content in the detail pane of a list‑detail layout, however, is meaningful even without the primary content, for example, the description of a product from a product listing.

Use cases for supporting pane include:

• Productivity apps: A document or spreadsheet accompanied by reviewer comments in a supporting pane
• Media apps: A streaming video complemented by a list of related videos in a supporting pane, or the depiction of an album of music supplemented with a playlist
• Tools and settings: A media editing tool with palettes, effects, and other settings in a support pane

Implementation

Compose supports window size class logic, which enables you to determine whether to show both the main content and the supporting content at the same time or place the supporting content in an alternative location.

Hoist all state, including current window size class and information related to the data in the main content and supporting content.

For compact-width displays, place the supporting content below the main content or inside a bottom sheet. For medium and expanded widths, place the supporting content next to the main content, sized appropriately based on the content and space available. For medium width, split the display space equally between the main and supporting content. For expanded width, give 70% of the space to the main content, 30% to the supporting content.

SupportingPaneScaffold is a high-level composable that simplifies the implementation of supporting pane layouts. The composable automatically handles pane logic based on window size classes, displaying panes side by side on large screens or hiding the supporting pane on small screens. SupportingPaneScaffold also supports navigation between panes.

The following is a minimal implementation:

@OptIn(ExperimentalMaterial3AdaptiveApi::class)
@Composable
fun MySupportingPaneScaffold() {
    // Creates and remembers a navigator to control pane visibility and navigation
    val navigator = rememberSupportingPaneScaffoldNavigator()
    SupportingPaneScaffold(
        // Directive and value help control pane visibility based on screen size and state
        directive = navigator.scaffoldDirective,
        value = navigator.scaffoldValue,
        mainPane = {
            // Main Pane for the primary content
        },
        supportingPane = {
            //Supporting Pane for supplementary content
        }
    )
}
CanonicalLayoutSamples.kt

• rememberSupportingPaneScaffoldNavigator: Composable that creates a navigator to manage pane visibility (for example, hiding or showing the supporting pane on compact screens)
• mainPane: Composable that displays the primary content
• supportingPane: Composable that displays the supplementary content

For detailed implementation examples, see:

• Build a supporting pane layout developer guide
• supporting-pane-compose sample

Additional resources

• Material Design — Canonical layouts