Ánh xạ bằng biến thể

Nếu hoạt động ánh xạ đơn giản một với một là chưa đủ, bạn có thể tạo hoạt động ánh xạ nâng cao hơn bằng cách sử dụng các biến thể Figma và ghi một hàm có khả năng kết hợp của trình bao bọc để xử lý thông tin của Figma.

Chúng ta sẽ sử dụng thành phần khối này có 3 biến thể — Configuration: success, warningerror (Cấu hình: thành công, cảnh báo và lỗi). Trong mã, các biến thể này tương ứng với các hàm có khả năng kết hợp SuccessChip, WarningChipErrorChip.

Sơ đồ tổng quan về hoạt động ánh xạ bằng biến thể

Tải dự án mẫu xuống

Chúng ta sẽ sử dụng dự án HelloMapping đã tải xuống trong phần trước. Vui lòng làm theo hướng dẫn trên trang Hướng dẫn về thành phần được ánh xạ nếu bạn chưa tải xuống.

Các thành phần hiện có trong mã

Hãy cùng tìm hiểu về mã của các khối này.

Mở com/example/hellomapping/ui/Chip.kt rồi tìm định nghĩa cho SuccessChip, WarningChipErrorChip.

Chip.kt trong khung hiển thị Android

Dưới đây là chữ ký của các hàm có khả năng kết hợp này. Chúng có cùng tham số nhưng lại hiển thị các thiết kế khác nhau:

@Composable
fun SuccessChip (
    text: String,
    modifier: Modifier = Modifier
) { … }

@Composable
fun WarningChip (
    text: String,
    modifier: Modifier = Modifier
) { … }

@Composable
fun ErrorChip (
    text: String,
    modifier: Modifier = Modifier
) { … }

Ví dụ về lệnh sao chép trong Figma

Chúng ta sẽ dùng một tệp hiện có trong Figma làm ví dụ cho hướng dẫn này. Hãy nhớ đăng nhập vào tài khoản Figma.

  1. Tải Mapping-With-Variants.fig xuống máy tính.
  2. Trong Figma, hãy chuyển đến trình duyệt tệp. Dọc phía bên trái, hãy di chuột qua Drafts (Bản nháp). Biểu tượng + sẽ xuất hiện — nhấp vào biểu tượng này rồi nhấp vào Import (Nhập) để nhập tệp Mapping-With-Variants.fig bạn vừa tải xuống.

    Mapping-With-Variants.fig

Tạo Gói giao diện người dùng trong Figma

Tệp này có thành phần Chip (Khối) đã được thiết lập bằng các biến thể và một bố cục của thẻ mà chúng ta muốn thêm khối vào đó. Chúng ta sẽ thêm một tham số để truyền nội dung văn bản.

  1. Khi trình bổ trợ Chuyển tiếp cho Figma (Relay for Figma) mở ra, hãy chọn thành phần Chip (Khối) rồi nhấp vào Create UI Package (Tạo Gói giao diện người dùng).

    Nút Create UI Package (Tạo Gói giao diện người dùng) trong trình bổ trợ
  2. Khi thành phần Chip (Khối) vẫn được chọn, hãy thêm nội dung mô tả vào hộp tóm tắt, ví dụ: "Chip component to display status, mapped to SuccessChip, WarningChip and ErrorChip" (Thành phần khối để hiển thị trạng thái, được ánh xạ đến SuccessChip, WarningChip và ErrorChip).

  3. Chọn lớp text (văn bản) ở một trong các biến thể khối (trên máy Mac: ⌘ + nhấp vào text, trên Windows hoặc Linux: Ctrl + nhấp vào text). Trong trình bổ trợ Chuyển tiếp cho Figma (Relay for Figma), hãy nhấp vào dấu + bên cạnh Parameters (Tham số) để thêm tham số text-content. Đổi tên tham số thành text (văn bản).

    Trình bổ trợ Figma với StatusCard (Thẻ trạng thái) được chọn

Đặt thành phần được ánh xạ trong một thẻ

Hãy dùng khối này trong một thẻ.

  1. Chọn thành phần StatusCard (Thẻ trạng thái) rồi nhấp vào Create UI Package (Tạo Gói giao diện người dùng).

    Trình bổ trợ Figma với StatusCard (Thẻ trạng thái) được chọn
  2. Sao chép và đặt biến thể Warning (Cảnh báo) của Chip (Khối) vào thẻ trong lớp Chip-Container (Khối-Vùng chứa).

  3. Chọn lớp text (văn bản) bên trong thực thể của nút (trên máy Mac: ⌘ + nhấp vào text, trên Windows hoặc Linux: Ctrl + nhấp vào text), chỉnh sửa nội dung văn bản để ghi đè nội dung bằng Be Careful (Hãy cẩn thận).

    Đặt thực thể của Chip (Khối) vào Thẻ trạng thái (StatusCard)

Sử dụng hàm gói (wrapper)

