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

Un composable è definito da una funzione e annotato con @Composable:

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

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

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

L'annotazione @Preview indica ad Android Studio che questo composable deve essere visualizzato nella visualizzazione di progettazione di questo file. Puoi vedere gli aggiornamenti in tempo reale dell'anteprima del composable man mano che apporti le modifiche.

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

Uno dei principali vantaggi dell'utilizzo dei composabili @Preview è evitare di fare affidamento sull'emulatore in Android Studio. Puoi risparmiare sull'avvio dell'emulatore che richiede molta memoria per apportare modifiche più definitive all'aspetto e alla funzionalità e sulla capacità di @Preview di 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 riceve come input e di eventi che genera.

Definisci il @Preview

Android Studio offre alcune funzionalità per estendere le anteprime composable. Puoi cambiare il design del contenitore, interagire con i contenitori o eseguirne il deployment direttamente su un emulatore o un dispositivo.

Dimensioni

Per impostazione predefinita, le dimensioni @Preview vengono scelte automaticamente per a capo dei relativi contenuti. Per impostare le dimensioni manualmente, aggiungi i parametri heightDp e widthDp. Questi valori sono già interpretati come dp, quindi non è necessario aggiungere .dp:

@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 il colore dinamico nella tua app, usa l'attributo wallpaper per cambiare sfondo e vedere come reagisce la tua UI allo sfondo scelto da diversi utenti. Seleziona uno dei 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 tuoi composabili su dispositivi diversi.

Quando il parametro del dispositivo ha una stringa vuota (@Preview(device = "")), puoi invocare 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 ciascun 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 una correzione il più simile possibile al tuo input.

Impostazioni internazionali

Per testare impostazioni internazionali diverse, aggiungi il parametro locale:

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

Impostare il colore di sfondo

Per impostazione predefinita, il composable viene visualizzato con uno sfondo trasparente. Per aggiungere un sfondo, aggiungi i parametri showBackground e backgroundColor. Tieni presente che backgroundColor è un Long ARGB, 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 di azione in un'anteprima, aggiungi il parametro showSystemUi:

@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

Modalità UI

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

LocalInspectionMode

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

In questo modo, puoi anche aggirare le limitazioni. Ad esempio, mostrare 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

Interagire con @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 navigare meglio nell'interfaccia utente 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 programma, ad esempio uno smartphone o un tablet. La modalità interattiva è isolata in un ambiente sandbox (ovvero isolata da altre anteprime), dove puoi fare clic sugli elementi e inserire input utente nell'anteprima. È un modo rapido per testare diversi stati, gesti e persino animazioni del tuo composable.

Navigazione nel codice e schemi componibili

Puoi passare il mouse sopra un'anteprima per visualizzare i contorni dei composabili al suo interno. Se fai clic su un abbozzo componibile, la visualizzazione dell'editor ti consente di accedere alla relativa definizione.

Esegui anteprima

Puoi eseguire un @Preview specifico su un emulatore o un dispositivo fisico. La preview viene implementata all'interno della stessa app di progetto come nuovo Activity, pertanto 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 esegue il deployment di @Preview sul dispositivo o sull'emulatore connesso.

Copia il rendering di @Preview

Ogni anteprima visualizzata 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 composable @Preview con specifiche diverse o parametri diversi passati al composable. 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 e versioni successive introducono i modelli API Multipreview: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark e @PreviewDynamicColors, in modo che con una singola annotazione sia possibile visualizzare l'anteprima dell'interfaccia utente di Compose in scenari comuni.

Creare annotazioni di anteprima multipla personalizzate

Con la visualizzazione multipla, puoi definire una classe di annotazioni che contiene più @Preview annotazioni con configurazioni diverse. L'aggiunta di questa annotazione a una funzione componibile consente di visualizzare automaticamente tutte le diverse anteprime 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 composable.

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 composabili di anteprima:

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

Puoi combinare più annotazioni con più anteprime e annotazioni con anteprima normale per creare un insieme più completo di anteprime. La combinazione di annotazioni con più anteprime non implica che vengano mostrate tutte le diverse combinazioni. Invece, ogni annotazione con più anteprime agisce in modo indipendente e mostra solo le 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 combinata dell'anteprima multipla e dell'anteprima normale ti consente di testare in modo più completo molte proprietà di progetti di dimensioni maggiori.

@Preview e set di dati di grandi dimensioni

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

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

Per fornire i dati di esempio, crea una classe che implementi 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 visualizzata 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

Limitazioni e best practice

Android Studio esegue il codice di anteprima direttamente nell'area di anteprima. Non richiede l'esecuzione di un emulatore o di un dispositivo fisico perché sfrutta una parte del framework Android trasferita chiamata Layoutlib. Layoutlib è una versione personalizzata del framework Android progettata per funzionare al di fuori dei dispositivi Android. Lo scopo della libreria è fornire un'anteprima di un layout in Android Studio molto simile 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 la visualizzazione. Tuttavia, presenta 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 utilizzi ViewModel all'interno di un composable. Il sistema di anteprime non è in grado di costruire tutti i parametri passati a un ViewModel, ad esempio repository, casi d'uso, gestori o simili. Inoltre, se ViewModel partecipa all'iniezione di dipendenze (ad esempio con Hilt), il sistema di anteprime non può creare l'intero grafo di dipendenze per costruire ViewModel.

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

Se vuoi visualizzare l'anteprima di un composable che utilizza un ViewModel, devi creare un altro composable con i parametri di ViewModel passati come argomenti del composable. In questo modo, non è necessario visualizzare l'anteprima del composable che utilizza il 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 fare clic con Ctrl o ⌘ 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,
)
AndroidStudioComposeSnippets.kt

Risorse aggiuntive

Per scoprire di più su come Android Studio promuove la @Previewfacilità d'uso e ricevere altri suggerimenti sugli strumenti, consulta il blog Compose tooling.