Visualizar a IU com visualizações de composição

Um elemento combinável é definido por uma função e anotado com @Composable:

@Composable
fun SimpleComposable() {
    Text("Hello World")
}

Um simples elemento do texto contendo as palavras "Hello World"

Para permitir uma visualização desse elemento, crie outro elemento combinável, com as anotações @Composable e @Preview. Esse novo elemento combinável com anotações agora contém o elemento criado inicialmente, SimpleComposable:

@Preview
@Composable
fun SimpleComposablePreview() {
    SimpleComposable()
}

A anotação @Preview informa ao Android Studio que esse elemento combinável precisa ser mostrado na visualização de design desse arquivo. Você pode ver atualizações em tempo real na visualização de composição enquanto faz as edições.

GIF mostrando atualizações em tempo real usando a Visualização do Compose

É possível adicionar parâmetros manualmente no código para personalizar a forma como o Android Studio renderiza @Preview. Você pode até mesmo adicionar a anotação @Preview à mesma função várias vezes para visualizar um elemento combinável com propriedades diferentes.

Um dos principais benefícios de usar elementos combináveis @Preview é evitar a dependência do emulador no Android Studio. Você pode salvar a inicialização do emulador, que consome muita memória, para mudanças mais finais de aparência e a capacidade do @Preview de fazer e testar pequenas mudanças de código com facilidade.

Para aproveitar a anotação @Preview da forma mais eficaz, defina as telas em termos do estado que ela recebe como entrada e dos eventos que ela gera.

Defina seu @Preview

O Android Studio oferece alguns recursos para estender visualizações que podem ser compostas. É possível mudar o design do contêiner, interagir com as visualizações ou fazer a implantação delas diretamente em um emulador ou dispositivo.

Dimensões

Por padrão, as dimensões de @Preview são escolhidas automaticamente para agrupar o conteúdo. Para definir as dimensões manualmente, adicione os parâmetros heightDp e widthDp. Esses valores já são interpretados como dp, então não é necessário adicionar .dp a eles:

@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
    Box(Modifier.background(Color.Yellow)) {
        Text("Hello World")
    }
}

Quadrado amarelo com as palavras "Hello World"

Prévias de cores dinâmicas

Se você ativou as cores dinâmicas no seu app, use o atributo wallpaper para alternar planos de fundo e observar como a interface reage às diferentes escolhas dos usuários. Selecione entre os diferentes temas de plano de fundo oferecidos pela classe Wallpaper. Esse recurso requer o Compose 1.4.0 ou mais recente.

Usar com dispositivos diferentes

No Android Studio Flamingo, é possível editar o parâmetro device da anotação de visualização para definir configurações para elementos combináveis em diferentes dispositivos.

Exemplo de função combinável

Quando o parâmetro do dispositivo tem uma string vazia (@Preview(device = "")), é possível invocar o preenchimento automático pressionando Ctrl + Space. Em seguida, é possível definir os valores de cada parâmetro.

Como editar a função de exemplo

No preenchimento automático, você pode selecionar qualquer opção de dispositivo na lista, por exemplo, @Preview(device = "id:pixel_4"). Como alternativa, é possível inserir um dispositivo personalizado escolhendo spec:width=px,height=px,dpi=int… para definir os valores individuais de cada parâmetro.

Lista de especificações

Para aplicar, pressione Enter ou cancele com Esc.

Se você definir um valor inválido, a declaração será sublinhada em vermelho e uma correção poderá estar disponível (Alt + Enter (⌥ + ⏎ para macOS) > Replace with …. A inspeção tenta fornecer uma correção que seja o mais próxima possível da sua entrada.

Exemplo de valor inválido

Localidade

Para testar diferentes localidades de usuários, adicione o parâmetro locale:

@Preview(locale = "fr-rFR")
@Composable
fun DifferentLocaleComposablePreview() {
    Text(text = stringResource(R.string.greeting))
}

Um elemento do texto simples contendo a palavra "Bonjour" com uma bandeira da França

Definir cor do plano de fundo

Por padrão, o elemento combinável é exibido com um plano de fundo transparente. Para adicionar um plano de fundo, adicione os parâmetros showBackground e backgroundColor. Lembre-se de que backgroundColor é um Long de ARGB, e não um valor de Color:

@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
    Text("Hello World")
}

