Visualizza l'anteprima dell'interfaccia utente con le anteprime componibili

Un componibile viene definito da una funzione e annotato con @Composable:

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

Per attivare un'anteprima di questo componibile, crea un altro componibile, annotato con @Composable e @Preview. Questo nuovo componibile annotato ora contiene il componibile creato inizialmente, SimpleComposable:

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

L'@Preview annotazione indica ad Android Studio che questo componibile deve essere mostrato nella visualizzazione Progetto di questo file. Puoi vedere gli aggiornamenti live dell'anteprima del componibile man mano che apporti le modifiche.

Puoi aggiungere parametri manualmente nel codice per personalizzare il modo in cui Android Studio esegue il rendering di @Preview. Puoi anche aggiungere l'annotazione @Preview alla stessa funzione più volte per visualizzare l'anteprima di un componibile con proprietà diverse.

Uno dei principali vantaggi dell'utilizzo dei componibili @Preview è evitare di dover utilizzare l'emulatore in Android Studio. Puoi salvare l'avvio dell'emulatore, che richiede molta memoria, per le modifiche finali dell'aspetto e utilizzare la funzionalità @Preview per apportare e testare facilmente piccole modifiche al codice.

Per sfruttare al meglio l'annotazione @Preview, assicurati di definire le schermate in termini di stato che ricevono come input e degli eventi che generano.

Definisci @Preview

Android Studio offre alcune funzionalità per estendere le anteprime dei componibili. Puoi modificare il design del contenitore, interagire con loro o eseguirne il deployment direttamente in un emulatore o su un dispositivo.

Dimensioni

Per impostazione predefinita, le dimensioni @Preview vengono scelte automaticamente per adattarsi ai contenuti. Per impostare le dimensioni manualmente, aggiungi i parametri heightDp e widthDp. Questi valori vengono già interpretati come dp, quindi non devi aggiungere .dp ad essi:

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

Anteprima dei colori dinamici

Se hai attivato i colori dinamici nella tua app, utilizza l'attributo wallpaper per cambiare gli sfondi e vedere come reagisce l'UI allo sfondo scelto da diversi utenti. Seleziona uno dei temi di sfondo offerti dalla Wallpaper classe. 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 Preview per definire le configurazioni dei componibili su dispositivi diversi.

Quando il parametro device ha una stringa vuota (@Preview(device = "")), puoi richiamare il completamento automatico premendo Ctrl + Space. Poi puoi impostare i valori di ogni 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 viene sottolineata in rosso e potrebbe essere disponibile una correzione (Alt + Enter (⌥ + ⏎ per macOS) > Sostituisci con…. L' ispezione tenta di fornire una correzione che si avvicini il più possibile all'input.

Impostazioni internazionali

Per testare impostazioni internazionali utente diverse, aggiungi il parametro locale:

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

Imposta colore di sfondo

Per impostazione predefinita, il componibile viene visualizzato con uno sfondo trasparente. Per aggiungere uno sfondo, aggiungi i parametri showBackground e backgroundColor. Tieni presente che backgroundColor è un valore ARGB Long, non un valore Color:

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

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

Modalità UI

Il parametro uiMode può accettare una qualsiasi delle Configuration.UI_* costanti e ti consente di modificare il comportamento dell'anteprima di conseguenza. Ad esempio, puoi impostare l'anteprima sulla modalità Buio per vedere come reagisce il tema.

LocalInspectionMode

Puoi leggere da LocalInspectionMode CompositionLocal per vedere se il componibile viene sottoposto a rendering in un'anteprima (all'interno di un componente ispezionabile). Se la composizione viene sottoposta a rendering in un'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 i dati reali.

In questo modo, puoi anche aggirare le limitazioni. Ad esempio, mostrando dati di esempio anziché chiamare la 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!")
    }
}
AndroidStudioComposeSnippets.kt

Interagisci con @Preview

Android Studio fornisce 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 navigare meglio nell'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 che esegue il programma, ad esempio uno smartphone o un tablet. La modalità interattiva è isolata in un ambiente sandbox (ovvero isolata da altre anteprime), in cui puoi fare clic sugli elementi e inserire l'input utente nell'anteprima. È un modo rapido per testare stati, gesti e persino animazioni diversi del componibile.

Navigazione nel codice e contorni dei componibili

Puoi passare il mouse sopra un'anteprima per visualizzare i contorni dei componibili contenuti al suo interno. Se fai clic sul contorno di un componibile, la visualizzazione dell'editor passa alla relativa definizione.

Esegui anteprima

Puoi eseguire un @Preview specifico su un emulatore o un dispositivo fisico. L'anteprima viene sottoposta a deployment all'interno della stessa app di progetto come una nuova Activity, quindi condivide lo stesso contesto e le stesse autorizzazioni. Non è necessario scrivere codice boilerplate per richiedere un'autorizzazione se è già stata concessa.

Fai clic sull'icona Esegui anteprima accanto all'annotazione @Preview o nella parte superiore dell'anteprima e Android Studio sottopone a deployment @Preview sul dispositivo connesso o sull'emulatore.

Copia il rendering @Preview

Ogni anteprima sottoposta a rendering può essere copiata come immagine facendo clic con il tasto destro del mouse.

Più anteprime della stessa annotazione @Preview

Puoi mostrare più versioni dello stesso componibile @Preview con specifiche diverse o parametri diversi passati al 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 dell'API Anteprima multipla: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark e @PreviewDynamicColors, in modo che con una singola annotazione tu possa visualizzare l'anteprima dell'UI Compose in scenari comuni.

Crea annotazioni di anteprima multipla personalizzate

