Trang này được dịch bởi Cloud Translation API.

Ánh xạ các thành phần với mã hiện có

Nhà phát triển có thể tuỳ chỉnh quy trình tạo mã bằng cách cung cấp quy tắc ánh xạ giữa Gói giao diện người dùng và thành phần mã hiện có thay vì mã được tạo. Điều này có lợi khi cách triển khai hiện tại có các tính năng không thể đạt được bằng mã được tạo, chẳng hạn như ảnh động hoặc hành vi phức tạp (như trình đơn thả xuống).

Nhà phát triển dùng tệp ánh xạ để xác định cách ánh xạ các thành phần. Chí ít, tệp ánh xạ sẽ chỉ dẫn trình tạo mã cách tiếp cận hàm có khả năng kết hợp mục tiêu để có thể tạo đúng mã ứng dụng khách.

Sơ đồ tổng quan về thành phần được ánh xạ

Dưới đây là ví dụ:

Trong Figma, nhà thiết kế tạo thành phần Card (Thẻ) chứa một thực thể của thành phần Play Bar (Thanh phát), đóng gói cả 2 thành phần rồi gửi cho nhà phát triển.

Khi nhà phát triển nhập các Gói giao diện người dùng từ Figma, 2 thư mục sẽ được tạo trong ui-packages: card và play_bar. Khi họ xây dựng dự án, 2 hàm có khả năng kết hợp sẽ được tạo: Card và PlayBar. Thông thường, vì Card (Thẻ) chứa một thực thể của Play Bar (Thanh phát) trong Figma, nên trong mã, hàm có khả năng kết hợp Card chứa lệnh gọi đến thành phần kết hợp PlayBar.

Tuy nhiên, nhà thiết kế và nhà phát triển muốn Card sử dụng thành phần kết hợp hiện có là MyExistingPlaybar, nhưng thành phần này lại có chức năng khó mô tả trong Figma. Do đó, nhà phát triển sẽ thêm một tệp ánh xạ có tên play_bar.json để ánh xạ Gói giao diện người dùng play_bar đến MyExistingPlaybar:

{
    "target": "MyExistingPlaybar",
    "package": "com.example.myApp"
}

Lúc này, khi nhà phát triển xây dựng dự án, Card sẽ gọi MyExistingPlaybar thay vì PlayBar. Hãy lưu ý rằng MyExistingPlaybar phải có cùng tham số với PlayBar (mặc dù có thể có một vài điểm khác biệt, như mô tả trong phần Chỉ dẫn bổ sung dưới đây).

Tệp ánh xạ

Trong các dự án Android Studio, tệp ánh xạ sẽ được thêm bên vào trong ui-package-resources/mappings cạnh thư mục ui-packages. Relay tìm kiếm các tệp ánh xạ trong quá trình xây dựng.

Tệp ánh xạ trong khung hiển thị dự án

Tạo tệp ánh xạ

Relay có thể tạo tệp ánh xạ cho mọi Gói giao diện người dùng đã nhập. Hãy làm theo các bước sau:

Nhấp chuột phải vào thư mục gói hoặc bất kỳ tệp nào bên trong thư mục ui-package mục tiêu. Chọn Tạo tệp ánh xạ.
Định cấu hình các tuỳ chọn sau trong hộp thoại:
- Vị trí tệp: Đặt vị trí cho tệp ánh xạ được tạo.
- Thành phần kết hợp mục tiêu: Đặt thành phần kết hợp tuỳ chỉnh được sử dụng thay cho thành phần kết hợp được tạo. Bạn có thể sử dụng một thành phần kết hợp hiện có hoặc tạo một thành phần kết hợp mới từ hộp thoại. Việc tạo một thành phần kết hợp mới sẽ tạo một thành phần kết hợp có cùng các tham số như được xác định trong gói giao diện người dùng.
Lưu ý: Thành phần kết hợp mục tiêu phải bắt đầu bằng chữ cái viết hoa.
- Tệp đã tạo: Đặt các tuỳ chọn generateImplementation và generatePreview trong tệp ánh xạ. Hãy xem phần Ánh xạ nội dung tệp bên dưới để biết thêm thông tin chi tiết.
Nhấp vào Tạo tệp ánh xạ. Một tệp ánh xạ mới được tạo bên trong thư mục ui-package-resources/mapping với các cấu hình đã chỉ định.

Bạn cũng có thể mở hộp thoại Tạo tệp ánh xạ từ giao diện người dùng mô-đun gói Chuyển tiếp bằng cách làm theo các bước sau:

Nhấp vào tệp bất kỳ của gói giao diện người dùng bên trong thư mục ui-package mục tiêu.
Nếu cửa sổ công cụ Chuyển tiếp không tự động mở, hãy nhấp vào biểu tượng Chuyển tiếp để mở cửa sổ.
Nhấp vào nút Tạo tệp ánh xạ trong phần Package Options (Tuỳ chọn gói).

Lưu ý: Nếu có tệp ánh xạ cho Gói giao diện người dùng đã chọn, thì một đường liên kết để mở tệp sẽ xuất hiện.

Tên tệp ánh xạ

