Cette page a été traduite par l'API Cloud Translation.

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. Un fichier de mappage indique au générateur de code, au minimum, comment atteindre la fonction modulable cible afin de créer le code client approprié.

Diagramme de présentation des composants mappés

Voici un exemple :

Dans Figma, un concepteur crée un composant Card qui contient une instance d'un composant Play Bar, empaquette les deux composants et les envoie à 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 les fichiers de mappage pendant la compilation.

Fichier de mappage dans la vue du projet

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:

Effectuez un clic droit sur le dossier du package ou sur n'importe quel fichier du dossier ui-package cible. Sélectionnez Générer le fichier de mappage.
Configurez les options suivantes dans la boîte de dialogue:
- File location (Emplacement du fichier) : définit l'emplacement du fichier de mappage généré.
- Target composable (Composable cible) : définit le composable personnalisé qui est utilisé à la place du composable généré. Vous pouvez utiliser un composable existant ou en créer un depuis 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 UI.
Remarque :Le composable cible doit commencer par une lettre majuscule.
- Generated file (Fichier généré) : définit les options generateImplementation et generatePreview dans le fichier de mappage. Pour en savoir plus, consultez la section Mappage du contenu du fichier ci-dessous.
Cliquez sur Générer un fichier de mappage. Un 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 du package Relay en procédant comme suit:

Cliquez sur n'importe quel fichier d'un package UI dans le dossier ui-package cible.
Si la fenêtre de l'outil Relay ne s'ouvre pas automatiquement, cliquez sur l'icône Relay pour l'ouvrir.
Cliquez sur le bouton Generate mapping file (Générer le fichier de mappage) sous Package Options (Options du package).

Remarque :Si un fichier de mappage existe pour le package UI sélectionné, un lien permettant d'ouvrir le fichier s'affiche à la place.

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) vrai ou faux. Si la valeur est "true", une implémentation de ce package 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) vrai ou faux. 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", aucun aperçu n'est créé. 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 Gérer les variantes de conception). Si vous souhaitez mapper un composant Figma avec des variantes à du 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 Chip Figma soit mappé à un composable MyChip existant, la signature de MyChip doit avoir la même signature que le composable généré (en supposant qu'aucune directive supplémentaire n'est 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.

Instructions supplémentaires

Par exemple, si la fonction composable que vous souhaitez cibler possède la signature suivante:

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

Vous pouvez ajouter au fichier de mappage un bloc fieldMappings qui affecte la façon dont les paramètres sont mappés. Ici, il contient un mappage entre le paramètre chipText de Chip et le 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.

Remarque :Ce type de mappage est en cours d'incubation, en particulier la gestion des champs d'application des destinataires.
- source: nom du paramètre tel que spécifié dans le package UI.
- method: méthode de l'objet Modifier qui doit être appelé 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.

Recommandations personnalisées

Remarque: Le texte du lien s'affiche lorsque JavaScript est désactivé * Créer des mises en page adaptatives * Instances de package imbriquées * Versions