Сопоставьте компоненты с существующим кодом

Разработчики могут настроить процесс генерации кода, предоставив сопоставление между пакетом пользовательского интерфейса и существующим компонентом кода вместо сгенерированного кода. Это полезно, когда существующая реализация имеет функции, которые невозможно реализовать с помощью сгенерированного кода, например анимацию или сложное поведение (например, раскрывающееся меню).

Разработчики указывают, как сопоставлять компоненты с помощью файла сопоставления. Файл сопоставления сообщает генератору кода, как минимум, как достичь целевой компонуемой функции, чтобы можно было создать правильный клиентский код.

Вот пример:

В Figma дизайнер создает компонент Card , который содержит экземпляр компонента Play Bar , упаковывает оба компонента и отправляет их разработчику.

Когда разработчик импортирует пакеты пользовательского интерфейса из Figma, в ui-packages создаются два каталога: card и play_bar . При сборке проекта создаются две составные функции: Card и PlayBar . Обычно, поскольку Card содержит экземпляр Play Bar в Figma, в коде компонуемая функция Card содержит вызов компонуемого PlayBar .

Однако дизайнер и разработчик хотят, чтобы Card вместо этого использовал существующий компонуемый объект MyExistingPlaybar , обладающий функциональностью, которую сложно описать в Figma. Поэтому разработчик добавляет файл сопоставления с именем play_bar.json , который сопоставляет пакет пользовательского интерфейса play_bar с MyExistingPlaybar :

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

Теперь, когда разработчик собирает проект, Card вызывает MyExistingPlaybar вместо PlayBar . Обратите внимание, что MyExistingPlaybar должен иметь те же параметры, что и PlayBar (хотя могут быть некоторые различия, как описано в разделе «Дополнительные директивы» ниже).

Файл сопоставления

В ваших проектах Android Studio файлы сопоставления добавляются в папку ui-package-resources/mappings рядом с папкой ui-packages . Реле ищет файлы сопоставления во время сборки.

Создать файл сопоставления

Relay может создать файл сопоставления для любого импортированного пакета пользовательского интерфейса. Выполните следующие действия:

1. Щелкните правой кнопкой мыши папку пакета или любой файл внутри целевой папки ui-package . Выберите Создать файл сопоставления .

   

2. Настройте следующие параметры в диалоговом окне:

   

   • Местоположение файла: устанавливает местоположение созданного файла сопоставления.

   • Целевой составной объект: устанавливает пользовательский составной объект, который используется вместо сгенерированного составного объекта. У вас есть возможность использовать существующий компонуемый объект или создать новый из диалогового окна. При создании нового составного объекта создается составной объект с теми же параметрами, которые определены в пакете пользовательского интерфейса.

   Примечание. Целевой составной элемент должен начинаться с заглавной буквы.
   • Сгенерированный файл: устанавливает generateImplementation generatePreview сопоставления. Для получения более подробной информации см. Содержимое файла сопоставления ниже.

3. Нажмите Создать файл сопоставления . Новый файл сопоставления создается внутри папки ui-package-resources/mapping с указанными конфигурациями.

Вы также можете открыть диалоговое окно «Создать файл сопоставления» из пользовательского интерфейса модуля пакета Relay, выполнив следующие действия:

1. Щелкните любой файл пакета пользовательского интерфейса в целевой папке ui-package .

2. Если окно инструмента «Реле» не открывается автоматически, щелкните значок «Реле», чтобы открыть окно.

3. Нажмите кнопку «Создать файл сопоставления» в разделе «Параметры пакета» .

   

   Примечание. Если для выбранного пакета пользовательского интерфейса существует файл сопоставления, вместо него отображается ссылка для открытия файла.

Имя файла сопоставления

Имя данного файла сопоставления должно совпадать с именем папки пакета пользовательского интерфейса для компонента, который он заменяет. Таким образом, play_bar.json сопоставляет пакет пользовательского интерфейса в папке ui-packages/mappings с существующим компонентом кода.

Сопоставление содержимого файла

Файл сопоставления содержит следующие свойства:

• target: (Обязательно) Имя вашей пользовательской составной функции. По умолчанию это имя функции, созданной сгенерированным кодом.

  "target" : "CustomComposableName"
  

• package: (Обязательно) Имя пакета, в котором находится ваш собственный составной объект. По умолчанию это пакет функции, созданной сгенерированным кодом.

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

• генерироватьImplementation: (Необязательно) true или false. Если это правда, реализация этого пакета пользовательского интерфейса по-прежнему создается в сгенерированном файле кода. Если false, реализация не создается. По умолчанию это правда.

  "generateImplementation" : true
  

• generPreviews: (Необязательно) true или false. Если значение равно true, в сгенерированном файле кода создается предварительный просмотр сопоставленного пользовательского компонента. Если false, предварительный просмотр не создается. По умолчанию это правда.

  "generatePreviews" : true
  

Сопоставленные варианты

Если у компонента Figma есть варианты, то сгенерированный составной объект содержит параметры перечисления, которые кодируют вариант (как описано в руководстве «Обработка вариантов дизайна »). Если вы хотите сопоставить компонент Figma с вариантами с существующим кодом, его необходимо сопоставить с составным объектом, который принимает те же параметры, что и сгенерированный составной объект. Например, для компонента Figma под названием Chip с вариантом, свойством которого является ChipType, сгенерированная составная подпись Chip выглядит следующим образом:

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

Если вы хотите, чтобы компонент Chip 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 : сопоставляет поле пакета пользовательского интерфейса с параметром кода.
  • source : имя параметра, указанное в пакете пользовательского интерфейса.
  • target : Имя параметра, указанное в компоненте целевого кода.
• lambda : сопоставляет поле пакета пользовательского интерфейса с лямбда-выражением содержимого.
  • source : имя параметра, указанное в пакете пользовательского интерфейса.
  • target : Имя параметра, указанное в компоненте целевого кода.

• modifier : сопоставляет поле пакета пользовательского интерфейса с методом модификатора .

  Примечание. Этот тип сопоставления находится в стадии разработки, в частности обработка областей получателя.
  • source : имя параметра, указанное в пакете пользовательского интерфейса.
  • method : метод объекта модификатора, который должен быть вызван в сгенерированном коде.
  • parameter : Имя параметра в указанном методе модификатора.
  • library : полное имя пакета, который нужно импортировать для доступа к методу модификатора.
  • scope : одно из двух значений, указывающих область действия модификатора:
  • any : модификатор можно использовать в любой области приемника.
  • relay : модификатор должен использоваться в области получателя объекта RelayContainer реле.