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 elemento de texto simples contendo as palavras "Hello
Mundo"

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

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

A anotação @Preview informa ao Android Studio que esse combinável precisa ser mostrado na visualização de design desse arquivo. Você pode ver ao vivo atualizações na visualização da função combinável enquanto você faz edições.

Um GIF mostrando atualizações em tempo real usando o Compose
Visualizar

É possível adicionar parâmetros manualmente no código para personalizar a forma como o Android Studio renderiza @Preview. É possível até adicionar a anotação @Preview aos mesmos 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 no emulador do Android Studio. Você pode salvar a inicialização com uso intenso de memória do emulador para mais mudanças finais na aparência e na capacidade do @Preview de fazer e testar pequenas mudanças de código com facilidade.

Para aproveitar a anotação @Preview de forma mais eficaz, defina o telas em termos do estado que recebe como entrada e os eventos que ele recebe de entrada e saída.

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. Aqueles valores já são interpretados como dp, então você não precisa adicionar .dp a eles:

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

Um quadrado amarelo com as palavras "Hello"
Mundo"

Prévias de cores dinâmicas

Se você ativou os recursos dinâmicos cor no seu app, use o atributo wallpaper para trocar de plano de fundo e conferir como a interface reage de diferentes usuários plano de fundo escolhido. Selecione um dos diferentes temas de plano de fundo oferecido pela Wallpaper . Esse recurso requer o Compose 1.4.0 ou uma versão mais recente.

Use com diferentes dispositivos

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

Exemplo de elemento combinável
função

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

Como editar o exemplo
função

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

Especificações
lista

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) > Substituir por .... O A inspeção tenta fornecer uma correção mais próxima da aparência da entrada.

Exemplo de anúncios inválidos
valor

Localidade

Para testar diferentes localidades do usuário, adicione o parâmetro locale:

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

Elemento de texto simples contendo a palavra "Bonjour" com um francês
sinalizar

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. Manter em backgroundColor é um Long ARGB, não um Color. :

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

Um retângulo verde com as palavras "Hello"
Mundo"

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")
}

Uma janela de visualização mostrando uma atividade com as barras de status e ação.

Modo de interface

O parâmetro uiMode pode usar qualquer um dos Configuration.UI_* constantes e permite que você altere o comportamento da visualização de acordo. 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 a partir do LocalInspectionMode CompositionLocal para ver se o elemento combinável foi renderizado em uma visualização (dentro de uma componente inspecionável). Se a composição for renderizada em uma visualização, LocalInspectionMode.current será avaliado como true. Isso informações permitem personalizar a visualização. por exemplo, é possível mostrar imagem de marcador de posição na janela de visualização em vez de mostrar dados reais.

Dessa forma, você também pode contornar as limitações. Para exemplo, mostrando 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!")
    }
}

Interaja com o @Preview

O Android Studio oferece recursos que permitem interagir com o visualizações prévias. Essa interação ajuda você a entender o desempenho comportamento do tempo de execução e permite que você navegue melhor pela IU com visualizações.

Modo interativo

O modo interativo permite que você interaja com uma visualização de forma semelhante a como em um dispositivo que executa o programa, como um smartphone ou tablet. Modo interativo são isolados em um ambiente sandbox (ou seja, isolado de outras visualizações), em que é possível clicar nos elementos e inserir 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.

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

Um vídeo do usuário interagindo com um
visualizar

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.

Quando o usuário passa o mouse sobre uma visualização, fazendo com que o Studio exiba os contornos
dela
elementos combináveis

Executar visualização

Você pode executar um @Preview específico em um emulador ou dispositivo físico. O A prévia é implantada no mesmo app do projeto que uma nova Activity. Por isso, ela compartilham o mesmo contexto e permissões. Ele não requer que você escreva código boilerplate solicitando uma permissão, caso ela já tenha sido concedida.

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

Usuário clicando em "Executar visualização"
botão

Vídeo do usuário implantando uma visualização em
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 copiá-la como uma
imagem.

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 passados para o elemento combinável. Isso é possível reduzir o código boilerplate que você precisaria escrever 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 introduzem o recurso Multipreview Modelos de API: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark, e @PreviewDynamicColors, de modo que, com uma única anotação, você possa visualizar a interface do Compose em cenários comuns.

Visualizar diferentes fontes e tamanhos de tela usando modelos

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. Adicionando esta anotação a uma função combinável renderiza automaticamente todas as diferentes visualizações em 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 recursos pequenos e grandes
fonte

É possível combinar várias anotações de várias visualizações e anotações de visualização normais. 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 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 todos os elementos
configurações

A natureza de combinação e combinação das visualizações múltiplas e normais permite que você tenha testar de forma abrangente muitas propriedades de projetos maiores.

@Preview e grandes conjuntos de dados

Muitas vezes, surge uma necessidade em que você precisa transmitir um grande conjunto de dados para um elemento combinável prévia. Para fazer isso, basta transmitir dados de amostra para uma função de visualização combinável adicionar um parâmetro com o @PreviewParameter; uma anotação.

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

Para fornecer os dados de amostra, crie uma classe que implemente PreviewParameterProvider e retorna o dados de amostra 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 Elise, Frank e Julia
elementos combináveis

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)
}

Limitações e práticas recomendadas

O Android Studio executa o código de visualizações diretamente na área de visualização. Ela não exigem a execução de um emulador ou dispositivo físico, porque ele utiliza um parte do framework do Android chamado Layoutlib. Layoutlib é um personalizado versão do framework do Android projetada para ser executada fora de dispositivos Android. O o objetivo da biblioteca é fornecer uma prévia de um layout no Android Studio que está muito próximo à renderização nos 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 a renderização de todo o framework do Android. 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 o ViewModel em um 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 similares. Além disso, se o ViewModel participar da injeção de dependência (como como no Hilt), o sistema de visualizações não pode criar toda a dependência gráfico para criar o ViewModel.

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

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

Caso você queira visualizar um elemento combinável que usa um ViewModel, crie outro elemento combinável com os parâmetros de ViewModel transmitidos como argumentos de o elemento combinável. Dessa forma, não é necessário visualizar o elemento combinável que usa o 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 pressionar Ctrl ou ⌘ + clicar a qualquer momento a anotação @Preview no Android; Studio, para uma lista completa de parâmetros que podem ser ajustados ao personalizar seu prévia.

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,
)

Outros recursos

Para ler mais sobre como o Android Studio promove a facilidade de uso do @Preview, e conheça mais dicas de ferramentas, confira o blog Escrever Ferramentas.