Un componibile viene definito da una funzione e annotato con @Composable:
@Composable
fun SimpleComposable() {
Text("Hello World")
}
Per attivare un'anteprima di questo componibile, crea un altro componibile, annotato con @Composable e @Preview. Questo nuovo componibile annotato ora contiene
il componibile che hai creato inizialmente, SimpleComposable:
@Preview
@Composable
fun SimpleComposablePreview() {
SimpleComposable()
}
L'annotazione @Preview indica ad Android Studio che il componibile deve essere mostrato nella visualizzazione struttura di questo file. Puoi vedere gli aggiornamenti in tempo reale
dell'anteprima componibile man mano che apporti le modifiche.
Puoi aggiungere parametri manualmente nel codice per personalizzare il modo in cui Android Studio visualizza @Preview. Puoi persino aggiungere più volte l'annotazione @Preview alla stessa funzione per visualizzare l'anteprima di un componibile con proprietà diverse.
Uno dei principali vantaggi dell'utilizzo di elementi componibili @Preview è non fare affidamento sull'emulatore in Android Studio. Puoi salvare l'avvio dell'emulatore ad alta memoria per apportare ulteriori modifiche all'aspetto e al design, nonché la capacità di @Preview di apportare e testare facilmente piccole modifiche al codice.
Per utilizzare l'annotazione @Preview in modo più efficace, assicurati di definire le tue schermate in termini di stato che riceve come input e degli eventi che restituisce.
Definisci il tuo @Preview
Android Studio offre alcune funzionalità per estendere le anteprime componibili. Puoi modificare il design del container, interagire o implementarli direttamente su un emulatore o un dispositivo.
Dimensioni
Per impostazione predefinita, le dimensioni @Preview vengono scelte automaticamente per aggregare i contenuti.
Per impostare le dimensioni manualmente, aggiungi i parametri heightDp e widthDp. Questi valori sono già interpretati come dp, quindi non è necessario aggiungerli .dp:
@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
Box(Modifier.background(Color.Yellow)) {
Text("Hello World")
}
}
Anteprima colore dinamica
Se hai attivato il colore dinamico nella tua app, utilizza l'attributo wallpaper per cambiare sfondo e vedere come la tua UI reagisce ai diversi sfondi scelti dagli utenti. Scegli tra i diversi temi di sfondo
offerti dalla
classe Wallpaper. Questa funzionalità richiede Compose 1.4.0 o versioni successive.
Utilizzo con dispositivi diversi
In Android Studio Flamingo, puoi modificare il parametro device dell'annotazione Anteprima per definire le configurazioni dei componibili in diversi dispositivi.
Se il parametro del dispositivo ha una stringa vuota (@Preview(device = "")), puoi
chiamare il completamento automatico premendo Ctrl + Space. Poi, puoi impostare i valori
di ciascun parametro.
Dal completamento automatico, puoi selezionare qualsiasi opzione del dispositivo dall'elenco, ad esempio
@Preview(device = "id:pixel_4"). In alternativa, puoi inserire un dispositivo personalizzato
scegliendo spec:width=px,height=px,dpi=int… per impostare i singoli valori di
ogni parametro.
Per applicare, premi Enter o annulla con Esc.
Se imposti un valore non valido, la dichiarazione è sottolineata in rosso e potrebbe essere disponibile una correzione (Alt + Enter (⌥ + ⏎ per macOS) > Sostituisci con ...). L'ispezione tenta di fornire la correzione più simile al tuo input.
Impostazioni internazionali
Per testare diverse impostazioni internazionali dell'utente, aggiungi il parametro locale:
@Preview(locale = "fr-rFR")
@Composable
fun DifferentLocaleComposablePreview() {
Text(text = stringResource(R.string.greeting))
}
Imposta colore sfondo
Per impostazione predefinita, il tuo componibile viene visualizzato con uno sfondo trasparente. Per aggiungere uno
sfondo, aggiungi i parametri showBackground e backgroundColor. Tieni presente che backgroundColor è un valore Long ARGB, non un valore Color:
@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
Text("Hello World")
}
UI di sistema
Se devi visualizzare le barre di stato e delle azioni all'interno di un'anteprima, aggiungi il parametro showSystemUi:
@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
Text("Hello World")
}
Modalità UI
Il parametro uiMode può utilizzare una qualsiasi delle costanti Configuration.UI_*
e ti consente di modificare il comportamento dell'anteprima di conseguenza. Ad
esempio, puoi impostare l'anteprima sulla modalità notturna per vedere come reagisce il tema.
LocalInspectionMode
Puoi leggere da LocalInspectionMode
CompositionLocal per vedere se il componibile viene visualizzato in un'anteprima (all'interno di un
componente ispezionebile). Se la composizione viene visualizzata
in anteprima, LocalInspectionMode.current restituisce true. Queste informazioni ti consentono di personalizzare l'anteprima; ad esempio, puoi mostrare un'immagine segnaposto nella finestra di anteprima anziché mostrare dati reali.
In questo modo, puoi anche aggirare le limitazioni. Ad esempio, puoi mostrare dati di esempio anziché chiamare una richiesta di rete.
@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!")
}
}
Interagisci con il tuo @Preview
Android Studio offre funzionalità che ti consentono di interagire con le anteprime definite. Questa interazione ti aiuta a comprendere il comportamento di runtime delle anteprime e ti consente di esplorare meglio la tua UI con le anteprime.
Modalità interattiva
La modalità interattiva ti consente di interagire con un'anteprima in modo simile a come faresti su un dispositivo su cui è in esecuzione il tuo programma, ad esempio uno smartphone o un tablet. La modalità interattiva è isolata in un ambiente sandbox (ovvero isolato da altre anteprime), in cui puoi fare clic sugli elementi e inserire l'input utente nell'anteprima. È un modo rapido per testare diversi stati, gesti e persino animazioni del componibile.
Navigazione del codice e contorni componibili
Puoi passare il mouse sopra un'anteprima per visualizzare i contorni dei componibili contenuti al suo interno. Se fai clic su un contorno componibile, la visualizzazione dell'editor passa alla sua definizione.
Esegui anteprima
Puoi eseguire un @Preview specifico su un emulatore o un dispositivo fisico. Il deployment dell'anteprima viene eseguito all'interno della stessa app di progetto di un nuovo Activity, quindi condivide lo stesso contesto e le stesse autorizzazioni. Non richiede la scrittura di codice boilerplate per richiedere l'autorizzazione, se è già stata concessa.
Fai clic sull'icona Esegui anteprima 
accanto all'annotazione @Preview o nella parte superiore dell'anteprima e Android Studio distribuirà @Preview nell'emulatore o nel dispositivo collegato.
Copia rendering di @Preview
Ogni anteprima visualizzata può essere copiata come immagine facendo clic con il tasto destro del mouse sull'anteprima.
Più anteprime della stessa annotazione @Preview
Puoi mostrare più versioni dello stesso componibile @Preview con specifiche diverse o parametri differenti passati all'elemento componibile. In questo modo, puoi ridurre il codice boilerplate che altrimenti dovresti scrivere.
Modelli di anteprima multipla
androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ introduce i modelli API di Multipreview: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark e @PreviewDynamicColors, in modo che con una singola annotazione sia possibile visualizzare l'anteprima della UI di Compose in scenari comuni.
Crea annotazioni personalizzate in anteprima multipla
Con l'anteprima multipla, puoi definire una classe di annotazione che a sua volta dispone di più annotazioni @Preview con configurazioni diverse. L'aggiunta di questa annotazione a una funzione componibile esegue automaticamente il rendering di tutte le diverse anteprime contemporaneamente. Ad esempio, puoi utilizzare questa annotazione per visualizzare l'anteprima di più dispositivi, dimensioni di carattere o temi contemporaneamente senza ripetere le definizioni per ogni singolo componibile.
Per iniziare, crea la tua classe di annotazione personalizzata:
@Preview(
name = "small font",
group = "font scales",
fontScale = 0.5f
)
@Preview(
name = "large font",
group = "font scales",
fontScale = 1.5f
)
annotation class FontScalePreviews
Puoi utilizzare questa annotazione personalizzata per i tuoi elementi componibili in anteprima:
@FontScalePreviews
@Composable
fun HelloWorldPreview() {
Text("Hello World")
}
Puoi combinare più annotazioni di anteprima multipla e normali annotazioni di anteprima per creare un set di anteprime più completo. La combinazione di annotazioni multi-anteprima non significa che vengono mostrate tutte le diverse combinazioni. Ogni annotazione multi-anteprima agisce in modo indipendente e esegue il rendering solo delle sue varianti.
@Preview(
name = "Spanish",
group = "locale",
locale = "es"
)
@FontScalePreviews
annotation class CombinedPreviews
@CombinedPreviews
@Composable
fun HelloWorldPreview2() {
MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } }
}
La natura combinazione dell'anteprima multipla (e della normale anteprima) ti consente di testare in modo più completo molte proprietà di progetti su scala più ampia.
@Preview e set di dati di grandi dimensioni
Molto spesso, si presenta la necessità di passare un set di dati di grandi dimensioni all'anteprima componibile. Per farlo, devi semplicemente passare dati di esempio a una funzione Anteprima componibile
aggiungendo un parametro con l'annotazione
@PreviewParameter.
@Preview
@Composable
fun UserProfilePreview(
@PreviewParameter(UserPreviewParameterProvider::class) user: User
) {
UserProfile(user)
}
Per fornire i dati di esempio, crea una classe che implementi PreviewParameterProvider e restituisca i dati di esempio come sequenza.
class UserPreviewParameterProvider : PreviewParameterProvider<User> {
override val values = sequenceOf(
User("Elise"),
User("Frank"),
User("Julia")
)
}
Viene visualizzata un'anteprima per ogni elemento di dati della sequenza:
Puoi utilizzare la stessa classe provider per più anteprime. Se necessario, limita il numero di anteprime impostando il parametro per il limite.
@Preview
@Composable
fun UserProfilePreview2(
@PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
UserProfile(user)
}
Limitazioni e best practice
Android Studio esegue l'anteprima del codice direttamente nell'area di anteprima. Non è necessario eseguire un emulatore o un dispositivo fisico perché sfrutta una parte portata del framework Android chiamata Layoutlib. Layoutlib è una versione personalizzata del framework Android progettata per l'esecuzione al di fuori dei dispositivi Android. L'obiettivo della libreria è fornire un'anteprima di un layout in Android Studio molto prossimo al rendering sui dispositivi.
Limitazioni delle anteprime
A causa del modo in cui le anteprime vengono visualizzate in Android Studio, sono leggere e non richiedono l'intero framework Android per visualizzarle. Tuttavia, ciò presenta le seguenti limitazioni:
- Nessun accesso di rete
- Nessun accesso ai file
- Alcune API
Contextpotrebbero non essere completamente disponibili
Anteprime e ViewModels
Le anteprime sono limitate quando utilizzi ViewModel all'interno di un
componibile. Il sistema di anteprime non è in grado di creare tutti i parametri passati a un ViewModel, ad esempio repository, casi d'uso, gestori o simili. Inoltre, se ViewModel partecipa all'inserimento delle dipendenze (ad esempio, Hilt), il sistema di anteprima non può creare l'intero grafico delle dipendenze per creare l'elemento ViewModel.
Quando provi a visualizzare l'anteprima di un componibile con ViewModel, Android Studio mostra un
errore durante il rendering dell'elemento componibile specifico:
Se vuoi visualizzare l'anteprima di un componibile che utilizza ViewModel, devi creare un altro componibile con i parametri di ViewModel passati come argomenti dell'elemento componibile. In questo modo, non è necessario visualizzare l'anteprima del componibile che utilizza 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 di annotazione @Preview
Puoi sempre premere Ctrl o ⌘ + clic sull 'annotazione @Preview in Android Studio per visualizzare un elenco completo dei parametri che possono essere regolati durante la personalizzazione dell'anteprima.
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,
)
Risorse aggiuntive
Per scoprire di più su come Android Studio promuove la facilità d'uso di @Preview e per scoprire di più sui suggerimenti per gli strumenti, consulta il blog Compose Tooling.
Consigliato per te
- Nota: il testo del link viene visualizzato quando JavaScript è disattivato
- Dati con ambito locale con ComposeLocal
- Material Design 2 in Compose
- Utilizzare le visualizzazioni in Compose