Trong ví dụ này, chúng ta có một thành phần Figma mà chúng ta muốn ánh xạ đến 3 thành phần có thể kết hợp riêng biệt (trong trường hợp này là SuccessChip, WarningChipErrorChip), tuỳ thuộc vào biến thể. Vì tệp ánh xạ chỉ có thể ánh xạ một thành phần Figma với một hàm có khả năng kết hợp, nên chúng ta cần tạo hàm gói lấy các tham số được truyền từ Figma và gọi một trong 3 thành phần có thể kết hợp, tuỳ thuộc vào biến thể.

Để thuận tiện cho bạn, chúng tôi đã đưa một ví dụ về hàm gói như vậy, MyChip, trong dự án Android Studio có tên HelloMapping.

  1. Chuyển đến Android Studio và mở com/example/hellomapping/MyChip.kt.

    MyChip.kt trong khung hiển thị Android

    Hàm MyChip có dạng như sau. Tham số design được lấy từ biến thể đã chọn của Chip. Bạn có thể sử dụng thông tin này và các tham số khác để thực hiện mọi hoạt động chuyển đổi nâng cao trong mã.

    @Composable
    fun MyChip(
        modifier: Modifier = Modifier,
        design: String = "Configuration=Success",  // See note below
        text: String
    ) {
        when (design) {
            "Configuration=Success" -> SuccessChip(modifier = modifier, text = text)
            "Configuration=Warning" -> WarningChip(modifier = modifier, text = text)
            "Configuration=Error" -> ErrorChip(modifier = modifier, text = text)
        }
    }
    

Ghi tệp ánh xạ

Tạo một tệp ánh xạ để ánh xạ thành phần đóng gói trong Figma với hàm của trình bao bọc mà bạn vừa tạo.

  1. Chuyển đến dự án Android Studio có tên HelloMapping và chọn khung hiển thị Project (Dự án).

    Khung hiển thị Project (Dự án) trong trình đơn thả xuống
  2. Trong ui-package-resources/mappings/ (tạo trong hướng dẫn ánh xạ một với một), hãy tạo một tệp có tên là chip.map.

    chip.map trong khung hiển thị Project (Dự án)
  3. Sao chép và dán mã sau, sau đó lưu và đóng tệp. Tệp này cho trình tạo mã biết cách truy cập hàm có khả năng kết hợp mong muốn, trong trường hợp này là com.example.hellomapping.MyChip.

    {
        "target": "MyChip",
        "package": "com.example.hellomapping"
    }
    

Nhập thiết kế của Figma

Hãy cùng xem thành phần này trong mã!

  1. Thêm phiên bản mới đã đặt tên của tệp Figma. Nhấp vào File (Tệp) > Save to Version History (Lưu vào nhật ký phiên bản) rồi nhập tiêu đề và nội dung mô tả về phiên bản mới (mọi tiêu đề và nội dung mô tả đều dùng được ở đây).
  2. Ở góc trên bên phải của Figma, hãy nhấp vào nút Share (Chia sẻ). Trong hộp thoại mở ra, hãy nhấp vào Copy link (Sao chép đường liên kết).
  3. Chuyển sang dự án Android Studio. Chuyển đến File > New > Import UI Packages… (Tệp > Mới > Nhập Gói giao diện người dùng…) trên thanh trình đơn của Android Studio.
  4. Dán URL của tệp Figma và rồi nhấp vào Next (Tiếp theo). Nếu bạn thấy lời nhắc dạng chuỗi khoá (keychain), hãy nhập mật khẩu rồi nhấp vào Always Allow (Luôn cho phép).
  5. Đợi tệp tải xuống. Sau khi thành công, bạn sẽ thấy bản xem trước của 2 thành phần: chip (khối) và status_card. Nhấp vào Finish (Hoàn tất).
  6. Nhấp vào Nút Tạo dự án trên thanh công cụ chính để tạo dự án. Quá trình này có thể mất vài phút. Nhấp vào thẻ Build (Tạo) ở cuối Android Studio để xem các kết quả về bản dựng.

Kiểm tra mã đã tạo

Mã đã tạo hiện được thêm vào dự án của bạn.

  1. Trong khung hiển thị Android, hãy mở app/java/com/example/hellomapping/statuscard/StatusCard.kt, đây là mã Jetpack Compose đã tạo cho thành phần Figma StatusCard (Thẻ trạng thái).

    Thẻ trạng thái (StatusCard) trong khung hiển thị Android
  2. Bạn sẽ thấy bản xem trước của thẻ đã nhập.

    Xem trước Thẻ trạng thái (StatusCard)

    Đây là mã được tạo trong Jetpack Compose cho thành phần Figma. Trong mã, bạn có thể thấy rằng MyChip được dùng thay cho khối, với các thông số dựa trên nội dung văn bản và biến thể đã chọn trong tệp Figma (xin lưu ý rằng, trong một phiên bản sắp tới của Relay, tham số design sẽ an toàn về loại hơn so với chuỗi).

    @Composable
    fun ChipInstance(modifier: Modifier = Modifier) {
        MyChip(
            design = "Configuration=Warning",
            text = "Be Careful",
            modifier = modifier
        )
    }