نقشه اجزاء به کد موجود

توسعه‌دهندگان می‌توانند فرآیند تولید کد را با ارائه نقشه‌ای بین یک بسته UI و یک جزء کد موجود به جای کد تولید شده، سفارشی کنند. این زمانی مفید است که پیاده‌سازی موجود دارای ویژگی‌هایی باشد که با کد تولید شده مانند انیمیشن یا رفتار پیچیده (مانند منوی کشویی) قابل دستیابی نباشد.

توسعه دهندگان نحوه نگاشت اجزا را با استفاده از یک فایل نگاشت مشخص می کنند. یک فایل نگاشت حداقل به تولید کننده کد می گوید که چگونه به تابع قابل ترکیب هدف برسد تا کد مشتری مناسب ایجاد شود.

در اینجا یک مثال است:

در Figma، یک طراح یک کامپوننت Card ایجاد می‌کند که حاوی نمونه‌ای از یک مؤلفه Play Bar است ، هر دو مؤلفه را بسته‌بندی می‌کند و برای توسعه‌دهنده می‌فرستد.

وقتی توسعه‌دهنده بسته‌های UI را از Figma وارد می‌کند، دو فهرست در ui-packages ایجاد می‌شود: card و play_bar . هنگامی که آنها پروژه را می سازند، دو تابع قابل ترکیب ایجاد می شوند: Card و PlayBar . به طور معمول، از آنجایی که Card شامل یک نمونه Play Bar در Figma است، در کد تابع Composable Card شامل یک تماس با PlayBar composable است.

با این حال، طراح و توسعه‌دهنده می‌خواهند که Card به جای آن از یک موجود ترکیب‌سازی، MyExistingPlaybar استفاده کند، که عملکردی دارد که توصیف آن در Figma دشوار است. بنابراین توسعه دهنده یک فایل نگاشت به نام play_bar.json اضافه می کند که بسته UI play_bar را به MyExistingPlaybar نگاشت می کند:

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

اکنون، زمانی که توسعه‌دهنده پروژه را می‌سازد، Card به جای PlayBar MyExistingPlaybar را فراخوانی می‌کند. توجه داشته باشید که MyExistingPlaybar باید همان پارامترهای PlayBar را داشته باشد (اگرچه ممکن است چند تفاوت وجود داشته باشد، همانطور که در دستورالعمل های اضافی در زیر توضیح داده شده است).

فایل نقشه برداری

در پروژه‌های Android Studio شما، فایل‌های نقشه‌برداری در زیر ui-package-resources/mappings در کنار پوشه ui-packages اضافه می‌شوند. رله در حین ساخت به دنبال فایل های نگاشت می گردد.

یک فایل نقشه برداری ایجاد کنید

Relay می تواند یک فایل نقشه برداری برای هر بسته UI وارد شده ایجاد کند. این مراحل را دنبال کنید:

1. بر روی پوشه بسته یا هر فایلی که داخل پوشه ui-package مورد نظر است کلیک راست کنید. Generate mapping file را انتخاب کنید.

   

2. گزینه های زیر را در دیالوگ پیکربندی کنید:

   

   • مکان فایل: مکان فایل نگاشت تولید شده را تعیین می کند.

   • Target composable: قابل تنظیم سفارشی را تنظیم می کند که به جای آن ساخته شده استفاده می شود. شما این امکان را دارید که از یک کامپوزیشن موجود استفاده کنید یا یک مورد جدید از دیالوگ ایجاد کنید. ایجاد یک composable جدید یک composable با همان پارامترهایی که در بسته UI تعریف شده است ایجاد می کند.

   • فایل Generated: گزینه های generateImplementation و generatePreview را در فایل نگاشت تنظیم می کند. برای جزئیات بیشتر به محتوای فایل نقشه برداری در زیر مراجعه کنید.

3. روی ایجاد فایل نگاشت کلیک کنید. یک فایل نگاشت جدید در داخل پوشه ui-package-resources/mapping با تنظیمات مشخص شده ایجاد می شود.

همچنین می توانید گفتگوی Generate mapping file را از رابط کاربری ماژول بسته Relay با استفاده از این مراحل باز کنید:

