Um elemento combinável é definido por uma função e anotado com @Composable
:
@Composable fun SimpleComposable() { Text("Hello World") }
Para ativar uma visualização desse elemento, crie outro elemento com anotações.
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.
É 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 elementos combináveis @Preview
é evitar a dependência
no emulador do Android Studio. É possível salvar a inicialização de memória pesada do
emulador para mais mudanças 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
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
. Esses
valores já são interpretados como dp
. 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 observar como a interface reage às
escolhas de planos de fundo de diferentes usuários. Selecione entre os diferentes temas de plano de fundo
oferecidos pela
classe
Wallpaper
. Esse recurso requer o Compose 1.4.0 ou uma versão mais recente.
Usar com diferentes dispositivos
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.
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.
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.
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
(⌥ + ⏎ no 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)) }
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") }
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") }
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.
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, o valor de LocalInspectionMode.current
será 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.
Assim, 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 as visualizações definidas. Essa interação ajuda a entender o comportamento de execução das suas prévias e permite navegar melhor na interface com elas.
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 forma 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.
Abrir 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
, então ela
compartilha o mesmo contexto e permissões. Ele não exige que você escreva
um código modelo solicitando uma permissão se ela já tiver sido concedida.
Clique no ícone Run Preview
ao lado da anotação @Preview
ou na parte de cima da visualização. O Android
Studio 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
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. Dessa
forma, você pode reduzir o código boilerplate que precisaria escrever.
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.
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") }
É possível combinar várias 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)) } } }
A natureza de mistura e combinação da visualização múltipla e da visualização normal permite testar de forma mais abrangente muitas propriedades de projetos de 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
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 exemplo, crie uma classe que implemente
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
portada do framework do Android chamada Layoutlib
. Layoutlib
é um personalizado
versão 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 visualizações
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 renderização. 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évias 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 similares. Além disso, se a ViewModel
participar da injeção de dependência (como
com o Hilt), o sistema de visualização não poderá criar o gráfico de dependência
inteiro para criar a ViewModel
.
Quando você tenta visualizar um elemento combinável com ViewModel
, o Android Studio mostra um
erro ao renderizar o elemento combinável específico:
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 saber mais sobre como o Android Studio promove a facilidade de uso do @Preview
e aprender
mais dicas de ferramentas, confira o blog Ferramentas
do Compose.
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