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

Khi đưa Compose vào một ứng dụng hiện có, 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á tính năng tạo giao diện bằng XML.

Bạn có thể sử dụng công cụ Material Theme Builder để 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 chủ đề (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.
Shape Một đối tượng Compose dùng để xác định các hình dạng thành phần tuỳ chỉnh cho một 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 một MaterialTheme.
Color 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 tạo giao diện Android được xác định trong các tệp XML, do hệ thống View 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á tính năng tạo giao diện bằng 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 việc tạo giao diện bằng 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 XML View. 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 các 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à định vị tất cả các tệp và tài nguyên XML cần thiết cho việc tạo giao diện: bộ đủ điều kiện và bảng phối màu sáng và tối, 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 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àu hex đượ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ã hex; hãy đặt tên theo vai trò của màu.

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 dùng các hình dạng tuỳ chỉnh:

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

    2. Cung cấp đối tượng Shape 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 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 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ác 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 một kiểu. Chúng đặt kiểu từ styles.xml theo hai cách: 1. Đặt "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 phạm vi Giao diện lớn hơn (theme.xml)

Các kiểu không có thành phần tương đương trực tiếp trong Compose. Thay vào đó, các kiểu được truyền dưới dạng tham số đến các thành phần kết hợp, đượ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ơ bản, để biểu thị sự khác biệt về kiểu dáng và trường hợp sử dụng cho những 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 kết hợp cụ thể.
  • Ví dụ:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Soạn: MyPrimaryButton(onClick = { ... })
  • Nhóm thuộc tính chung: Nếu một kiểu đặt các đối tượng sửa đổi chung (chẳng hạ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 có thể đọc hoặc một biến Modifier 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ó trong giao diện XML ban đầu làm nguồn dữ liệu chính cho Giao diện Material mới trong Compose. Không bao giờ tạo ra các 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 các lỗi về giao diện.

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