Di chuyển giao diện XML sang Material 3 trong Compose

Khi đưa Compose vào ứng dụng hiện tại, bạn cần di chuyển giao diện XML Material để dùng MaterialTheme cho các thành phần Compose. Như vậy, giao diện của ứng dụng sẽ có 2 nguồn đáng tin cậy: giao diện dựa trên Khung hiển thị và giao diện Compose. Mọi thay đổi đối với kiểu sẽ cần được thực hiện ở nhiều nơi. Sau khi di chuyển toàn bộ ứng dụng sang Compose, hãy xoá giao diện XML.

Bạn có thể sử dụng công cụ Material Theme Builder để di chuyển màu.

Khi bắt đầu di chuyển từ XML sang Compose, hãy di chuyển giao diện sang giao diện Material 3 Compose.

Bảng chú giải thuật ngữ

Thuật ngữ Định nghĩa
MaterialTheme Hàm composable cung cấp giao diện (màu, kiểu chữ, hình dạng) cho các thành phần trên giao diện người dùng Compose.
Shape Đối tượng Compose dùng để xác định hình dạng thành phần tuỳ chỉnh cho MaterialTheme.
Typography Đối tượng Compose dùng để xác định kiểu văn bản tuỳ chỉnh (nhóm phông chữ, kích thước, độ đậm) cho MaterialTheme.
Color Đối tượng Compose dùng để xác định bảng phối màu tuỳ chỉnh cho MaterialTheme.
Giao diện XML Hệ thống giao diện Android được xác định trong các tệp XML, do hệ thống Khung hiển thị sử dụng.

Các điểm hạn chế

Trước khi di chuyển, hãy lưu ý những điểm hạn chế sau:

  • Hướng dẫn này chỉ tập trung vào việc di chuyển sang Material 3. Để di chuyển từ các hệ thống thiết kế thay thế, hãy xem Material 2 hoặc Các hệ thống thiết kế tuỳ chỉnh trong Compose.
  • Mục tiêu cuối cùng là di chuyển hoàn toàn sang Compose, cho phép xoá giao diện XML. Hướng dẫn này giải thích cách di chuyển, nhưng không giải thích cách xoá giao diện XML.

Bước 1: Đánh giá hệ thống thiết kế

Xác định hệ thống thiết kế nào được dùng trong dự án Khung hiển thị XML. Phân tích đường dẫn di chuyển và các bước cần thiết để di chuyển hệ thống thiết kế hiện có sang Material 3 trong Compose.

Bước 2: Xác định các tệp nguồn giao diện

Trong XML, bạn viết ?attr/colorPrimary. Trong Compose, bạn truy cập vào các giá trị giao diện bằng MaterialTheme.*:

Xác định và tìm tất cả các tài nguyên và tệp XML cần thiết cho giao diện: bảng phối màu sáng và tối cùng các trình đủ điều kiện, giao diện, hình dạng, kích thước, kiểu chữ, kiểu và các tệp có liên quan khác.

Bạn có thể sử dụng lại các tài nguyên như chuỗi và không cần di chuyển.

Bước 3: Di chuyển màu

Nguyên tắc chính: XML sử dụng màu thập lục phân được đặt tên. Material 3 sử dụng vai trò ngữ nghĩa (ví dụ: primary, onPrimary, surface). Ngừng đặt tên màu theo mã thập lục phân; đặt tên theo vai trò.

Ví dụ:

Tên màu XML Vai trò Material 3
colorPrimary primary
colorPrimaryDark / colorPrimaryVariant primaryContainer hoặc secondary
colorAccent secondary hoặc tertiary
colorOnPrimary onPrimary
android:colorBackground background
colorSurface surface
colorOnSurface onSurface
colorError error
colorOnError onError
colorOutline outline
colorSurfaceVariant surfaceVariant
colorOnSurfaceVariant onSurfaceVariant

Di chuyển bảng phối màu tối và sáng từ XML sang các bảng phối màu tương đương trong Material 3 Compose.

Bước 4: Di chuyển hình dạng và kiểu chữ tuỳ chỉnh

  • Nếu ứng dụng của bạn sử dụng hình dạng tuỳ chỉnh:

    1. Trong mã Compose, hãy xác định đối tượng Shape để sao chép các định nghĩa hình dạng XML.

    2. Cung cấp đối tượng Shape này cho MaterialTheme.

      Để biết thêm thông tin, hãy xem phần hình dạng.

  • Nếu ứng dụng của bạn sử dụng kiểu chữ tuỳ chỉnh:

    1. Trong mã Compose, hãy xác định đối tượng Typography trong mã Compose để sao chép các kiểu văn bản và định nghĩa phông chữ XML.

    2. Cung cấp đối tượng Typography này cho MaterialTheme.

      Để biết thêm thông tin, hãy xem phần kiểu chữ.