Retângulo verde com as palavras "Hello World"

IU do sistema

Caso precise exibir as barras de status e ação em uma visualização, adicione o parâmetro showSystemUi:

@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
    Text("Hello World")
}

Janela de visualização mostrando uma atividade com as barras de status e de ações.

Modo de interface

O parâmetro uiMode pode usar qualquer uma das constantes Configuration.UI_* e permite que você mude o comportamento da visualização. Por exemplo, você pode definir a visualização para o Modo noturno e ver como o tema reage.

interface da visualização do Compose

LocalInspectionMode

Você pode ler usando o LocalInspectionMode CompositionLocalda propriedade para saber se o elemento combinável está sendo renderizado em uma visualização (dentro de um componente inspecionável). Se a composição for renderizada em uma visualização, o valor da LocalInspectionMode.current será true. Essas informações permitem personalizar a visualização. Por exemplo, é possível mostrar uma imagem marcadora de posição na janela de visualização em vez de mostrar dados reais.

Dessa forma, você também pode contornar as limitações. Por exemplo, mostrar dados de amostra em vez de chamar a solicitação de rede.

@Composable
fun GreetingScreen(name: String) {
    if (LocalInspectionMode.current) {
        // Show this text in a preview window:
        Text("Hello preview user!")
    } else {
        // Show this text in the app:
        Text("Hello $name!")
    }
}

Interagir com o @Preview

O Android Studio oferece recursos que permitem interagir com as prévias definidas. Essa interação ajuda a entender o comportamento de execução das prévias e permite navegar melhor pela interface com as prévias.

Modo interativo

O modo interativo permite interagir com uma visualização de forma semelhante à que você faria em um dispositivo que executa o programa, como um smartphone ou tablet. O modo interativo é isolado em um ambiente de sandbox (ou seja, isolado de outras visualizações), em que é possível clicar em elementos e inserir entradas do usuário na visualização. É uma forma rápida de testar diferentes estados, gestos e até animações do elemento combinável.

Usuário clicando no botão "interativo" da visualização

Vídeo de um usuário interagindo com uma visualização

Navegação de código e contornos de elementos de composição

Passe o cursor sobre uma visualização para ver os contornos dos elementos contidos nela. Clicar em um contorno que pode ser composto aciona a visualização do editor para navegar para a definição.

Usuário passando o cursor sobre uma visualização, fazendo com que o Studio exiba os contornos dos elementos combináveis

Prévia da execução

É possível executar uma @Preview específica em um emulador ou dispositivo físico. A prévia é implantada no mesmo app do projeto, como uma nova Activity. Ela compartilha o mesmo contexto e permissões. Não é necessário escrever um código boilerplate para solicitar uma permissão que já foi concedida.

Clique no ícone Run Preview Ícone "Executar visualização" ao lado da anotação @Preview ou na parte de cima da visualização, e o Android Studio vai implantar essa @Preview no dispositivo conectado ou emulador.

Usuário clicando no botão "deploy" (implantar)

Vídeo do usuário implantando uma visualização no dispositivo

Copiar renderização de @Preview

Cada visualização renderizada pode ser copiada no formato de imagem, clicando com o botão direito sobre ela.

Usuário clicando em uma visualização para que ela seja copiada no formato de imagem.

Várias prévias da mesma anotação @Preview

É possível mostrar várias versões do mesmo elemento combinável @Preview com especificações diferentes ou parâmetros diferentes transmitidos ao elemento. Dessa forma, é possível reduzir o código boilerplate que você precisaria escrever.

Modelos de várias visualizações

O androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01 e versões mais recentes apresentam modelos da API Multipreview (@PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark e @PreviewDynamicColors) para que, com uma única anotação, seja possível visualizar a interface do Compose em cenários comuns.

