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")
}
AndroidStudioComposeSnippets.kt

Para ativar uma visualização desse elemento combinável, crie outro elemento combinável, com a anotação @Composable e @Preview. Esse novo elemento combinável com a anotação agora contém o elemento que você criou inicialmente, SimpleComposable:

@Preview
@Composable
fun SimpleComposablePreview() {
    SimpleComposable()
}
AndroidStudioComposeSnippets.kt

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 conferir atualizações em tempo real da visualização do elemento combinável enquanto faz as edições.

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

Observação: se você tem várias visualizações de composição, mas quer se concentrar em uma visualização por vez, recomendamos o uso do modo de galeria para economizar recursos de renderização. Mude para os modos de grade ou de lista quando precisar conferir todas as variantes da interface de uma só vez. É possível alternar entre os modos usando o menu na parte de cima da guia Design.

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 com muita memória para fazer mudanças mais finais na aparência e a capacidade de @Preview de fazer e testar pequenas mudanças no código com facilidade.

Para aproveitar a anotação @Preview de forma mais eficaz, defina suas telas em termos do estado que ela recebe como entrada e os 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")
    }
}
AndroidStudioComposeSnippets.kt

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 ao plano de fundo escolhido por diferentes usuários. Selecione um dos diferentes temas de plano de fundo oferecidos pela classe Wallpaper. Esse recurso exige o Compose 1.4.0 ou mais recente.

Usar com diferentes dispositivos

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

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

No preenchimento automático, é possível 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.

Para usar, 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 mais próxima à da sua entrada.

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))
}
AndroidStudioComposeSnippets.kt

Definir cor do plano de fundo

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

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

interface 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")
}
AndroidStudioComposeSnippets.kt

Modo de interface

O parâmetro uiMode pode assumir 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.

LocalInspectionMode

Você pode ler o LocalInspectionMode CompositionLocal para conferir se o elemento combinável é renderizado em uma visualização (dentro de um componente inspecionável). Se a composição for renderizada em uma visualização, LocalInspectionMode.current será avaliado como true. Essas informações permitem personalizar a visualização. Por exemplo, você pode mostrar uma imagem de marcador de posição na janela de visualização em vez de 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!")
    }
}
AndroidStudioComposeSnippets.kt

Interagir com @Preview

O Android Studio oferece recursos que permitem interagir com as visualizações definidas. Essa interação ajuda a entender o comportamento do tempo de execução das visualizações e permite navegar melhor pela interface com visualizações.

Modo interativo

O modo interativo permite que você interaja com uma visualização da mesma forma que faria em um dispositivo que executa o programa, como um smartphone ou tablet. Esse modo é isolado em um ambiente sandbox (ou seja, isolado de outras visualizações). Nele, você clica em elementos e insere a entrada do usuário na visualização. É uma maneira rápida de testar diferentes estados, gestos e até animações do elemento combinável.

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.

Prévia da execução

Você pode executar um @Preview específico em um emulador ou dispositivo físico. A visualização é implantada no mesmo app do projeto como uma nova Activity. Portanto, ela compartilha o mesmo contexto e as mesmas permissões. Não é necessário escrever um código boilerplate que solicita uma permissão se ela já tiver sido concedida.

Observação: os argumentos aplicados à anotação @Preview (por exemplo, widthDp, locale etc.) não são aplicados à visualização executada e implantada.

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

Copiar renderização de @Preview

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

Várias visualizações da mesma anotação @Preview

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

Modelos de várias visualizações

O androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01 e versões mais recentes apresentam modelos de API de várias visualizações: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark e @PreviewDynamicColors. Assim, com uma única anotação, é possível visualizar a interface do Compose em cenários comuns.

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

Com várias visualizações, é possível definir uma classe de anotação em que há diversas anotações @Preview com configurações diferentes. A adição dessa anotação a uma função combinável renderiza automaticamente todas as diferentes visualizações de uma só 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
AndroidStudioComposeSnippets.kt

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

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

É possível combinar várias anotações de várias visualizações e anotações de visualização normal para criar um conjunto mais completo de visualizações. Combinar anotações de várias visualizações não significa que todas as combinações diferentes vão aparecer. 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)) } }
}
AndroidStudioComposeSnippets.kt

A natureza mesclada da visualização normal e de várias visualizações permite testar de forma mais abrangente muitas propriedades de projetos maiores.

@Preview e grandes conjuntos de dados

Muitas vezes, surge uma necessidade em que você precisa transmitir um conjunto de dados grande para a visualização de um elemento 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)
}
AndroidStudioComposeSnippets.kt

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

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

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

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)
}
AndroidStudioComposeSnippets.kt

Limitações e práticas recomendadas

O Android Studio executa o código de visualizações diretamente na área de visualização. Ele não exige 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 a visualização de um layout no Android Studio que esteja muito próximo da renderização em dispositivos.

Limitações das visualizações

Devido à maneira como as visualizações são renderizadas no Android Studio, elas são leves e não exigem todo o framework do Android para renderizá-las. 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

Visualizações e ViewModels

As visualizações são limitadas ao usar ViewModel em um elemento combinável. O sistema de visualizações 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 vai poder criar o gráfico de dependências inteiro para criar o ViewModel.

Quando você tenta visualizar um elemento combinável com ViewModel, o Android Studio mostra um erro ao renderizar o elemento específico:

Aviso: não transmita as instâncias ViewModel para outras funções combináveis. Ao fazer isso, você une os elementos combináveis ao tipo ViewModel, o que os torna menos reutilizáveis, mais difíceis de testar e não conseguem visualizar.

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. Dessa forma, não é necessário visualizar o elemento combinável que usa a ViewModel.

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

@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]
) {
  AuthorColumn(...) {
    name = NameLabel(name),
    posts = PostsList(posts)
  }
}

Classe de anotação @Preview

Você pode sempre pressionar Ctrl ou ⌘ + clicar na anotação @Preview no Android Studio para acessar 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,
)
AndroidStudioComposeSnippets.kt

Outros recursos

Para saber mais sobre como o Android Studio promove a facilidade de uso do @Preview e conferir mais dicas sobre ferramentas, confira o blog Compose Tooling.