Memetakan komponen ke kode yang ada

Developer dapat menyesuaikan proses pembuatan kode dengan menyediakan pemetaan antara Paket UI dan komponen kode yang sudah ada, bukan kode yang dihasilkan. Hal ini bermanfaat jika implementasi yang sudah ada memiliki fitur yang tidak dapat dicapai oleh kode yang dihasilkan seperti animasi atau perilaku kompleks (seperti menu drop-down).

Developer menentukan cara memetakan komponen menggunakan file pemetaan. File pemetaan setidaknya akan memberi tahu generator kode cara menjangkau fungsi composable target sehingga kode klien yang tepat dapat dibuat.

Diagram ringkasan komponen 
yang dipetakan

Berikut ini contohnya:

Di Figma, desainer membuat komponen Kartu yang berisi instance komponen Play Bar, memaketkan kedua komponen, dan mengirimkannya ke developer.

Saat developer mengimpor Paket UI dari Figma, dua direktori dibuat di ui-packages: card dan play_bar. Saat mem-build project, dua fungsi composable akan dibuat: Card dan PlayBar. Biasanya, karena Kartu berisi instance Play Bar di Figma, dalam kode fungsi composable Card berisi panggilan ke composable PlayBar.

Namun, desainer dan developer ingin Card menggunakan composable yang sudah ada, MyExistingPlaybar, yang memiliki fungsi yang sulit dijelaskan di Figma. Jadi, developer menambahkan file pemetaan bernama play_bar.json yang memetakan Paket UI play_bar ke MyExistingPlaybar:

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

Sekarang, saat developer mem-build project, Card memanggil MyExistingPlaybar, bukan PlayBar. Perhatikan bahwa MyExistingPlaybar harus memiliki parameter yang sama dengan PlayBar (meskipun mungkin ada beberapa perbedaan, seperti yang dijelaskan dalam Perintah Tambahan di bawah).

File pemetaan

Dalam project Android Studio, file pemetaan ditambahkan di bagian ui-package-resources/mappings di samping folder ui-packages. Relay mencari file pemetaan selama build.

File pemetaan dalam
tampilan project

Membuat file pemetaan

Relay dapat membuat file pemetaan untuk setiap Paket UI yang diimpor. Ikuti langkah-langkah berikut:

  1. Klik kanan pada folder paket atau file apa pun di dalam folder ui-package target. Pilih Buat file pemetaan.

    Membuat kemampuan file
pemetaan

  2. Konfigurasikan opsi berikut dalam dialog:

    Dialog untuk membuat
file pemetaan

    • File location: Menetapkan lokasi untuk file pemetaan yang dihasilkan.

    • Target composable: Menetapkan composable kustom yang digunakan sebagai pengganti composable yang dihasilkan. Anda memiliki opsi untuk menggunakan composable yang sudah ada atau membuat composable baru dari dialog. Membuat composable baru akan membuat composable dengan parameter yang sama seperti yang ditentukan dalam paket UI.

    • Generated file: Menetapkan opsi generateImplementation dan generatePreview di file pemetaan. Lihat Memetakan konten file di bawah untuk detail selengkapnya.
  3. Klik Buat file pemetaan. File pemetaan baru dibuat di dalam folder ui-package-resources/mapping dengan konfigurasi yang ditentukan.

Anda juga dapat membuka dialog Generate mapping file dari UI modul paket Relay menggunakan langkah-langkah berikut:

  1. Klik file apa pun untuk paket UI di dalam folder ui-package target.

  2. Jika jendela alat Relay tidak terbuka secara otomatis, klik ikon Relay untuk membuka jendela tersebut.

  3. Klik tombol Generate mapping file di bagian Package Options.

    Membuat kemampuan file
pemetaan

Nama file pemetaan

Nama file pemetaan yang diberikan harus cocok dengan nama folder Paket UI untuk komponen yang diganti. Jadi, play_bar.json memetakan Paket UI di folder ui-packages/mappings ke komponen kode yang sudah ada.

Memetakan konten file

File pemetaan berisi properti berikut:

  • target: (Wajib) Nama fungsi composable kustom Anda. Secara default, ini adalah nama fungsi yang dibuat oleh kode yang dihasilkan.

    "target" : "CustomComposableName"
    
  • package: (Wajib) Nama paket tempat composable kustom Anda berada. Secara default, ini adalah paket fungsi yang dibuat oleh kode yang dihasilkan.

    "package" : "com.example.podcastapp.ui.components"
    
  • generateImplementation: (Opsional) benar atau salah. Jika true (benar), implementasi Paket UI ini akan tetap dibuat dalam file kode yang dihasilkan. Jika nilainya adalah salah (false), implementasi tidak akan dibuat. Secara default, ini benar.

    "generateImplementation" : true
    
  • generatePreviews: (Opsional) true atau false. Jika true (benar), pratinjau komponen kustom yang dipetakan akan dibuat dalam file kode yang dihasilkan. Jika nilainya adalah salah, tidak ada pratinjau yang akan dibuat. Secara default, ini benar.

    "generatePreviews" : true
    

Varian yang dipetakan

Jika komponen Figma memiliki varian, composable yang dihasilkan akan berisi parameter enum yang mengenkode varian (seperti yang dijelaskan dalam tutorial Menangani Varian Desain). Jika Anda ingin memetakan komponen Figma dengan varian ke kode yang ada, komponen tersebut harus dipetakan ke composable yang menggunakan parameter yang sama dengan composable yang dihasilkan. Misalnya, untuk komponen Figma bernama Chip dengan varian yang propertinya adalah tanda tangan composable yang dihasilkan ChipType, Chip's, akan terlihat seperti ini:

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

Jika Anda ingin memetakan komponen Figma Chip ke composable MyChip yang ada, tanda tangan untuk MyChip harus memiliki tanda tangan yang sama dengan composable yang dihasilkan (dengan asumsi tidak ada perintah tambahan yang ditentukan). Secara konseptual, ini menunjukkan bahwa komponen kode yang ada dapat memiliki varian desain yang sama seperti komponen Figma.

Perintah tambahan

Misalnya, jika fungsi composable yang ingin Anda targetkan memiliki tanda tangan berikut:

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

Anda dapat menambahkan blok fieldMappings ke file pemetaan yang memengaruhi cara pemetaan parameter. Dalam hal ini, parameter ini berisi pemetaan dari parameter chipText dalam Chip ke parameter description di MyChip.

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

Jenis untuk blok fieldMappings mencakup:

  • parameter: Memetakan kolom Paket UI ke parameter kode.
    • source: Nama parameter seperti yang ditentukan dalam Paket UI.
    • target: Nama parameter seperti yang ditentukan dalam komponen kode target.
  • lambda: Memetakan kolom Paket UI ke lambda konten.
    • source: Nama parameter seperti yang ditentukan dalam Paket UI.
    • target: Nama parameter seperti yang ditentukan dalam komponen kode target.
  • modifier: Memetakan kolom Paket UI ke metode pengubah.

    • source: Nama parameter seperti yang ditentukan dalam Paket UI.
    • method: Metode pada objek Pengubah yang harus dipanggil dalam kode yang dihasilkan.
    • parameter: Nama parameter dalam metode Pengubah yang ditentukan.
    • library: Nama paket yang memenuhi syarat untuk diimpor guna mengakses metode Pengubah.
    • scope: Salah satu dari dua nilai untuk menunjukkan cakupan Pengubah:
    • any: Pengubah dapat digunakan dalam semua cakupan penerima.
    • relay: Pengubah harus digunakan dalam cakupan penerima objek RelayContainer Relay.