Mapper des composants à un code existant

Les développeurs peuvent personnaliser le processus de génération de code en fournissant un mappage entre un package UI et un composant de code existant au lieu du code généré. Cela s'avère utile lorsque l'implémentation existante comporte des fonctionnalités qui ne peuvent pas être réalisées par le code généré, comme une animation ou un comportement complexe (un menu déroulant, par exemple).

Les développeurs spécifient comment mapper des composants à l'aide d'un fichier de mappage. Celui-ci indique au générateur de code, au minimum, comment accéder à la fonction modulable cible afin de créer le code client approprié.

Voici un exemple :

Dans Figma, un concepteur crée un composant Card qui contient une instance du composant Play Bar, regroupe les deux composants dans un package, puis envoie ce dernier à un développeur.

Lorsque le développeur importe les packages UI depuis Figma, deux répertoires sont créés dans ui-packages: card et play_bar. Lorsqu'il compile le projet, deux fonctions modulables sont créées : Card et PlayBar. En général, comme Card contient une instance de Play Bar dans Figma, dans le code, la fonction modulable Card contient un appel au composable PlayBar.

Cependant, le graphiste et le développeur souhaitent que Card utilise à la place un composable existant, MyExistingPlaybar, dont la fonctionnalité est difficile à décrire dans Figma. Le développeur ajoute donc un fichier de mappage appelé play_bar.json, qui mappe le package UI play_bar à MyExistingPlaybar:

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

Désormais, lorsque le développeur compile le projet, Card appelle MyExistingPlaybar au lieu de PlayBar. Notez que les paramètres de MyExistingPlaybar et de PlayBar doivent être identiques (bien qu'il puisse y avoir quelques différences, comme décrit dans les directives supplémentaires ci-dessous).

Fichier de mappage

Dans vos projets Android Studio, les fichiers de mappage sont ajoutés sous ui-package-resources/mappings à côté du dossier ui-packages. Relay recherche des fichiers de mappage lors de la compilation.

Générer un fichier de mappage

Relay peut générer un fichier de mappage pour tout package UI importé. Procédez comme suit:

1. Effectuez un clic droit sur le dossier du package ou sur un fichier du dossier ui-package cible. Sélectionnez Générer un fichier de mappage.

   

2. Configurez les options suivantes dans la boîte de dialogue:

   

   • Emplacement du fichier:définit l'emplacement du fichier de mappage généré.

   • Composable cible:définit le composable personnalisé utilisé à la place du composable généré. Vous pouvez utiliser un composable existant ou en créer un à partir de la boîte de dialogue. La création d'un composable crée un composable avec les mêmes paramètres que ceux définis dans le package d'interface utilisateur.

   • Fichier généré:définit les options generateImplementation et generatePreview dans le fichier de mappage. Pour en savoir plus, consultez la section Mappeur de contenu de fichier ci-dessous.

3. Cliquez sur Générer un fichier de mappage. Un nouveau fichier de mappage est créé dans le dossier ui-package-resources/mapping avec les configurations spécifiées.

Vous pouvez également ouvrir la boîte de dialogue Generate mapping file (Générer un fichier de mappage) à partir de l'interface utilisateur du module de package Relay en procédant comme suit:

1. Cliquez sur n'importe quel fichier d'un package UI dans le dossier ui-package cible.

2. Si la fenêtre de l'outil de relais ne s'ouvre pas automatiquement, cliquez sur l'icône de relais pour l'ouvrir.

3. Cliquez sur le bouton Generate mapping file (Générer le fichier de mappage) sous Package Options (Options de package).

   

Nom du fichier de mappage

Le nom d'un fichier de mappage doit correspondre au nom du dossier du package UI correspondant au composant qu'il remplace. play_bar.json mappe donc le package UI du dossier ui-packages/mappings à un composant de code existant.

Contenu du fichier de mappage

Le fichier de mappage contient les propriétés suivantes:

• target : (obligatoire) nom de votre fonction composable personnalisée. Par défaut, il s'agit du nom de la fonction créée par le code généré.

  "target" : "CustomComposableName"
  

• package : (obligatoire) nom du package dans lequel se trouve votre composable personnalisé. Par défaut, il s'agit du package de la fonction créée par le code généré.

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

• generateImplementation : (facultatif) "true" ou "false". Si la valeur est "true", une implémentation de ce package d'UI est toujours créée dans le fichier de code généré. Si la valeur est "false", l'implémentation n'est pas créée. Par défaut, cette valeur est "true".

  "generateImplementation" : true
  

• generatePreviews : (facultatif) "true" ou "false". Si la valeur est "true", un aperçu du composant personnalisé mappé est créé dans le fichier de code généré. Si la valeur est "false", aucune prévisualisation n'est créée. Par défaut, cette valeur est "true".

  "generatePreviews" : true
  

Variantes mappées

Si un composant Figma comporte des variantes, le composable généré contient des paramètres d'énumération qui encodent la variante (comme décrit dans le tutoriel Gestion des variantes de conception). Si vous souhaitez mapper un composant Figma avec des variantes à un code existant, vous devez le mapper à un composable qui utilise les mêmes paramètres que le composable généré. Par exemple, pour un composant Figma appelé Chip avec une variante dont la propriété est ChipType, la signature composable générée par Chip se présente comme suit:

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

Si vous souhaitez que le composant Figma Chip soit mappé à un composable MyChip existant, la signature de MyChip doit être la même que celle du composable généré (en supposant qu'aucune directive supplémentaire ne soit spécifiée). D'un point de vue conceptuel, cela indique que le composant de code existant est compatible avec les mêmes variantes de conception que le composant Figma.

Directives supplémentaires

Par exemple, si la fonction composable que vous souhaitez cibler a la signature suivante:

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

Vous pouvez ajouter un bloc fieldMappings au fichier de mappage qui affecte la façon dont les paramètres sont mappés. Dans ce cas, il contient un mappage du paramètre chipText de Chip au paramètre description de MyChip.

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

Les types du bloc fieldMappings sont les suivants :

• parameter: mappe un champ de package UI à un paramètre de code.
  • source: nom du paramètre tel que spécifié dans le package UI.
  • target : nom du paramètre tel que spécifié dans le composant du code cible.
• lambda: mappe un champ de package UI à un lambda de contenu.
  • source: nom du paramètre tel que spécifié dans le package UI.
  • target : nom du paramètre tel que spécifié dans le composant du code cible.

• modifier: mappe un champ de package UI à une méthode modifier.

  • source: nom du paramètre tel que spécifié dans le package UI.
  • method: méthode de l'objet Modifier qui doit être appelée dans le code généré.
  • parameter : nom du paramètre dans la méthode Modifier spécifiée.
  • library : nom du package qualifié à importer pour accéder à la méthode Modifier.
  • scope : l'une des deux valeurs suivantes pour indiquer le champ d'application du modificateur :
  • any : le modificateur peut être utilisé dans n'importe quel champ d'application du récepteur.
  • relay: le modificateur doit être utilisé dans le champ d'application du récepteur de l'objet RelayContainer de Relay.