แมปคอมโพเนนต์กับโค้ดที่มีอยู่

นักพัฒนาแอปสามารถปรับแต่งกระบวนการสร้างโค้ดได้โดยระบุการแมประหว่างแพ็กเกจ UI กับคอมโพเนนต์โค้ดที่มีอยู่แทนโค้ดที่สร้างขึ้น ซึ่งจะเป็นประโยชน์เมื่อการติดตั้งใช้งานที่มีอยู่มีฟีเจอร์ที่โค้ดที่สร้างขึ้นไม่สามารถดำเนินการได้ เช่น ภาพเคลื่อนไหวหรือลักษณะการทำงานที่ซับซ้อน (เช่น เมนูแบบเลื่อนลง)

นักพัฒนาแอปจะระบุวิธีแมปคอมโพเนนต์โดยใช้ไฟล์การแมป ไฟล์การแมปจะบอกเครื่องมือสร้างโค้ดอย่างน้อยเกี่ยวกับวิธีเข้าถึงฟังก์ชันคอมโพสิเบิลเป้าหมายเพื่อให้สร้างโค้ดไคลเอ็นต์ที่ถูกต้องได้

มีตัวอย่างดังต่อไปนี้

ใน Figma นักออกแบบจะสร้างคอมโพเนนต์ Card ที่มีอินสแตนซ์ของคอมโพเนนต์ Play Bar แพ็กเกจคอมโพเนนต์ทั้ง 2 รายการ และส่งไปยังนักพัฒนาซอฟต์แวร์

เมื่อนักพัฒนาแอปนําเข้าแพ็กเกจ UI จาก Figma ระบบจะสร้างไดเรกทอรี 2 รายการใน ui-packages ได้แก่ card และ play_bar เมื่อสร้างโปรเจ็กต์ ระบบจะสร้างฟังก์ชันแบบคอมโพสิเบิล 2 รายการ ได้แก่ Card และ PlayBar โดยปกติแล้ว เนื่องจากการ์ดมีอินสแตนซ์ Play Bar ใน Figma โค้ดของฟังก์ชันคอมโพสิเบิล Card จึงมีการเรียกใช้คอมโพสิเบิล PlayBar

อย่างไรก็ตาม นักออกแบบและนักพัฒนาซอฟต์แวร์ต้องการให้ Card ใช้คอมโพสิเบิลที่มีอยู่อย่าง MyExistingPlaybar แทน เนื่องจากมีฟังก์ชันการทำงานที่อธิบายใน Figma ได้ยาก นักพัฒนาแอปจึงเพิ่มไฟล์การแมปชื่อ play_bar.json ซึ่งแมปแพ็กเกจ UI play_bar กับ MyExistingPlaybar ดังนี้

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

ตอนนี้เมื่อนักพัฒนาซอฟต์แวร์สร้างโปรเจ็กต์ Card จะเรียก MyExistingPlaybar แทน PlayBar โปรดทราบว่า MyExistingPlaybar ต้องมีพารามิเตอร์เดียวกับ PlayBar (แม้ว่าจะมีความแตกต่างกันเล็กน้อยตามที่อธิบายไว้ในคำสั่งเพิ่มเติมด้านล่าง)

ไฟล์การแมป

ในโปรเจ็กต์ Android Studio ระบบจะเพิ่มไฟล์การแมปในส่วน ui-package-resources/mappings ข้างโฟลเดอร์ ui-packages Relay จะมองหาไฟล์การแมประหว่างการสร้าง

สร้างไฟล์การแมป

Relay สามารถสร้างไฟล์การแมปสําหรับแพ็กเกจ UI ที่นําเข้า โปรดทำตามขั้นตอนต่อไปนี้

1. คลิกขวาที่โฟลเดอร์แพ็กเกจหรือไฟล์ใดก็ได้ในui-package โฟลเดอร์เป้าหมาย เลือกสร้างไฟล์การแมป

   

