Informazioni sul pacchetto UI e sul codice generato

Pacchetto UI

I pacchetti UI rappresentano un nuovo modo flessibile per scambiare informazioni relative all'interfaccia utente. I designer usano il plug-in Relay for Figma per creare pacchetti UI dai componenti di Figma. In questo modo si dichiara che il design è pronto per l'uso da parte degli sviluppatori. I designer forniscono agli sviluppatori l'URL del file di progettazione Figma.

Gli sviluppatori usano il plug-in di Android Studio per importare pacchetti UI dal file di progettazione Figma. In un progetto Android Studio, un pacchetto UI contiene descrizioni dichiarative dei componenti Figma importati insieme agli asset associati, inclusi file di caratteri, immagini e SVG.

I pacchetti UI sono artefatti permanenti e possono essere sottoposti al controllo del codice sorgente. Quando uno sviluppatore importa un pacchetto Figma in un progetto Android Studio, i file vengono aggiunti al progetto all'interno della cartella ui-packages. Ecco un esempio di pacchetto UI importato:

Contenuti di un pacchetto UI

Un progetto con un pacchetto UI importato contiene i seguenti file:

  • [component_name].json: un file JSON che descrive il componente (ad esempio, story_card.json).
  • config.json: archivia i metadati per il pacchetto UI specifico.
  • fonts/: cartella in cui sono archiviati gli eventuali asset del carattere utilizzati dal componente.
  • *.png: asset immagine utilizzati nel componente (ad esempio, menu.png), se presenti.
  • [component_name]_preview.png: immagine di anteprima del componente, ad esempio story_card_preview.png.
  • *.svg: risorse grafiche vettoriali utilizzate nel componente (ad esempio un triangolo), se presenti.
  • FONTS.txt: un elenco di eventuali caratteri utilizzati.
  • DEPS.txt: nomi dei componenti secondari.
  • VERSION.txt: la versione dell'inoltro utilizzata per creare e importare il pacchetto UI.

Questi dati sono memorizzati in src/main/ui-packages/[package_name].

Rimozione dei pacchetti UI

Per rimuovere un pacchetto UI dal progetto, puoi eliminare la cartella in ui-packages/. Per ricostruire il progetto dopo la rimozione della cartella viene rimosso anche il codice generato.

Struttura della cartella del codice generato

Durante la creazione del progetto, questi pacchetti UI vengono trasformati in codice generato contenente funzioni @Composable che lo sviluppatore può richiamare. Questi valori sono archiviati in build/generated/. Nella visualizzazione Android, questi appaiono come java (generated) e res nella directory del modulo (in questo caso, la directory app).

Cartelle che contengono file generati in Android Studio

I seguenti screenshot illustrano i file di questa directory:

  • Le risorse, come caratteri e immagini, vengono copiate in build/generated/res/relay/.

    Risorse generate nella cartella res

  • Ogni pacchetto UI ha il proprio codice generato posizionato in build/generated/source/relay/. La cartella del codice generato di ogni pacchetto UI ha un singolo file corrispondente al componente importato. Contiene inoltre un singolo file che termina con Fonts.kt, che contiene riferimenti agli asset del carattere utilizzati dal componente.

    File Kotlin generati nella cartella java(generate)

  • C'è anche una libreria di runtime, com.google.relay.compose, che fornisce le funzionalità utilizzate dal codice generato.

    Libreria di runtime per l'inoltro

Struttura del codice generato

Componibili

I componenti in Figma sono costituiti da livelli. Ad esempio, questo design contiene un livello frame Hello Card, che contiene due livelli secondari, Immagine (un livello immagine) e Titolo (un livello di testo):

Componente Scheda di Ciao con livelli Immagine e Titolo

Quando questo progetto viene tradotto in codice, creiamo funzioni componibili separate per ogni livello, dove il nome del livello Figma è quello della funzione componibile (modificata per conformarsi alla sintassi di Kotlin). I livelli sono tradotti come segue:

  1. Livello Hello Card:

    @Composable
fun HelloCard(
  modifier: Modifier = Modifier,
  title: String
) {
  TopLevel(modifier = modifier) {
      Image()
      Title(title = title)
  }
]

  2. Livello immagine:

    @Composable
fun Image(modifier: Modifier = Modifier) {
  Image(...)
}

  3. Livello Title:

    @Composable
fun Title(
  title: String,
  modifier: Modifier = Modifier
) {
  Text(...)
}

Varianti e parametri Figma tradotte

Se un componente Figma ha più varianti, il codice generato include un'enum per ogni proprietà delle varianti. I valori nell'enumerazione di ogni variante corrispondono al valore della proprietà della variante. Il componibile include un parametro per ogni enumerazione delle varianti.

// Design to select for NewsCard
enum class View {
    HeroItem,
    ArticleItem,
    AudioItem
}

/**
 *   This composable was generated from the UI Package 'news_card'.
 *   Generated code; do not edit directly
 */
@Composable
fun NewsCard(
    modifier: Modifier = Modifier,
    view: View = View.HeroItem,
    onNewsCardTapped: () -> Unit = {},
    thumbnail: Painter,
    headline: String,
    author: String,
    date: String,
    onMenuTapped: () -> Unit = {}
) {
       when (view) {
           View.HeroItem -> TopLevelViewHeroItem(...) {
               ContentViewHeroItem { ... }
           }
           View.ArticleItem -> TopLevelViewArticleItem(...) {
               ContentViewArticleItem { ... }
           }
           View.AudioItem -> TopLevelViewAudioItem(...) {
               ContentViewAudioItem { ... }
           }
       }
   }
}

Ogni parametro dei contenuti e gestore di interazione di un componente Figma viene tradotto in un parametro del componibile. L'elemento componibile NewsCard di seguito ha quattro parametri di contenuti (un'immagine e tre stringhe) e due gestori di interazione (gli ultimi due parametri).

/**
 *   This composable was generated from the UI Package 'news_card'.
 *   Generated code; do not edit directly
 */
@Composable
fun NewsCard(
    modifier: Modifier = Modifier,
    view: View = View.HeroItem,
    thumbnail: Painter,
    headline: String,
    author: String,
    date: String,
    onNewsCardTapped: () -> Unit = {},
    onMenuTapped: () -> Unit = {}
) {...}