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é.
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.
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.
- Generated file (Fichier généré) : définit les options
generateImplementation
etgeneratePreview
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).
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.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'objetRelayContainer
de Relay.
Recommandations personnalisées
- Remarque: Le texte du lien s'affiche lorsque JavaScript est désactivé * Compatibilité avec différentes tailles d'écran * Instances de package imbriquées * Versions