Con l'anteprima multipla, puoi definire una classe di annotazione che a sua volta ha più annotazioni @Preview con configurazioni diverse. L'aggiunta di questa annotazione a una funzione componibile esegue automaticamente il rendering di tutte le anteprime diverse contemporaneamente. Ad esempio, puoi utilizzare questa annotazione per visualizzare l'anteprima di più dispositivi, dimensioni dei caratteri o temi contemporaneamente senza ripetere queste definizioni per ogni singolo componibile.

Inizia creando 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
AndroidStudioComposeSnippets.kt

Puoi utilizzare questa annotazione personalizzata per i componibili di anteprima:

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

Puoi combinare più annotazioni di anteprima multipla e annotazioni di anteprima normali per creare un insieme più completo di anteprime. La combinazione di annotazioni di anteprima multipla non significa che vengono mostrate tutte le combinazioni diverse. Ogni annotazione di anteprima multipla agisce in modo indipendente ed esegue il rendering solo delle proprie varianti.

@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

La natura di combinazione dell'anteprima multipla e dell'anteprima normale ti consente di testare in modo più completo molte proprietà dei progetti su larga scala.

@Preview e set di dati di grandi dimensioni

Molto spesso, è necessario passare un set di dati di grandi dimensioni all'anteprima del componibile. Per farlo, basta passare i dati di esempio a una funzione di anteprima del componibile by aggiungendo un parametro con la @PreviewParameter annotazione.

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

Per fornire i dati di esempio, crea una classe che implementa PreviewParameterProvider e restituisce i dati di esempio come sequenza.

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

Viene eseguito il rendering di un'anteprima per ogni elemento di dati nella sequenza:

Puoi utilizzare la stessa classe di provider per più anteprime. Se necessario, limita il numero di anteprime impostando il parametro limit.

@Preview
@Composable
fun UserProfilePreview2(
    @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
    UserProfile(user)
}
AndroidStudioComposeSnippets.kt

Per impostazione predefinita, le anteprime che utilizzano @PreviewParameter vengono denominate utilizzando l'indice del parametro e il nome della proprietà (utente 0, utente 1, utente 2 e così via), il che può rendere difficile distinguerle. Per migliorare la chiarezza dell'anteprima, puoi fornire nomi visualizzati personalizzati per ogni anteprima sostituendo getDisplayName() in PreviewParameterProvider. In questo modo è più facile distinguere tra le diverse varianti dei dati o gli stati dell'UI. Ad esempio, puoi etichettare le anteprime in base ai dati di input:

class UserAgePreviewParameterProvider : PreviewParameterProvider<User> {
    // Using a List internally for efficient index-based access
    private val userList = listOf(
        User(name = "Elise", age = 30),
        User(name = "Frank", age = 31),
        User(name = "Julia", age = 40)
    )

    override val values = userList.asSequence()

    override fun getDisplayName(index: Int): String? {
        // Return null or an empty string to use the default index-based name
        val user = userList.getOrNull(index) ?: return null
        return "${user.name} - ${user.age}"
    }
}
AndroidStudioComposeSnippets.kt

Generazione di anteprime assistita dall'AI

L'agente AI in Android Studio può generare automaticamente anteprime di Compose per i tuoi componibili. Fai clic con il tasto destro del mouse su una funzione componibile e seleziona AI > Genera anteprima per [nome componibile]. L'agente analizza il componibile per generare il boilerplate @Preview necessario con i parametri corretti, aiutandoti a verificare rapidamente che l'UI venga sottoposta a rendering come previsto.

Classe di annotazione @Preview

Puoi sempre fare clic su "ctrl o ⌘ + clic" sull'annotazione @Preview in Android Studio per visualizzare un elenco completo dei parametri che possono essere modificati 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,
)
AndroidStudioComposeSnippets.kt

Limitazioni e best practice

Android Studio esegue il codice delle anteprime direttamente nell'area di anteprima. Non è necessario eseguire un emulatore o un dispositivo fisico perché sfrutta una parte del framework Android chiamata Layoutlib. Layoutlib è una versione personalizzata del framework Android progettata per essere eseguita al di fuori dei dispositivi Android. L'obiettivo della libreria è fornire un'anteprima di un layout in Android Studio molto simile al rendering sui dispositivi.

Limitazioni delle anteprime

Grazie al modo in cui le anteprime vengono sottoposte a rendering in Android Studio, sono leggere e non richiedono l'intero framework Android per il rendering. Tuttavia, ciò comporta le seguenti limitazioni:

• Nessun accesso di rete
• Nessun accesso ai file
• Alcune API Context potrebbero non essere completamente disponibili

Anteprime e ViewModels

Le anteprime sono limitate quando si utilizza ViewModel all'interno di un componibile. Il sistema di anteprime non è in grado di costruire tutti i parametri passati a un ViewModel, come repository, casi d'uso, gestori o simili. Inoltre, se il ViewModel partecipa all'inserimento delle dipendenze (ad esempio con Hilt), il sistema di anteprime non può creare l'intero grafico delle dipendenze per costruire il ViewModel.

Quando provi a visualizzare l'anteprima di un componibile con ViewModel, Android Studio mostra un errore durante il rendering del componibile specifico:

Se vuoi visualizzare l'anteprima di un componibile che utilizza un ViewModel, devi creare un altro componibile con i parametri di ViewModel passati come argomenti del componibile. In questo modo, non devi visualizzare l'anteprima del componibile che utilizza il ViewModel.

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

@Composable
fun AuthorScreen(
  name: NameLabel,
  posts: PostsList
) {
  // ...
}

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

Risorse aggiuntive

• Per saperne di più su come Android Studio promuove la facilità d'uso di @Preview e per altri suggerimenti sugli strumenti, consulta il blog Compose Tooling.
• Per le linee guida sulle visualizzazioni legacy, consulta Sviluppare un layout con le visualizzazioni.