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 ứng dụng của bạn được di chuyển hoàn toàn sang Compose, hãy xoá giao diện XML.

Bạn có thể sử dụng công cụ Trình tạo giao diện Material để di chuyển màu.

Khi bạn 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 thuật ngữ

Thuật ngữ Định nghĩa
MaterialTheme Hàm composable cung cấp giao diện (màu sắc, kiểu chữ, hình dạng) cho các thành phần giao diện người dùng Compose.
Shapes Một đối tượng Compose dùng để xác định hình dạng thành phần tuỳ chỉnh cho MaterialTheme.
Typography Một đối tượng Compose dùng để xác định kiểu văn bản tuỳ chỉnh (bộ phông chữ, kích thước, độ đậm) cho MaterialTheme.
ColorScheme Một đố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 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 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á hoàn toàn giao diện XML.

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

Xác định hệ thống thiết kế được dùng trong dự án Chế độ xem XML. Phân tích lộ trình 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 tệp nguồn của 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ả tài nguyên cũng như tệp XML cần thiết cho giao diện: bảng phối màu sáng và tối, bộ hạn định, giao diện, hình dạng, kích thước, kiểu chữ, kiểu và các tệp liên quan khác.

Bạn có thể sử dụng lại các tài nguyên như chuỗi mà 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ã màu hex được đặt tên. Material 3 sử dụng vai trò ngữ nghĩa (ví dụ: primary, onPrimary, surface). Hãy ngừng đặt tên màu theo mã thập lục phân mà hãy đặt tên theo vai trò của màu.

Ví dụ:

Tên màu XML Vai trò của 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 một đối tượng Shapes để sao chép các định nghĩa hình dạng XML.

    2. Cung cấp đối tượng Shapes này cho MaterialTheme của bạn.

      Để 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 một đối tượng Typography để sao chép 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 của bạn.

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

Vai trò soạn thư 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

Thành phần hiển thị và thành phần XML kết hợp nhiều thuộc tính để tạo kiểu. Họ đặt kiểu từ styles.xml theo hai cách:

  1. Đặt "style="@style/..." trực tiếp và rõ ràng trong Chế độ xem XML
  2. Đặt kiểu gián tiếp và ngầm định cho một thành phần trong một Giao diện lớn hơn (theme.xml)

Kiểu không có thành phần tương đương trực tiếp trong Compose. Thay vào đó, kiểu được truyền dưới dạng: tham số hoặc đối tượng sửa đổi cho thành phần kết hợp, sử dụng Styles API thử nghiệm mới được xác định trong AppTheme hoặc bằng cách tạo các biến thể thành phần kết hợp có thể sử 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 composable cụ thể.
  • Ví dụ:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Compose: MyPrimaryButton(onClick = { ... })
  • Nhóm thuộc tính phổ biến: Nếu một kiểu đặt các đối tượng sửa đổi phổ biến (như khoảng đệm + chiều cao), hãy trích xuất các đối tượng đó vào một thuộc tính tiện ích dễ đọc hoặc một biến Đối tượng sửa đổi dùng chung.

Ví dụ thường gặp

XML Soạn thư
Theme.Material3.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) được xác định trong Typography(bodyMedium = ...)
ShapeAppearance.*.SmallComponent Shapes(small = RoundedCornerShape(X.dp))
Widget.Material3.Button Button(colors = ButtonDefaults.buttonColors(...))
Widget.Material3.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 gốc làm nguồn đáng tin cậy cho Tuỳ chỉnh giao diện Material mới trong Compose. Tuyệt đối không 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 hình ảnh.

Xác minh rằng tất cả giá trị giao diện mới của Compose đều khớp với các giá trị XML hiện có. Đừng cố định giá trị trong mã đối với bất kỳ giá trị nào đã di chuyển.