Entender o pacote da IU e o código gerado

Pacote da IU

Os pacotes são uma nova maneira flexível de trocar informações da IU. Os designers usam o plug-in Relay for Figma para criar pacotes da IU dos componentes do Figma. Essa ação declara que o design está pronto para ser usado pelos desenvolvedores. Os designers fornecem aos desenvolvedores o URL do arquivo de design do Figma.

Os desenvolvedores usam o plug-in do Android Studio para importar pacotes da IU do arquivo de design do Figma. Em um projeto do Android Studio, um pacote da IU contém descrições declarativas dos componentes importados do Figma, além dos recursos associados, incluindo arquivos de fontes, imagens e SVGs.

Os pacotes da IU são artefatos persistentes e podem ser confirmados no controle de origem. Quando um desenvolvedor importa um pacote do Figma para um projeto do Android Studio, os arquivos são adicionados ao projeto na pasta ui-packages. Veja um exemplo de pacote da IU importado:

Conteúdo de um pacote da IU

Um projeto com um pacote da IU importado contém os seguintes arquivos:

  • [component_name].json: um arquivo JSON que descreve o componente, como story_card.json.
  • config.json: armazena metadados para o pacote específico da IU.
  • fonts/: pasta em que os recursos de fonte usados pelo componente são armazenados.
  • *.png: recursos de imagem usados no componente, como menu.png.
  • [component_name]_preview.png: imagem de visualização do componente, como story_card_preview.png.
  • *.svg: recursos gráficos vetoriais usados no componente, como um triângulo.
  • FONTS.txt: lista de fontes usadas.
  • DEPS.txt: nome de qualquer componente filho.
  • VERSION.txt: a versão do Relay usada para criar e importar o pacote da IU.

Eles são armazenados em src/main/ui-packages/[package_name].

Como remover pacotes da IU

Para remover um pacote da IU do projeto, exclua a pasta em ui-packages/. A recriação do projeto após a remoção da pasta também remove o código gerado.

Estrutura da pasta do código gerado

Quando o projeto é criado, esses pacotes da IU são transformados em código gerado com funções @Composable que o desenvolvedor pode invocar. Eles são armazenados em build/generated/. Na visualização do Android, eles aparecem como java (generated) e res no diretório do módulo. Nesse caso, é o diretório app.

Pastas com arquivos gerados no Android Studio

As seguintes capturas de tela percorrem os arquivos desse diretório:

  • Recursos, como fontes e imagens, são copiados para build/generated/res/relay/.

    Recursos gerados na pasta "res"
  • Cada pacote da IU tem o código gerado em build/generated/source/relay/. Cada pasta de código gerado do pacote da IU tem um único arquivo correspondente ao componente que foi importado. Ela também contém um único arquivo que termina em Fonts.kt, com referências aos recursos de fonte usados pelo componente.

    Arquivos Kotlin gerados na pasta java(generated)
  • Há também uma biblioteca de ambiente de execução, com.google.relay.compose, que fornece a funcionalidade usada pelo código gerado.

    Biblioteca de ambiente de execução do Relay

Estrutura do código gerado

Elementos combináveis

Os componentes do Figma são compostos por camadas. Por exemplo, esse design contém uma camada de frame Hello Card, que contém duas camadas filhas, Image (camada de imagem) eTitle (camada de texto):

Componente "Hello Card" com camadas de imagem e texto

Quando esse design é traduzido para código, criamos funções de composição separadas para cada camada, em que o nome da camada do Figma é o nome da função de composição. Ele é modificado para estar em conformidade com a sintaxe do Kotlin. As camadas são traduzidas da seguinte maneira:

  1. Camada Hello Card:

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

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

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

Variantes e parâmetros do Figma traduzidos

Se um componente do Figma tiver diversas variantes, o código gerado vai incluir um tipo enumerado para cada propriedade de variante. Os valores nos tipos enumerados de cada variante correspondem ao valor da propriedade da variante. O elemento combinável inclui um parâmetro para cada tipo enumerado de variante.

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

Cada parâmetro de conteúdo e gerenciador de interação de um componente do Figma é traduzido para um parâmetro do elemento combinável. O elemento NewsCard abaixo tem quatro parâmetros de conteúdo (uma imagem e três strings) e dois gerenciadores de interação (os dois últimos parâmetros).

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