1. روی هر فایلی برای بسته UI در داخل پوشه ui-package هدف کلیک کنید.

2. اگر پنجره ابزار Relay به طور خودکار باز نشد، روی نماد Relay کلیک کنید تا پنجره باز شود.

3. روی دکمه Generate mapping file در قسمت Package Options کلیک کنید.

   

نام فایل نقشه برداری

نام یک فایل نگاشت داده شده باید با نام پوشه بسته UI برای مؤلفه ای که جایگزین می شود مطابقت داشته باشد. بنابراین play_bar.json بسته UI را در پوشه ui-packages/mappings به یک جزء کد موجود نگاشت می کند.

نگاشت محتویات فایل

فایل نگاشت دارای ویژگی های زیر است:

• target: (الزامی) نام تابع قابل ترکیب سفارشی شما. به طور پیش فرض، این نام تابع ایجاد شده توسط کد تولید شده است.

  "target" : "CustomComposableName"
  

• بسته: (الزامی) نام بسته ای که قابل ترکیب سفارشی شما در آن قرار دارد. به طور پیش فرض، این بسته تابع ایجاد شده توسط کد تولید شده است.

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

• generateImplementation: (اختیاری) درست یا نادرست. اگر درست باشد، پیاده‌سازی این بسته رابط کاربری همچنان در فایل کد ایجاد شده ایجاد می‌شود. اگر نادرست باشد، پیاده سازی ایجاد نمی شود. به طور پیش فرض، این درست است.

  "generateImplementation" : true
  

• generatePreviews: (اختیاری) درست یا نادرست. اگر درست باشد، پیش نمایشی از مؤلفه سفارشی نگاشت شده در فایل کد ایجاد شده ایجاد می شود. اگر نادرست باشد، هیچ پیش نمایشی ایجاد نمی شود. به طور پیش فرض، این درست است.

  "generatePreviews" : true
  

انواع نقشه برداری شده

اگر یک جزء Figma دارای انواع باشد، آنگاه composable تولید شده حاوی پارامترهای enum است که نوع را رمزگذاری می کند (همانطور که در آموزش Handling Design Variants توضیح داده شده است). اگر می‌خواهید یک مؤلفه Figma را با انواع مختلف به کد موجود نگاشت کنید، باید آن را به یک composable نگاشت کنید که همان پارامترهای composable تولید شده را داشته باشد. به عنوان مثال، برای یک مؤلفه Figma به نام Chip با متغیری که ویژگی آن ChipType است، امضای ترکیب‌پذیر تولید شده توسط تراشه به شکل زیر است:

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

اگر می‌خواهید نقشه مؤلفه Chip Figma را به یک MyChip موجود داشته باشید، امضای MyChip باید همان امضای سازنده ایجاد شده را داشته باشد (با فرض اینکه هیچ دستورالعمل اضافی مشخص نشده باشد). از نظر مفهومی، این نشان می‌دهد که مؤلفه کد موجود قادر به همان گونه‌های طراحی مانند مؤلفه Figma است.

بخشنامه های اضافی

به عنوان مثال، اگر تابع composable که می خواهید هدف قرار دهید دارای امضای زیر باشد:

@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 را به یک محتوا لامبدا نگاشت می کند.
  • source : نام پارامتر همانطور که در بسته UI مشخص شده است.
  • target : نام پارامتر همانطور که در جزء کد هدف مشخص شده است.

• modifier : یک فیلد بسته رابط کاربری را به یک روش اصلاح کننده نگاشت می کند.

  • source : نام پارامتر همانطور که در بسته UI مشخص شده است.
  • method : روشی بر روی شی Modifier که باید در کد تولید شده فراخوانی شود.
  • parameter : نام پارامتر در متد تعدیل کننده مشخص شده.
  • library : نام بسته واجد شرایط برای وارد کردن برای دسترسی به روش Modifier.
  • scope : یکی از دو مقدار برای نشان دادن محدوده Modifier:
  • any : اصلاح کننده را می توان در هر محدوده گیرنده استفاده کرد.
  • relay : اصلاح کننده باید در محدوده گیرنده شی Relay's RelayContainer استفاده شود.