Tài liệu Compose 3

Tài liệu tham khảo API
androidx.compose.material3
(Xem tài liệu tham khảo về API cho tất cả các gói soạn)

Xây dựng giao diện người dùng Jetpack Compose bằng các thành phần Material Design 3, phiên bản cải tiến tiếp theo của Material Design. Material 3 có giao diện cập nhật, cũng như các thành phần và tính năng cá nhân hoá Material You, chẳng hạn như màu động. Công cụ này được thiết kế để phù hợp với phong cách đồ hoạ và giao diện người dùng hệ thống mới trên Android 12.

Bản cập nhật mới nhất	Bản phát hành ổn định	Bản phát hành dùng thử	Bản phát hành beta	Bản phát hành alpha
Ngày 1 tháng 6 năm 2022	-	-	-	1.0.0-alpha13

Cấu trúc

Compose là sự kết hợp của 7 mã nhận dạng Nhóm Maven (Maven Group Id) trong androidx. Mỗi Nhóm chứa một tập con chức năng mục tiêu, và mỗi tập con có một bộ ghi chú phát hành riêng.

Bảng này giải thích các nhóm và đường liên kết đến từng bộ ghi chú phát hành.

Nhóm	Mô tả
compose.animation	Tạo ảnh động trong các ứng dụng Jetpack Compose để làm phong phú trải nghiệm người dùng.
compose.compiler	Biến đổi các hàm @Composable và hỗ trợ hoạt động tối ưu hoá bằng trình biên dịch bổ trợ Kotlin.
compose.foundation	Viết ứng dụng Jetpack Compose bằng các khối dựng có sẵn, cũng như mở rộng nền tảng để xây dựng các thành phần của hệ thống thiết kế của riêng bạn.
compose.material	Xây dựng các giao diện người dùng Compose Jetpack bằng các thành phần Material Design có sẵn. Đây là điểm truy cập cấp cao hơn của Compose, được thiết kế nhằm cung cấp các thành phần theo như mô tả trên trang web www.material.io.
compose.material3	Xây dựng giao diện người dùng Jetpack Compose bằng các thành phần Material Design 3, phiên bản cải tiến tiếp theo của Material Design. Material 3 có giao diện cập nhật, cũng như các thành phần và tính năng cá nhân hoá Material You, chẳng hạn như màu động. Công cụ này được thiết kế để phù hợp với phong cách đồ hoạ và giao diện người dùng hệ thống mới trên Android 12.
compose.runtime	Các khối dựng cơ bản cho mô hình lập trình và tính năng quản lý trạng thái của Compose, đồng thời là thời gian chạy cốt lõi để trình biên dịch bổ trợ Compose nhắm đến.
compose.ui	Các thành phần cơ bản của giao diện người dùng Compose cần thiết để tương tác với thiết bị, bao gồm cả bố cục, bản vẽ và phương thức nhập.

Khai báo phần phụ thuộc

Để thêm một phần phụ thuộc trên Compose, bạn phải thêm kho lưu trữ Google Maven vào dự án. Đọc nội dung Kho lưu trữ Maven của Google để biết thêm thông tin.

Thêm các phần phụ thuộc cho cấu phần mềm bạn cần trong tệp build.gradle cho ứng dụng hoặc mô-đun:

Groovy