2. กำหนดค่าตัวเลือกต่อไปนี้ในกล่องโต้ตอบ

   

   • ตำแหน่งไฟล์: ตั้งค่าตำแหน่งสำหรับไฟล์การแมปที่สร้างขึ้น

   • คอมโพสิเบิลเป้าหมาย: ตั้งค่าคอมโพสิเบิลที่กําหนดเองซึ่งจะใช้แทนคอมโพสิเบิลที่สร้างขึ้น คุณสามารถเลือกใช้คอมโพสิเบิลที่มีอยู่หรือสร้างใหม่จากกล่องโต้ตอบ การสร้างคอมโพสิเบิลใหม่จะสร้างคอมโพสิเบิลที่มีพารามิเตอร์เดียวกันกับที่กําหนดไว้ในแพ็กเกจ UI

   • ไฟล์ที่สร้างขึ้น: ตั้งค่าตัวเลือก generateImplementation และ generatePreview ในไฟล์การแมป ดูรายละเอียดเพิ่มเติมที่หัวข้อการแมปเนื้อหาไฟล์ด้านล่าง

3. คลิกสร้างไฟล์การแมป ระบบจะสร้างไฟล์การแมปใหม่ภายในโฟลเดอร์ ui-package-resources/mapping ที่มีการกำหนดค่าที่ระบุ

นอกจากนี้ คุณยังเปิดกล่องโต้ตอบสร้างไฟล์การแมปจาก UI ของโมดูลแพ็กเกจ Relay ได้โดยใช้ขั้นตอนต่อไปนี้

1. คลิกไฟล์ใดก็ได้สำหรับแพ็กเกจ UI ภายในui-package โฟลเดอร์เป้าหมาย

2. หากหน้าต่างเครื่องมือรีเลย์ไม่เปิดขึ้นโดยอัตโนมัติ ให้คลิกไอคอนรีเลย์เพื่อเปิดหน้าต่าง

3. คลิกปุ่มสร้างไฟล์การแมปในส่วนตัวเลือกแพ็กเกจ

   

ชื่อไฟล์การแมป

ชื่อของไฟล์การแมปหนึ่งๆ ต้องตรงกับชื่อโฟลเดอร์แพ็กเกจ UI สำหรับคอมโพเนนต์ที่จะแทนที่ ดังนั้น play_bar.json จะแมปแพ็กเกจ UI ในโฟลเดอร์ ui-packages/mappings กับคอมโพเนนต์โค้ดที่มีอยู่

การแมปเนื้อหาไฟล์

ไฟล์การแมปมีพร็อพเพอร์ตี้ต่อไปนี้

• target: (ต้องระบุ) ชื่อของฟังก์ชันคอมโพสิเบิลที่กําหนดเอง โดยค่าเริ่มต้น ชื่อนี้จะใช้เป็นชื่อของฟังก์ชันที่สร้างโดยโค้ดที่สร้างขึ้น

  "target" : "CustomComposableName"
  

• package: (ต้องระบุ) ชื่อแพ็กเกจที่คอมโพสิชันที่กำหนดเองอยู่ โดยค่าเริ่มต้น แพ็กเกจนี้จะเป็นของฟังก์ชันที่สร้างโดยโค้ดที่สร้างขึ้น

  "package" : "com.example.podcastapp.ui.components"
  

• generateImplementation: (ไม่บังคับ) จริงหรือเท็จ หากเป็น "จริง" ระบบจะยังคงสร้างการใช้งานแพ็กเกจ UI นี้ในไฟล์โค้ดที่สร้างขึ้น หากเป็นเท็จ ระบบจะไม่สร้างการใช้งาน โดยค่าเริ่มต้น ค่านี้จะตรง

  "generateImplementation" : true
  

• generatePreviews: (ไม่บังคับ) จริงหรือเท็จ หากเป็น True ระบบจะสร้างตัวอย่างคอมโพเนนต์ที่กําหนดเองซึ่งแมปไว้ในไฟล์โค้ดที่สร้างขึ้น หากเป็นเท็จ ระบบจะไม่สร้างตัวอย่างเพลง โดยค่าเริ่มต้น ค่านี้จะตรง

  "generatePreviews" : true
  

