Um elemento combinável é definido por uma função e anotado com @Composable:
@Composable
fun SimpleComposable() {
Text("Hello World")
}
Para permitir uma visualização desse elemento, crie outro, com a anotação @Composable e @Preview. Esse novo elemento combinável com anotação agora contém
o elemento que você criou 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. É possível conferir as atualizações
em tempo real da visualização da função combinável enquanto você faz 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.
Um dos principais benefícios de usar os elementos combináveis @Preview é evitar a dependência
do emulador no Android Studio. Você pode salvar a inicialização com uso intenso de memória do
emulador para ter mais mudanças finais na aparência e para a 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 as
telas em relação ao estado que ela recebe como entrada e os eventos que ela
envia.
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. Portanto, não é necessário adicionar .dp
a eles:
@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
Box(Modifier.background(Color.Yellow)) {
Text("Hello World")
}
}
Prévias de cores dinâmicas
Se você ativou as cores
dinâmicas no app,
use o atributo wallpaper para alternar planos de fundo e conferir como a interface reage ao
plano de fundo escolhido pelos usuários. Selecione um dos diferentes temas de plano de fundo
oferecidos pela
classe
Wallpaper. Esse recurso requer o Compose 1.4.0 ou uma versão mais recente.
Use com diferentes dispositivos
No Android Studio Flamingo, você pode editar o parâmetro device da anotação de visualização
para definir configurações dos elementos combináveis em diferentes dispositivos.
Quando o parâmetro do dispositivo tem uma string vazia (@Preview(device = "")), você pode
invocar o preenchimento automático pressionando Ctrl + Space. Depois, você pode definir os valores
de cada parâmetro.
No preenchimento automático, você pode selecionar qualquer opção de dispositivo na lista, por exemplo,
@Preview(device = "id:pixel_4"). Como alternativa, você pode inserir um dispositivo personalizado escolhendo spec:width=px,height=px,dpi=int… para definir os valores individuais de cada parâmetro.
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 mais próxima da sua entrada.
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))
}
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")
}
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")
}
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
É possível ler no CompositionLocal de LocalInspectionMode
para ver se o elemento combinável foi renderizado em uma visualização (dentro de um
componente inspecionável). Se a composição for renderizada
em uma visualização, LocalInspectionMode.current será avaliada como true. Essas
informações permitem personalizar a visualização. Por exemplo, é possível mostrar uma
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. 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!")
}
}
Interaja com o @Preview
O Android Studio oferece recursos que permitem interagir com as visualizações definidas. Essa interação ajuda a entender o comportamento do ambiente de execução das visualizações e permite navegar melhor pela interface com elas.
Modo interativo
O modo interativo permite interagir com uma visualização da mesma forma que você faria em um dispositivo que executa seu programa, como um smartphone ou tablet. O modo interativo é isolado em um ambiente de sandbox (ou seja, isolado de outras visualizações), em que você pode clicar em 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.
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.
Executar visualizaçã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 permissões. Não é necessário escrever
código boilerplate solicitando uma permissão, caso ela já tenha sido concedida.
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 essa @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
É possível mostrar várias versões do mesmo elemento combinável @Preview com
especificações diferentes ou parâmetros distintos transmitidos ao elemento combinável. Dessa
forma, é 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 modelos
de API Multipreview: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark
e @PreviewDynamicColors, para que, com uma única anotação, você possa
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. Adicionar essa anotação a
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")
}
É 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 diferentes combinações 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)) } }
}
A natureza de combinação e correspondência das várias visualizações e da visualização normal permite que você teste mais abrangentemente muitas propriedades de projetos em grande escala.
@Preview e grandes conjuntos de dados
Muitas vezes, surge uma necessidade em que um grande conjunto de dados é necessário para a visualização
de composição. 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 o
PreviewParameterProvider e retorne os
dados de exemplo 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:
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. Ele não
exige a execução de um emulador ou dispositivo físico, porque aproveita uma parte
transferida do framework do Android chamada Layoutlib. Layoutlib é uma versão
personalizada do framework do Android projetada para ser executada fora de dispositivos Android. O
objetivo da biblioteca é fornecer uma prévia de um layout no Android Studio que
esteja muito próximo da 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 todo o framework do Android para fazê-las. No entanto, isso tem as seguintes limitações:
- Não há acesso à rede
- Não há acesso ao arquivo
- Algumas APIs de
Contextpodem 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 passados para um ViewModel, como repositórios, casos de uso, gerenciadores
ou similares. Além disso, se a 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 específico:
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
do elemento. 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
Use "ctrl" ou "⌘ + clique" na anotação @Preview no Android
Studio para conferir 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,
)
Outros recursos
Para ler mais sobre como o Android Studio promove a facilidade de uso do @Preview e saber
mais dicas de ferramentas, confira o blog Compose
Tooling (link em inglês).
Recomendados para você
- Observação: o texto do link aparece quando o JavaScript está desativado.
- Dados com escopo local usando o CompositionLocal
- Material Design 2 no Compose
- Como usar visualizações no Compose