Tên của một tệp ánh xạ nhất định phải khớp với tên của thư mục Gói giao diện người dùng của thành phần mà tệp đó thay thế. Do đó, play_bar.json sẽ ánh xạ Gói giao diện người dùng trong thư mục ui-packages/mappings đến một thành phần mã hiện có.

Ánh xạ nội dung tệp

Tệp ánh xạ chứa các thuộc tính sau:

target: (Bắt buộc) Tên của hàm có khả năng kết hợp tuỳ chỉnh. Theo mặc định, đây là tên của hàm do mã được tạo tạo ra.
```
"target" : "CustomComposableName"
```
package: (Bắt buộc) Tên của gói chứa thành phần kết hợp tuỳ chỉnh. Theo mặc định, đây là gói của hàm do mã được tạo tạo ra.
```
"package" : "com.example.podcastapp.ui.components"
```
generateImplementation: (Không bắt buộc) true hoặc false. Nếu đúng, thì quá trình triển khai Gói giao diện người dùng này vẫn được tạo trong tệp mã được tạo. Nếu giá trị là sai, quá trình triển khai sẽ không được tạo. Theo mặc định, giá trị này là true.
```
"generateImplementation" : true
```
generatePreviews: (Không bắt buộc) true hoặc false. Nếu đúng, bản xem trước của thành phần tuỳ chỉnh đã liên kết sẽ được tạo trong tệp mã đã tạo. Nếu giá trị là false, hệ thống sẽ không tạo bản xem trước. Theo mặc định, giá trị này là true.
```
"generatePreviews" : true
```

Biến thể được liên kết

Nếu một thành phần Figma có các biến thể, thì thành phần kết hợp được tạo sẽ chứa các tham số enum giúp mã hoá biến thể đó (như mô tả trong hướng dẫn Xử lý biến thể thiết kế). Nếu bạn muốn ánh xạ một thành phần Figma có các biến thể đến mã hiện có, thì thành phần đó phải được ánh xạ đến một thành phần kết hợp có các thông số giống với thành phần kết hợp được tạo. Ví dụ: đối với một thành phần Figma có tên Chip với một biến thể có thuộc tính là ChipType, chữ ký có khả năng kết hợp được tạo của Chip sẽ có dạng như sau:

@Composable
fun Chip(
    modifier: Modifier = Modifier,
    chipType: ChipType = ChipType.Red,
    chipText: String
) { ... }

Nếu bạn muốn thành phần Figma Chip ánh xạ đến một thành phần kết hợp MyChip hiện có, thì chữ ký cho MyChip phải có cùng chữ ký với thành phần kết hợp được tạo (giả sử không chỉ định chỉ dẫn bổ sung). Về mặt lý thuyết, điều này cho thấy thành phần mã hiện có có khả năng chứa các biến thể thiết kế giống với thành phần Figma.

Chỉ thị bổ sung

Ví dụ: nếu hàm có khả năng kết hợp mà bạn muốn nhắm đến có chữ ký sau:

@Composable
fun MyChip(
    modifier: Modifier = Modifier,
    chipType: ChipType = ChipType.Red,
    description: String  // instead of chipText
) { ... }

Bạn có thể thêm một khối fieldMappings vào tệp ánh xạ ảnh hưởng đến cách ánh xạ các tham số. Trong trường hợp này, khối này chứa một đường ánh xạ từ tham số chipText trong Chip đến tham số description trong MyChip.

{
    "target": "MyChip",
    "package": "com.example.myApp",
    "fieldMappings": [
        {
            "type": "parameter",
            "source": "chipText",
            "target": "description"
        }
    ]
}

Khối fieldMappings gồm các loại:

parameter: Ánh xạ trường Gói giao diện người dùng đến tham số mã.
- source: Tên tham số như được chỉ định trong Gói giao diện người dùng.
- target: Tên tham số như được chỉ định trong thành phần mã mục tiêu.
lambda: Ánh xạ trường Gói giao diện người dùng đến một lambda nội dung.
- source: Tên tham số như được chỉ định trong Gói giao diện người dùng.
- target: Tên tham số như được chỉ định trong thành phần mã mục tiêu.
modifier: Ánh xạ trường Gói giao diện người dùng đến phương thức đối tượng sửa đổi.

Lưu ý: Loại ánh xạ này đang được ươm, đặc biệt là việc xử lý phạm vi trình thu nhận.
- source: Tên tham số như được chỉ định trong Gói giao diện người dùng.
- method: Phương thức trên đối tượng Đối tượng sửa đổi cần gọi trong mã được tạo.
- parameter: Tên tham số trong phương thức Đối tượng sửa đổi đã chỉ định.
- library: Tên gói đủ điều kiện cần nhập để truy cập vào phương thức Đối tượng sửa đổi.
- scope: Một trong hai giá trị để cho biết phạm vi của Đối tượng sửa đổi:
- any: Bạn có thể sử dụng đối tượng sửa đổi trong bất kỳ phạm vi trình thu nhận nào.
- relay: Đối tượng sửa đổi phải được sử dụng trong phạm vi trình thu nhận của đối tượng RelayContainer trong Relay.