Visualizar diferentes fontes e tamanhos de tela usando modelos

Criar anotações de várias visualizações personalizadas

Com várias visualizações, é possível definir uma classe de anotação em que há diversas anotações @Preview com configurações diferentes. O uso dessa anotação em uma função combinável renderiza automaticamente todas as diferentes visualizações de uma vez. Por exemplo, é possível usar essa anotação para visualizar vários dispositivos, tamanhos de fonte ou temas ao mesmo tempo, sem precisar repetir essas definições para cada elemento combinável.

Comece criando sua própria classe de anotação personalizada:

@Preview(
    name = "small font",
    group = "font scales",
    fontScale = 0.5f
)
@Preview(
    name = "large font",
    group = "font scales",
    fontScale = 1.5f
)
annotation class FontScalePreviews

Você pode usar essa anotação personalizada para elementos combináveis de visualização:

@FontScalePreviews
@Composable
fun HelloWorldPreview() {
    Text("Hello World")
}

Guia de design do Android Studio mostrando o elemento combinável com fonte pequena e grande

É possível combinar diversas anotações de várias visualizações e anotações normais para criar um conjunto mais completo de visualizações. Isso não significa que todas as combinações diferentes serão mostradas. Na verdade, cada anotação de várias visualizações funciona de maneira independente e renderiza apenas as próprias variantes.

@Preview(
    name = "Spanish",
    group = "locale",
    locale = "es"
)
@FontScalePreviews
annotation class CombinedPreviews

@CombinedPreviews
@Composable
fun HelloWorldPreview2() {
    MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } }
}

Guia de design do Android Studio mostrando o elemento combinável em todas as configurações

A natureza de combinação da multiprévia e da prévia normal permite que você teste de forma mais abrangente muitas propriedades de projetos em maior escala.

@Preview e grandes conjuntos de dados

Muitas vezes, é necessário transmitir um grande conjunto de dados para a visualização combinável. Para fazer isso, basta transmitir dados de amostra para uma função de visualização combinável adicionando um parâmetro com a anotação @PreviewParameter.

@Preview
@Composable
fun UserProfilePreview(
    @PreviewParameter(UserPreviewParameterProvider::class) user: User
) {
    UserProfile(user)
}

Para fornecer os dados de amostra, crie uma classe que implemente a PreviewParameterProvider e retorne esses dados como uma sequência.

class UserPreviewParameterProvider : PreviewParameterProvider<User> {
    override val values = sequenceOf(
        User("Elise"),
        User("Frank"),
        User("Julia")
    )
}

Isso renderiza uma visualização por elemento de dados na sequência:

Prévias mostrando as funções de composição Elise, Frank e Julia

Você pode usar a mesma classe de provedor para várias visualizações. Se necessário, limite o número de visualizações definindo o parâmetro "limit".

@Preview
@Composable
fun UserProfilePreview2(
    @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
    UserProfile(user)
}

As visualizações que usam @PreviewParameter são nomeadas por padrão usando o índice de parâmetro e o nome da propriedade (usuário 0, usuário 1, usuário 2 etc.), o que pode dificultar a diferenciação entre elas. Para melhorar a clareza da visualização, você pode fornecer nomes de exibição personalizados para cada visualização, substituindo getDisplayName() no PreviewParameterProvider. Isso ajuda a distinguir entre diferentes variações de dados ou estados da interface. Por exemplo, é possível rotular as visualizações com base nos dados de entrada:

class UserAgePreviewParameterProvider : PreviewParameterProvider<User> {
    // Using a List internally for efficient index-based access
    private val userList = listOf(
        User(name = "Elise", age = 30),
        User(name = "Frank", age = 31),
        User(name = "Julia", age = 40)
    )

    override val values = userList.asSequence()

    override fun getDisplayName(index: Int): String? {
        // Return null or an empty string to use the default index-based name
        val user = userList.getOrNull(index) ?: return null
        return "${user.name} - ${user.age}"
    }
}