ตัวแปรที่แมป

หากคอมโพเนนต์ Figma มีตัวแปร คอมโพสิเบิลที่สร้างขึ้นจะมีพารามิเตอร์ enum ที่เข้ารหัสตัวแปร (ตามที่อธิบายไว้ในบทแนะนำการจัดการตัวแปรการออกแบบ) หากต้องการแมปคอมโพเนนต์ Figma ที่มีตัวแปรกับโค้ดที่มีอยู่ คุณต้องแมปกับคอมโพสิเบิลที่ใช้พารามิเตอร์เดียวกันกับคอมโพสิเบิลที่สร้างขึ้น ตัวอย่างเช่น สําหรับคอมโพเนนต์ Figma ชื่อ Chip ที่มีตัวแปรซึ่งมีพร็อพเพอร์ตี้เป็น ChipType ลายเซ็นคอมโพสิเบิลที่สร้างขึ้นของ Chip จะมีลักษณะดังนี้

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

หากต้องการให้คอมโพเนนต์ชิป Figma แมปกับคอมโพเนนต์ MyChip ที่มีอยู่แล้ว ลายเซ็นของ MyChip ต้องมีลายเซ็นเดียวกับคอมโพเนนต์ที่สร้างขึ้น (ในกรณีที่ไม่ได้ระบุคำสั่งเพิ่มเติม) แนวคิดนี้แสดงให้เห็นว่าคอมโพเนนต์โค้ดที่มีอยู่สามารถใช้รูปแบบการออกแบบเดียวกับคอมโพเนนต์ Figma ได้

คำสั่งเพิ่มเติม

ตัวอย่างเช่น หากฟังก์ชันคอมโพสิเบิลที่คุณต้องการกําหนดเป้าหมายมีลายเซ็นต่อไปนี้

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

คุณสามารถเพิ่มบล็อก fieldMappings ลงในไฟล์การแมปที่ส่งผลต่อวิธีแมปพารามิเตอร์ได้ ในกรณีนี้ จะมีการแมปจากพารามิเตอร์ chipText ใน Chip กับพารามิเตอร์ description ใน MyChip

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

ประเภทของบล็อก fieldMappings มีดังนี้

• parameter: แมปช่องแพ็กเกจ UI กับพารามิเตอร์โค้ด
  • source: ชื่อพารามิเตอร์ตามที่ระบุไว้ในแพ็กเกจ UI
  • target: ชื่อพารามิเตอร์ตามที่ระบุไว้ในคอมโพเนนต์โค้ดเป้าหมาย
• lambda: แมปช่องแพ็กเกจ UI กับ Lambda ของเนื้อหา
  • source: ชื่อพารามิเตอร์ตามที่ระบุไว้ในแพ็กเกจ UI
  • target: ชื่อพารามิเตอร์ตามที่ระบุไว้ในคอมโพเนนต์โค้ดเป้าหมาย

• modifier: แมปช่องแพ็กเกจ UI กับเมธอด modifier

  • source: ชื่อพารามิเตอร์ตามที่ระบุไว้ในแพ็กเกจ UI
  • method: เมธอดบนออบเจ็กต์ตัวแก้ไขที่ควรเรียกใช้ในโค้ดที่สร้างขึ้น
  • parameter: ชื่อพารามิเตอร์ภายในเมธอดตัวแก้ไขที่ระบุ
  • library: ชื่อแพ็กเกจที่ผ่านการรับรองเพื่อนําเข้าเพื่อเข้าถึงเมธอด Modifier
  • scope: ค่าใดค่าหนึ่งต่อไปนี้เพื่อระบุขอบเขตของตัวแก้ไข
  • any: ตัวแก้ไขใช้ได้กับขอบเขตตัวรับสัญญาณใดก็ได้
  • relay: ต้องใช้ในขอบเขตผู้รับของออบเจ็กต์ RelayContainer ของ Relay