Informationen zu UI-Paket und generiertem Code

UI-Paket

UI-Pakete sind eine neue flexible Möglichkeit, UI-Informationen auszutauschen. Designschaffende verwenden das Relay for Figma-Plug-in, um UI-Pakete aus Komponenten in Figma zu erstellen. Dadurch wird das Design zur Verwendung durch Entwickler deklariert. Designschaffende geben dann die URL zu ihrer Figma-Designdatei an die Designschaffenden weiter.

Entwickler verwenden das Android Studio-Plug-in, um UI-Pakete aus der Figma-Designdatei zu importieren. In einem Android Studio-Projekt enthält ein UI-Paket deklarative Beschreibungen der importierten Figma-Komponenten sowie zugehörige Assets, einschließlich Schriftartdateien, Bildern und SVGs.

UI-Pakete sind persistente Artefakte, für die ein Commit für die Versionsverwaltung durchgeführt werden kann. Wenn ein Entwickler ein Figma-Paket in ein Android Studio-Projekt importiert, werden dem Projekt im Ordner ui-packages Dateien hinzugefügt. Hier ist ein Beispiel für ein importiertes UI-Paket:

Inhalt eines UI-Pakets

Ein Projekt mit einem importierten UI-Paket enthält die folgenden Dateien:

  • [component_name].json: Eine JSON-Datei, die die Komponente beschreibt (z. B. story_card.json).
  • config.json: speichert Metadaten für das jeweilige UI-Paket.
  • fonts/: Ordner, in dem die von der Komponente verwendeten Schriftart-Assets gegebenenfalls gespeichert werden.
  • *.png: in der Komponente verwendete Bild-Assets (z. B. menu.png)
  • [component_name]_preview.png: Vorschaubild der Komponente (z. B. story_card_preview.png).
  • *.svg: Vektorgrafiken, die in der Komponente verwendet werden (z. B. ein Dreieck), falls vorhanden.
  • FONTS.txt: Eine Liste der verwendeten Schriftarten, falls vorhanden.
  • DEPS.txt: Namen aller untergeordneten Komponenten.
  • VERSION.txt: Die Relay-Version, die zum Erstellen und Importieren des UI-Pakets verwendet wurde.

Sie werden unter src/main/ui-packages/[package_name] gespeichert.

UI-Pakete entfernen

Wenn Sie ein UI-Paket aus dem Projekt entfernen möchten, löschen Sie den Ordner unter ui-packages/. Wenn Sie das Projekt nach dem Entfernen des Ordners neu erstellen, wird auch der generierte Code entfernt.

Ordnerstruktur mit generiertem Code

Beim Erstellen des Projekts werden diese UI-Pakete in generierten Code umgewandelt, der @Composable-Funktionen enthält, die der Entwickler aufrufen kann. Sie werden unter build/generated/ gespeichert. In der Android-Ansicht werden diese in Ihrem Modulverzeichnis (in diesem Fall dem Verzeichnis app) als java (generated) und res angezeigt.

Ordner, die generierte Dateien in Android Studio enthalten

In den folgenden Screenshots werden die Dateien in diesem Verzeichnis erläutert:

  • Ressourcen wie Schriftarten und Bilder werden nach build/generated/res/relay/ kopiert.

    Generierte Ressourcen im Ordner „res“

  • Der generierte Code jedes UI-Pakets wird unter build/generated/source/relay/ platziert. Der generierte Codeordner jedes UI-Pakets enthält eine einzelne Datei, die der importierten Komponente entspricht. Außerdem enthält sie eine einzelne Datei mit der Endung Fonts.kt, die Verweise auf die Schriftart-Assets enthält, die von der Komponente verwendet werden.

    Generierte Kotlin-Dateien im Ordner „java(generated)“

  • Außerdem gibt es die Laufzeitbibliothek com.google.relay.compose, die die vom generierten Code verwendeten Funktionen bietet.

    Relay-Laufzeitbibliothek

Struktur des generierten Codes

Zusammensetzbare Funktionen

Komponenten in Figma bestehen aus Ebenen. Dieses Design enthält beispielsweise die Frame-Ebene Hello Card mit den beiden untergeordneten Ebenen Image (Bildebene) und Title (eine Textebene):

Hello Card-Komponente mit Bild- und Titelebenen

Wenn dieses Design in Code übersetzt wird, erstellen wir separate zusammensetzbare Funktionen für jede Ebene, wobei der Name der Figma-Ebene der Name der zusammensetzbaren Funktion ist (geändert, um der Kotlin-Syntax zu entsprechen). Die Ebenen werden so übersetzt:

  1. Hello Card-Ebene:

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

  2. Bildebene:

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

  3. Titelebene:

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

Übersetzte Varianten und Parameter von Figma

Wenn eine Figma-Komponente mehrere Varianten hat, enthält der generierte Code eine Aufzählung für jede Varianteneigenschaft. Die Werte in jeder Varianten-Enum entsprechen dem Wert der jeweiligen Varianteneigenschaft. Die zusammensetzbare Funktion enthält einen Parameter für jede Variantenvariante.

// 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 { ... }
           }
       }
   }
}

Alle Inhaltsparameter und Interaktions-Handler einer Figma-Komponente werden in einen Parameter der zusammensetzbaren Funktion umgewandelt. Die unten stehende zusammensetzbare Funktion NewsCard hat vier Inhaltsparameter (ein Bild und drei Strings) und zwei Interaktions-Handler (die letzten beiden Parameter).

/**
 *   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 = {}
) {...}