Prévias com nomes de exibição personalizados mostrando as funções de composição Elise - 30, Frank - 31 e Julia - 40

Geração de prévias assistida por IA

O agente de IA no Android Studio pode gerar automaticamente prévias do Compose para seus elementos combináveis. Clique com o botão direito do mouse em uma função combinável e selecione IA > Gerar prévia para [nome da função combinável]. O agente analisa seu elemento combinável para gerar o código boilerplate @Preview necessário com os parâmetros corretos, ajudando você a verificar rapidamente se a interface é renderizada conforme o esperado.

Gerar uma visualização do Compose usando IA.

Classe de anotação @Preview

Você pode usar o atalho "Ctrl ou ⌘ + clique" na anotação @Preview no Android Studio para ver uma lista completa de parâmetros que podem ser ajustados ao personalizar a visualização.

annotation class Preview(
    val name: String = "",
    val group: String = "",
    @IntRange(from = 1) val apiLevel: Int = -1,
    val widthDp: Int = -1,
    val heightDp: Int = -1,
    val locale: String = "",
    @FloatRange(from = 0.01) val fontScale: Float = 1f,
    val showSystemUi: Boolean = false,
    val showBackground: Boolean = false,
    val backgroundColor: Long = 0,
    @UiMode val uiMode: Int = 0,
    @Device val device: String = Devices.DEFAULT,
    @Wallpaper val wallpaper: Int = Wallpapers.NONE,
)

Limitações e práticas recomendadas

O Android Studio executa o código de pré-lançamentos diretamente na área de pré-lançamento. Ele não requer a execução de um emulador ou dispositivo físico porque usa uma parte portada do framework do Android chamada Layoutlib. O Layoutlib é uma versão personalizada do framework do Android projetada para ser executada fora de dispositivos Android. O objetivo da biblioteca é fornecer uma visualização de um layout no Android Studio que seja muito próxima da renderização em dispositivos.

Limitações das prévias

Devido à forma como as prévias são renderizadas no Android Studio, elas são leves e não exigem todo o framework do Android para serem renderizadas. No entanto, isso tem as seguintes limitações:

  • Não há acesso à rede
  • Não há acesso ao arquivo
  • Algumas APIs de Context podem não estar totalmente disponíveis

Pré-lançamentos e ViewModels

As prévias são limitadas ao usar ViewModel em um elemento combinável. O sistema de prévias não é capaz de construir todos os parâmetros transmitidos para um ViewModel, como repositórios, casos de uso, gerenciadores ou semelhantes. Além disso, se o ViewModel participar da injeção de dependência (como com o Hilt), o sistema de visualizações não poderá criar todo o gráfico de dependência para construir o ViewModel.

Quando você tenta visualizar um elemento combinável com ViewModel, o Android Studio mostra um erro ao renderizar o elemento em questão:

Painel de problemas do Android Studio com a mensagem &quot;Falha ao instanciar um ViewModel&quot;

Se você quiser visualizar um elemento combinável que usa um ViewModel, crie outro elemento combinável com os parâmetros de ViewModel transmitidos como argumentos dele. Dessa forma, não é necessário visualizar o elemento combinável que usa o ViewModel.

@Composable
fun AuthorScreen(viewModel: AuthorViewModel = viewModel()) {
  AuthorScreen(
    name = viewModel.authorName,
    // ViewModel sends the network requests and makes posts available as a state
    posts = viewModel.posts
  )
}

@Composable
fun AuthorScreen(
  name: NameLabel,
  posts: PostsList
) {
  // ...
}

@Preview
@Composable
fun AuthorScreenPreview(
  // You can use some sample data to preview your composable without the need to construct the ViewModel
  name: String = sampleAuthor.name,
  posts: List<Post> = samplePosts[sampleAuthor]
) {
  AuthorScreen(
      name = NameLabel(name),
      posts = PostsList(posts)
  )
}

Outros recursos

Avançar
Visualizar e depurar animações