dependencies {
    implementation "androidx.compose.material3:material3:1.0.0-alpha13"
    implementation "androidx.compose.material3:material3-window-size-class:1.0.0-alpha13"
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.2.0-alpha08"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

dependencies {
    implementation("androidx.compose.material3:material3:1.0.0-alpha13")
    implementation("androidx.compose.material3:material3-window-size-class:1.0.0-alpha13")
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.2.0-alpha08"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Để biết thêm thông tin về các phần phụ thuộc, hãy xem bài viết Thêm phần phụ thuộc vào bản dựng.

Ý kiến phản hồi

Phản hồi của bạn có thể giúp chúng tôi cải thiện Jetpack. Hãy cho chúng tôi biết nếu bạn phát hiện lỗi mới hoặc có ý tưởng cải thiện thư viện này. Vui lòng xem các lỗi hiện có trong thư viện này trước khi báo một lỗi mới. Bạn có thể thêm lượt bình chọn cho lỗi hiện có bằng cách nhấp vào nút dấu sao.

Báo lỗi mới

Xem tài liệu về Công cụ theo dõi lỗi để biết thêm thông tin.

Phiên bản 1.0

Phiên bản 1.0.0-alpha13

Ngày 1 tháng 6 năm 2022

Phát hành androidx.compose.material3:material3:1.0.0-alpha13 và androidx.compose.material3:material3-window-size-class:1.0.0-alpha13. Phiên bản 1.0.0-alpha13 bao gồm các thay đổi sau.

Thay đổi API

Hỗ trợ duy trì vị trí hàng đầu trên thanh ứng dụng trong quá trình thay đổi cấu hình. (I10459, b/216160958)

Phiên bản 1.0.0-alpha12

Ngày 18 tháng 5 năm 2022

Phát hành androidx.compose.material3:material3:1.0.0-alpha12 và androidx.compose.material3:material3-window-size-class:1.0.0-alpha12. Phiên bản 1.0.0-alpha12 bao gồm các thay đổi sau.

Sửa lỗi

Thanh trượt mẹ hiện có thể có chiều rộng bằng 0. (b/231707291)

Phiên bản 1.0.0-alpha11

Ngày 11 tháng 5 năm 2022

Phát hành androidx.compose.material3:material3:1.0.0-alpha11 và androidx.compose.material3:material3-window-size-class:1.0.0-alpha11. Phiên bản 1.0.0-alpha11 bao gồm các thay đổi sau.

Tính năng mới

Đã thêm RangeSlider vào Material 3 (I18e38)
Thêm tùy chọn hỗ trợ Material3 AssistChip và InputChip (I0d25a)
Thêm tùy chọn hỗ trợ Material3 FilterChip và SuggestionChip (I9fdf3)

Thay đổi API

Đã đổi tên thành phần kết hợp TextFieldDefaults.BorderStroke để vẽ một nét đường viền trong OutlinedTextField thành TextFieldDefaults.BorderBox. (I5f295)
Chuyển sang chế độ thay đổi hình ảnh trong m3 (Iab30e)
Cho phép truyền màu tới các nút biểu tượng chuẩn. (Ia2445)

Sửa lỗi

Thêm tính năng kiểm tra lint vào material3/Scaffold để đảm bảo khoảng đệm bên trong được sử dụng (I72293, b/226951418)

Phiên bản 1.0.0-alpha10

Ngày 20 tháng Tư, 2022

Phát hành androidx.compose.material3:material3:1.0.0-alpha10 và androidx.compose.material3:material3-window-size-class:1.0.0-alpha10. Phiên bản 1.0.0-alpha10 bao gồm các thay đổi sau.

Tính năng mới

material3-window-size-class là một thư viện mới hỗ trợ các lớp kích thước cửa sổ: một tập hợp các điểm ngắt cửa sổ xem ý kiến để bạn thiết kế, phát triển và thử nghiệm các bố cục ứng dụng có thể đổi kích thước. Bạn có thể sử dụng calculateWindowSizeClass để truy xuất phiên bản lớp kích thước cửa sổ. Bạn có thể sử dụng thực thể này để xác định cách giao diện người dùng sẽ xuất hiện, chẳng hạn như hiển thị thanh điều hướng thay vì điều hướng dưới cùng đối với kích thước cửa sổ lớn hơn. Để biết thêm thông tin và sử dụng mẫu, hãy xem tài liệu Tài liệu tham khảo API dành cho WindowSizeClass. Để biết thêm thông tin về định nghĩa lớp kích thước cửa sổ, hãy xem hướng dẫn công khai về việc hỗ trợ các kích thước màn hình khác nhau.

Thay đổi API

Thêm độ cao FAB mặc định cho BottomAppBar, xóa hàm lambda ở cuối khỏi BottomAppBar với FAB. (I92c47)
Thêm Material3 FilledIconButton, FilledTonalIconButton và OutlinedIconButton. (Ib2bda)
Cập nhật API Snackbar của Material 3 để chấp nhận các giá trị màu cho hành động không bắt buộc và hành động đóng. (Ibe4b4)
Mức sử dụng một phần (giảm/không có vị trí) trong PointerInputChange sẽ không được dùng nữa. Bạn có thể dùng consume() để thay đổi hoàn toàn. Bạn có thể sử dụng isConsumed để xác định xem ai đó đã từng thực hiện thay đổi trước đây hay chưa.
Giờ đây, PointerInputChange::copy() luôn tạo một bản sao nông. Điều này có nghĩa là các bản sao của PointerInputChange sẽ được sử dụng sau khi một trong các bản sao được sử dụng. Nếu bạn muốn tạo một PointerInputChange không liên kết, hãy dùng hàm dựng. (Ie6be4, b/225669674)
Các thay đổi đối với API Thẻ để nhận màu vùng chứa và nội dung qua giao diện CardColors, đồng thời hỗ trợ trạng thái bị vô hiệu hóa cho các thẻ có thể nhấp. (I927df)
Thông số backgroundColor đã được đổi tên thành containerColor trong các trường văn bản Material 3 để cải thiện tính nhất quán với các thành phần khác. (I6fbd9)

Sửa lỗi

Cập nhật lên tiêu chuẩn IconButton để điều chỉnh cho phù hợp với thông số kỹ thuật của Material3. (I09eab)
Di chuyển chiều cao thanh trên cùng của Material3 Scaffold vào khoảng đệm được chuyển đến nội dung, cho phép nội dung hiển thị bên dưới thanh ứng dụng trên cùng. Nếu bạn bỏ qua PaddingValues, thì nội dung có thể bị che khuất bằng thanh trên cùng. (I83cbc, b/217776202)

Phiên bản 1.0.0-alpha09

Ngày 6 tháng Tư, 2022

Phát hành androidx.compose.material3:material3:1.0.0-alpha09. Phiên bản 1.0.0-alpha09 bao gồm những thay đổi này.

Tính năng mới

Thêm API chuyển đổi Material 3 (I2c3ad)

Thay đổi API

Thêm tùy chọn hỗ trợ cho các trình đơn thả xuống có trường văn bản (còn gọi là "trình đơn thả xuống hiển thị" hoặc "hộp kết hợp"). (I1b832)
Thêm thông số hình dạng vào hệ thống phụ MaterialMaterial và Shape. (I37426)
Đã thêm một tham số mở rộng vào ExtendedFloatingActionButton để kiểm soát việc FAB được mở rộng hay thu gọn, với ảnh động giữa mỗi trạng thái. Đã thêm quá tải FAB mở rộng cho FAB mở rộng có văn bản đứng sau cho ExtendedFAB mà không có biểu tượng. (Iba7f1)

Phiên bản 1.0.0-alpha08

Ngày 23 tháng Ba, 2022

Phát hành androidx.compose.material3:material3:1.0.0-alpha08. Phiên bản 1.0.0-alpha08 bao gồm các thay đổi sau.

Tính năng mới

Thêm tùy chọn hỗ trợ cho các trường văn bản Material 3. (I795cc, b/199377790)

Thay đổi API

Thêm dấu phân chia mặc định cho trình đơn (I01374)
Đã thêm thông số màu surfaceTint vào lớp ColorScheme. (I2f558)

Sửa lỗi

Hãy chỉnh sửa tại nút Material3 để đọc giá trị kiểu văn bản mặc định của nó từ MaterialTheme. (Ie62fc)

Phiên bản 1.0.0-alpha07

Ngày 9 tháng Ba, 2022

androidx.compose.material3:material3:1.0.0-alpha07 đã phát hành. Phiên bản 1.0.0-alpha07 chứa những cam kết này.

Thay đổi API

Các bản cập nhật của API Surface 3 Material 3 đã mang lại các chức năng quá tải cho Surfaces có thể nhấp, cũng như thêm một hàm để hỗ trợ các Surface có thể chọn và chuyển đổi. (I4bf18)
LazyVerticalGrid và LazyHorizontalGrid hiện đang ổn định. (I307c0)
LazyVerticalGrid/LazyHorizontalGrid và tất cả API có liên quan đã được di chuyển vào gói con .grid. Vui lòng cập nhật các mục nhập của bạn từ androidx.comose.foundation.lazy thành androidx.comose.foundation.lazy.grid. (I2d446)
Đã hoàn nguyên thay đổi trước đó là chỉ dựa vào Chế độ xem cho WindowInsetsControllerCompat và một lần nữa, bạn cần phải sử dụng Cửa sổ để quản lý một số cờ trong cửa sổ. Đã ngừng sử dụng ViewCompat.getWindowInsetsController và thay vào đó là WindowCompat.getInsetsController để đảm bảo sử dụng đúng Cửa sổ (chẳng hạn như khi Chế độ xem nằm trong hộp thoại). (I660ae, b/219572936)
Thêm API LazyVerticalGrid mới để xác định kích thước trục chéo (I17723)

Sửa lỗi

Cập nhật API Thẻ để tuân theo các thay đổi tại API Surface (I3c8b9)

Phiên bản 1.0.0-alpha06

Ngày 23 tháng Hai, 2022

androidx.compose.material3:material3:1.0.0-alpha06 đã phát hành. Phiên bản 1.0.0-alpha06 bao gồm các thay đổi sau.

Thay đổi API

NavigationDrawerItem được thêm vào đại diện cho một điểm đến duy nhất trong các ngăn (Ic396f, b/218286829)
Đã thêm PermanentNavigationDrawer và DismissibleNavigationDrawer làm API thử nghiệm. Đó là các ngăn phù hợp với các thiết bị có màn hình lớn. (I5f8ab, b/218286829)
Thêm vị trí hỗ trợ thanh ứng dụng dưới cùng Tài liệu 3 (Ic432a)
NavigationDrawer đã được đổi tên thành ModalNavigationDrawer (I1807d, b/218286829)
Đã thêm loại Thanh trượt và mã thông báo Tài liệu 3 (I1successe)
Triển khai thẻ được thêm vào, hãy xem tài liệu để sử dụng mẫu (Ie0146)

Sửa lỗi

Đã khắc phục sự cố trong đó trình điều hướng tuyến tính của trình đọc màn hình TalkBack chọn tiêu đề thanh ứng dụng trên cùng trống. (Id4690)
Đã thêm IconSize vào FloatingActionButtonDefaults (Ia71cf)
Sửa lỗi cho các nút AlertDialog bị ẩn khi một văn bản dài được thêm vào bằng LazyColumn. (Ib2cc9, b/216663029)

Phiên bản 1.0.0-alpha05

Ngày 9 tháng Hai, 2022

androidx.compose.material3:material3:1.0.0-alpha05 đã phát hành. Phiên bản 1.0.0-alpha05 chứa những cam kết này.

Tính năng mới

Đã thêm thành phần Material Design 3

Trình đơn thả xuống
- DropdownMenu, DropdownMenuItem
Thẻ
- Thẻ, OutlinedCard, ElevatedCard

Thay đổi API

Hàm Surface không còn hoạt động mà sẽ thực hiện lệnh gọi lại onClick. Bạn nên tạo các nền tảng có thể nhấp bằng InteractionSource và Modifier.clickable(). (I211c6)
Thêm chế độ hỗ trợ nhấn và đặt tiêu điểm cho FAB. (Ibb584)
Đã thay đổi API Surface để nhận một InteractiveSource cho phép kiểm soát giao diện của mục đó ở các trạng thái khác nhau. (Iafbc8)

Sửa lỗi

Thêm màu thứ ba bị thiếu trong bảng phối màu động (I456c4, b/214588434)

Phiên bản 1.0.0-alpha04

Ngày 26 tháng Một, 2022

androidx.compose.material3:material3:1.0.0-alpha04 đã phát hành. Phiên bản 1.0.0-alpha04 chứa những bản cam kết này.

Thay đổi API

Thêm NonRestartableComposable vào các phương thức đang làm quá tải những phương thức hiện có mà không cần logic phức tạp. Điều này làm giảm các bước kiểm tra ghi nhớ do trình biên dịch tạo ra (các bước cân bằng) cho tất cả các thông số được lặp lại trong hàm bên trong được gọi. (I90490)
Đã thêm bộ chia Tài liệu 3. (Ica5fc)
Đánh dấu Hộp đánh dấu và RadioButton bằng chú thích API thử nghiệm. (Ie44bb)
Thêm tùy chọn hỗ trợ cho các chỉ báo tiến trình của Material 3. (Iff232, b/205023841)

Sửa lỗi

Cập nhật màu vùng chứa TextButton's đã tắt cho thành màu trong suốt (I6b248, b/213339737)

Phiên bản 1.0.0-alpha03

Ngày 12 tháng Một, 2022

androidx.compose.material3:material3:1.0.0-alpha03 đã phát hành. Phiên bản 1.0.0-alpha03 bao gồm các thay đổi sau.

Sửa lỗi

Thêm LocalIndication vào MaterialTheme của Tài liệu 3. (I7ce4e)
Chỉnh sửa bán kính góc áp dụng cho Hộp đánh dấu (I38b03, b/175198975, b/202309440)

Thông tin cập nhật phần phụ thuộc

Giờ phụ thuộc vào Kotlin 1.6.10.

Phiên bản 1.0.0-alpha02

Ngày 1 tháng Mười hai, 2021

androidx.compose.material3:material3:1.0.0-alpha02 đã phát hành. Phiên bản 1.0.0-alpha02 chứa những cam kết này.

Tính năng mới

Thêm tùy chọn hỗ trợ cho hộp đánh dấu và nút chọn.
Đã cập nhật để tương thích với 1.6.0 Kotlin

Thay đổi API

Tháo ngăn khỏi giàn của Chất liệu 3. (I04f51)
Thêm vị trí hỗ trợ Checkbox của Material 3. (Id5542)
Thêm vị trí hỗ trợ RadioButton của Material 3. (I20334)

Sửa lỗi

Giảm IconButton bán kính gợn sóng từ 40dp xuống 20 dp. (I68bbe, b/206674345)
Đường dẫn nhanh của chuỗi cổng cho Text thay đổi từ compose.material (I30b03)
Đã khắc phục nhưng nút luôn được mã hóa cứng này luôn bật. (Iea832, b/205335456)

Phiên bản 1.0.0-alpha01

Ngày 27 tháng Mười, 2021

androidx.compose.material3:material3:1.0.0-alpha01 đã phát hành. Phiên bản 1.0.0-alpha01 bao gồm các thay đổi sau.

Tính năng mới

Thiết kế Material Design 3 và thiết bị Material You màu động

Thành phần Material Design 3

Nút
- Button, ElevatedButton, FilledTonalButton, OutlinedButton, TextButton
FAB và FAB mở rộng
- SmallFloatingActionButton, FloatingActionButton, LargeFloatingActionButton, ExtendedFloatingActionButton
Hộp thoại
- AlertDialog
Thanh điều hướng
- NavigationBar
Ngăn điều hướng
- NavigationDrawer
Dải điều hướng
- NavigationRail
Thanh ứng dụng hàng đầu
- SmallTopAppBar, CenterAlignedTopAppBar, MediumTopAppBar, LargeTopAppBar
Huy hiệu
- Badge, BadgedBox
Biểu tượng
- Icon, IconButton
Văn bản
- Text
Nền tảng
- Surface
Bố cục
- Scaffold
Màu nội dung
- LocalContentColor

Để biết thêm thông tin, hãy xem phần Material Design 3 và Material You trong phần hướng dẫn Chủ đề của thiết bị trong ứng dụng Compose.