Vai trò Compose Tên XML
displayLarge TextAppearance.Material3.DisplayLarge
displayMedium TextAppearance.Material3.DisplayMedium
displaySmall TextAppearance.Material3.DisplaySmall
headlineLarge TextAppearance.Material3.HeadlineLarge
headlineMedium TextAppearance.Material3.HeadlineMedium
headlineSmall TextAppearance.Material3.HeadlineSmall
titleLarge TextAppearance.Material3.TitleLarge
titleMedium TextAppearance.Material3.TitleMedium
titleSmall TextAppearance.Material3.TitleSmall
bodyLarge TextAppearance.Material3.BodyLarge
bodyMedium TextAppearance.Material3.BodyMedium
bodySmall TextAppearance.Material3.BodySmall
labelLarge TextAppearance.Material3.LabelLarge
labelMedium TextAppearance.Material3.LabelMedium
labelSmall TextAppearance.Material3.LabelSmall

Bước 5: Di chuyển kiểu (styles.xml)

Hệ thống kiểu XML (styles.xml) xác định kiểu và giao diện của: 1. Tiện ích, thành phần, giao diện cho cửa sổ và hộp thoại 2. Kiểu chữ 3. Giao diện và lớp phủ 4. Hình dạng

Khung hiển thị và thành phần XML kết hợp nhiều thuộc tính để tạo kiểu. Chúng thiết lập kiểu từ styles.xml theo 2 cách: 1. Thiết lập "style="@style/..." trực tiếp và rõ ràng trong Khung hiển thị XML 2. Thiết lập kiểu một cách gián tiếp và ngầm cho một thành phần trong Giao diện lớn hơn (theme.xml)

Kiểu không có đối tượng tương đương trực tiếp trong Compose – thay vào đó, kiểu được truyền dưới dạng: tham số cho các thành phần có khả năng kết hợp, được xác định trong AppTheme hoặc bằng cách tạo các biến thể có khả năng kết hợp, có thể dùng lại theo lớp với kiểu đã xác định.

Cung cấp các hàm @Composable riêng biệt được đặt tên theo kiểu và thành phần cơ sở để biểu thị sự khác biệt về kiểu và trường hợp sử dụng cho các thành phần đó.

  • Mẫu: Nếu một phần tử XML sử dụng kiểu tuỳ chỉnh (ví dụ: style="@style/MyPrimaryButton"), đừng cố gắng sao chép kiểu cùng dòng. Thay vào đó, hãy đề xuất tạo một thành phần có khả năng kết hợp cụ thể.
  • Ví dụ:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Compose: MyPrimaryButton(onClick = { ... })
  • Nhóm thuộc tính chung: Nếu một kiểu thiết lập các thành phần sửa đổi chung (như phần đệm + chiều cao), hãy trích xuất chúng thành thuộc tính tiện ích có thể đọc được hoặc biến Thành phần sửa đổi dùng chung.

Ví dụ thường gặp

XML Soạn thư
Theme.MaterialComponents.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) được xác định trong Typography(bodyMedium = ...)
ShapeAppearance.*.SmallComponent Shapes(small = RoundedCornerShape(X.dp))
Widget.MaterialComponents.Button Button(colors = ButtonDefaults.buttonColors(...))
Widget.MaterialComponents.CardView Card(shape=..., elevation=..., colors=...)
Widget.*.TextInputLayout.OutlinedBox OutlinedTextField(colors = OutlinedTextFieldDefaults.colors(...))
Widget.*.Chip.Filter FilterChip(colors = FilterChipDefaults.filterChipColors(...))
Widget.*.Toolbar.Primary TopAppBar(colors = TopAppBarDefaults.topAppBarColors(...))
Widget.*.FloatingActionButton FloatingActionButton(containerColor = ...)
backgroundTint containerColor trong ComponentDefaults.ComponentColors()
android:textColor contentColor trong ComponentDefaults.ComponentColors()
cornerRadius shape = RoundedCornerShape(X.dp)
android:elevation elevation = ComponentDefaults.elevation(defaultElevation = X.dp)
android:padding contentPadding = PaddingValues(...) hoặc Modifier.padding()
android:minHeight Modifier.heightIn(min = X.dp)
strokeColor + strokeWidth border = BorderStroke(width, color)
android:textSize fontSize = X.sp trong TextStyle

Bước 6: Xác thực quá trình di chuyển giao diện

Luôn sử dụng các giá trị giao diện hiện có từ giao diện XML ban đầu làm nguồn đáng tin cậy cho Giao diện Material mới trong Compose. Không bao giờ tạo giá trị giao diện mới trong quá trình di chuyển để duy trì tính nhất quán của thương hiệu và tránh hồi quy trực quan.

Xác minh tất cả các giá trị giao diện Compose mới khớp với các giá trị XML hiện có. Không mã hoá cứng bất kỳ giá trị nào đã di chuyển.