Gli sviluppatori possono personalizzare il processo di generazione del codice fornendo una mappatura tra un pacchetto UI e un componente di codice esistente, anziché il codice generato. Ciò è vantaggioso quando l'implementazione esistente presenta funzionalità non raggiungibili dal codice generato, come animazione o comportamenti complessi (come un menu a discesa).
Gli sviluppatori specificano come mappare i componenti utilizzando un file di mappatura. Un file di mapping indica al generatore di codice come raggiungere la funzione componibile di destinazione in modo che sia possibile creare il codice client corretto.
Ecco un esempio:
In Figma, un designer crea un componente Card che contiene un'istanza di un componente Play Bar, pacchettizza entrambi i componenti e li invia a uno sviluppatore.
Quando lo sviluppatore importa i pacchetti UI da Figma, in ui-packages
vengono create due directory: card
e play_bar
. Quando il progetto viene creato, vengono create
due funzioni componibili: Card
e PlayBar
. In genere, poiché Card contiene un'istanza Play Bar in Figma, nel codice la funzione componibile Card
contiene una chiamata all'elemento componibile PlayBar
.
Tuttavia, il progettista e lo sviluppatore vogliono che Card
utilizzi invece un componibile esistente, MyExistingPlaybar
, che ha funzionalità difficili da descrivere in Figma. Lo sviluppatore aggiunge quindi un file di mappatura denominato play_bar.json
che mappa il pacchetto UI play_bar
a MyExistingPlaybar
:
{
"target": "MyExistingPlaybar",
"package": "com.example.myApp"
}
Ora, quando lo sviluppatore crea il progetto, Card
chiama MyExistingPlaybar
anziché PlayBar
. Tieni presente che MyExistingPlaybar
deve avere gli stessi
parametri di PlayBar
(anche se possono esserci alcune differenze, come descritto
nella sezione Direttive aggiuntive di seguito).
File di mapping
Nei tuoi progetti Android Studio, i file di mapping vengono aggiunti in
ui-package-resources/mappings
accanto alla cartella ui-packages
. Relay cerca i file di mapping durante la build.
Generare un file di mappatura
L'inoltro può generare un file di mappatura per qualsiasi pacchetto UI importato. Segui questi passaggi:
Fai clic con il pulsante destro del mouse sulla cartella del pacchetto o su qualsiasi file all'interno della cartella
ui-package
di destinazione. Seleziona Genera file di mappatura.Configura le seguenti opzioni nella finestra di dialogo:
Posizione file:imposta la posizione del file di mappatura generato.
Componibile target: imposta il componibile personalizzato che viene utilizzato al posto dell'elemento componibile generato. Puoi utilizzare un elemento componibile esistente o crearne uno nuovo dalla finestra di dialogo. La creazione di un nuovo componibile crea un componibile con gli stessi parametri definiti nel pacchetto UI.
- File generato: imposta le opzioni
generateImplementation
egeneratePreview
nel file di mappatura. Per ulteriori dettagli, consulta la sezione Mappatura dei contenuti dei file di seguito.
Fai clic su Genera file di mappatura. All'interno della cartella
ui-package-resources/mapping
viene creato un nuovo file di mapping con le configurazioni specificate.
Puoi anche aprire la finestra di dialogo Genera file di mapping dall'interfaccia utente del modulo Pacchetto di inoltro seguendo questi passaggi:
Fai clic su un file qualsiasi per un pacchetto UI all'interno della cartella
ui-package
di destinazione.Se la finestra dello strumento di inoltro non si apre automaticamente, fai clic sull'icona di inoltro per aprirla.
Fai clic sul pulsante Genera file di mappatura in Opzioni pacchetto.
Nome file di mappatura
Il nome di un determinato file di mapping deve corrispondere al nome della cartella del pacchetto UI
relativo al componente che sostituisce. Di conseguenza, play_bar.json
mappa il pacchetto UI nella
cartella ui-packages/mappings
a un componente di codice esistente.
Mappatura dei contenuti dei file
Il file di mapping contiene le seguenti proprietà:
target: (obbligatorio) il nome della funzione componibile personalizzata. Per impostazione predefinita, questo è il nome della funzione creata dal codice generato.
"target" : "CustomComposableName"
package: (obbligatorio) il nome del pacchetto in cui si trova il componibile personalizzato. Per impostazione predefinita, questo è il pacchetto della funzione creata dal codice generato.
"package" : "com.example.podcastapp.ui.components"
generateImplementation: (facoltativo) true o false. Se il valore è true, un'implementazione di questo pacchetto UI viene comunque creata nel file di codice generato. Se il valore è false, l'implementazione non viene creata. Questo è vero per impostazione predefinita.
"generateImplementation" : true
generatePreviews: (facoltativo) per true o false. Se il valore è true, viene creata un'anteprima del componente personalizzato mappato nel file di codice generato. Se il valore è false, non viene creata alcuna anteprima. Questo è vero per impostazione predefinita.
"generatePreviews" : true
Varianti mappate
Se un componente Figma ha varianti, il componibile generato contiene parametri di enum che codificano la variante (come descritto nel tutorial Gestione delle varianti di progettazione). Se vuoi mappare un componente Figma con varianti al codice esistente, deve essere mappato a un componibile che accetta gli stessi parametri del componibile generato. Ad esempio, per un componente Figma chiamato Chip con una variante la cui proprietà è ChipType, la firma componibile generata da Chip ha questo aspetto:
@Composable
fun Chip(
modifier: Modifier = Modifier,
chipType: ChipType = ChipType.Red,
chipText: String
) { ... }
Se vuoi che il componente Chip Figma venga mappato a un componibile MyChip
esistente, la firma per MyChip
deve avere la stessa firma del componibile generato (supponendo che non vengano specificate istruzioni aggiuntive).
Concettualmente, ciò suggerisce che il componente di codice esistente è in grado di
utilizzare le stesse varianti di progettazione del componente Figma.
Istruzioni aggiuntive
Ad esempio, se la funzione componibile che vuoi scegliere come target ha la seguente firma:
@Composable
fun MyChip(
modifier: Modifier = Modifier,
chipType: ChipType = ChipType.Red,
description: String // instead of chipText
) { ... }
Puoi aggiungere un blocco fieldMappings
al file di mappatura che influisce sulla modalità di mappatura dei parametri. In questo caso, contiene una mappatura dal parametro chipText
nel parametro Chip
al parametro description
in MyChip
.
{
"target": "MyChip",
"package": "com.example.myApp",
"fieldMappings": [
{
"type": "parameter",
"source": "chipText",
"target": "description"
}
]
}
I tipi di blocco fieldMappings
includono:
parameter
: mappa un campo di un pacchetto UI a un parametro di codice.source
: nome del parametro specificato nel pacchetto UI.target
: nome del parametro specificato nel componente di codice target.
lambda
: mappa un campo di un pacchetto UI a un lambda di contenuti.source
: nome del parametro specificato nel pacchetto UI.target
: nome del parametro specificato nel componente di codice target.
modifier
: mappa un campo di un pacchetto UI a un metodo modifier.source
: nome del parametro specificato nel pacchetto UI.method
: metodo nell'oggetto Modificatore che deve essere richiamato nel codice generato.parameter
: il nome del parametro all'interno del metodo di modifica specificato.library
: il nome del pacchetto qualificato da importare per accedere al metodo Modificatore.scope
: uno dei due valori per indicare l'ambito del modificatore:any
: il modificatore può essere utilizzato in qualsiasi ambito del ricevitore.relay
: il modificatore deve essere utilizzato nell'ambito del ricevitore dell'oggettoRelayContainer
dell'inoltro.
Consigliato per te
- Nota: il testo del link viene visualizzato quando JavaScript è disattivato * Supporta dimensioni di schermi diverse * Istanze di pacchetti nidificati * Release