Prévisualiser votre UI avec des aperçus composables

Un composable est défini par une fonction et annoté avec @Composable:

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

Un élément de texte simple contenant les mots "Hello"
Monde"

Pour activer un aperçu de ce composable, créez-en un autre, annoté avec @Composable et @Preview. Ce nouveau composable annoté contient désormais le composable que vous avez créé initialement, SimpleComposable:

@Preview
@Composable
fun SimpleComposablePreview() {
    SimpleComposable()
}

L'annotation @Preview indique à Android Studio que Le composable doit être affiché dans la vue Conception de ce fichier. Vous pouvez voir en direct des mises à jour de l'aperçu de votre composable lorsque vous apportez des modifications.

GIF montrant des mises à jour en temps réel à l'aide de Compose
Aperçu

Vous pouvez ajouter des paramètres manuellement dans votre code pour personnaliser la manière dont Android Studio affiche @Preview. Vous pouvez même ajouter l'annotation @Preview au même plusieurs fois pour prévisualiser un composable avec différentes propriétés.

L'un des principaux avantages de l'utilisation de composables @Preview est d'éviter de dépendre sur l'émulateur dans Android Studio. Vous pouvez éviter le démarrage gourmand en mémoire du pour plus de modifications finales de l'apparence et pour permettre à @Preview d'effectuer et tester facilement de petites modifications du code.

Pour exploiter au mieux l'annotation @Preview, assurez-vous de définir votre en fonction de l'état qu'il reçoit en tant qu'entrée et des événements qu'il de sortie.

Définissez votre @Preview

Android Studio propose plusieurs fonctionnalités pour étendre l'aperçu des composables. Vous pouvez modifier leur conception de conteneur, interagir avec ou les déployer directement sur un émulateur ou un appareil.

Dimensions

Par défaut, les dimensions @Preview sont choisies automatiquement pour encapsuler son contenu. Pour définir les dimensions manuellement, ajoutez les paramètres heightDp et widthDp. Ces les valeurs sont déjà interprétées comme dp. Vous n'avez donc pas besoin d'ajouter .dp pour eux:

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

Un carré jaune avec les mots "Bonjour"
Monde"

Prévisualisation de la couleur dynamique

Si vous avez activé les couleur dans votre application, Utilisez l'attribut wallpaper pour changer de fond d'écran et voir comment votre UI réagit d'utilisateurs différents le fond d'écran choisi. Faites votre choix parmi les différents thèmes de fond d'écran proposées par le Wallpaper . Cette fonctionnalité nécessite Compose 1.4.0 ou version ultérieure.

Utiliser avec différents appareils

Dans Android Studio Flamingo, vous pouvez modifier le paramètre device de l'aperçu pour définir des configurations pour vos composables sur différents appareils.

Exemple de composable
fonction

Si le paramètre d'appareil comporte une chaîne vide (@Preview(device = "")), vous pouvez : invoquer la saisie semi-automatique en appuyant sur Ctrl+Space. Vous pouvez ensuite définir les valeurs de chaque paramètre.

Modifier l'exemple
fonction

Depuis la saisie semi-automatique, vous pouvez sélectionner n'importe quelle option d'appareil dans la liste, par exemple, @Preview(device = "id:pixel_4") Vous pouvez également saisir un appareil personnalisé en choisissant spec:width=px,height=px,dpi=int… pour définir les valeurs individuelles pour chaque paramètre.

Caractéristiques techniques
liste

Pour appliquer, appuyez sur Enter ou annulez avec Esc.

Si vous définissez une valeur non valide, la déclaration est soulignée en rouge, et une correction peut (Alt + Enter (⌥ + pour macOS) > Remplacer par...). L'inspection tente de fournir un correctif qui se rapproche le plus de votre entrée.

Exemple de valeur incorrecte
valeur

Langue

Pour tester différents paramètres régionaux utilisateur, ajoutez le paramètre locale:

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

Élément de texte simple contenant le mot "Bonjour" avec un Français
indicateur

Définir la couleur de l'arrière-plan

Par défaut, votre composable s'affiche avec un arrière-plan transparent. Pour ajouter un arrière-plan, ajoutez les paramètres showBackground et backgroundColor. Conserver dans notez que backgroundColor est de type Long ARVB, et non Color :

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

Rectangle vert avec les mots "Hello"
Monde"

UI du système

Si vous devez afficher les barres d'état et d'action dans un aperçu, ajoutez le paramètre showSystemUi :

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

Fenêtre d'aperçu affichant une activité avec les barres d'état et d'action.

Mode UI

Le paramètre uiMode peut utiliser n'importe quel élément Configuration.UI_* et vous permet de modifier le comportement de l'aperçu en conséquence. Par exemple, vous pouvez passer l'aperçu en mode Nuit pour observer la réaction du thème.

UI d'aperçu de Compose

LocalInspectionMode

Vous pouvez consulter le LocalInspectionMode CompositionLocal pour voir si le composable est affiché dans un aperçu (dans une composant Inspectable). Si la composition est affichée Dans un aperçu, LocalInspectionMode.current prend la valeur true. Ce vous permet de personnaliser votre aperçu. Par exemple, vous pouvez afficher dans la fenêtre d'aperçu au lieu d'afficher des données réelles.

De cette façon, vous pouvez également contourner les limites. Pour montrant des exemples de données au lieu d'appeler une requête réseau.

@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!")
    }
}

Interagir avec votre @Preview

Android Studio fournit des fonctionnalités qui vous permettent d'interagir avec vos des aperçus. Cette interaction vous aide à comprendre vos aperçus comportement lors de l'exécution et vous permet de mieux naviguer dans votre interface utilisateur grâce aux aperçus.

Mode interactif

Le mode interactif vous permet d'interagir avec un aperçu comme vous le feriez sur un appareil exécutant votre programme, comme un téléphone ou une tablette. Le mode interactif est isolé dans un environnement de bac à sable (c'est-à-dire, des autres aperçus) ; où vous pouvez cliquer sur les éléments et saisir l'entrée utilisateur dans l'aperçu. Il s'agit d'un rapide pour tester différents états, gestes et même animations de votre composable.

L'utilisateur cliquant sur l'écran "interactif" de l'aperçu
bouton

Une vidéo de l'utilisateur interagissant avec
aperçu

Navigation dans le code et contours d'un composable

Vous pouvez pointer sur un aperçu pour afficher les contours des composables qu'il contient. Cliquez sur le contour d'un composable pour accéder à sa définition dans la vue de l'éditeur.

Utilisateur passant la souris sur un aperçu, Studio affiche les contours de
son
composables

Exécuter l'aperçu

Vous pouvez exécuter un @Preview spécifique sur un émulateur ou sur un appareil physique. La l'aperçu est déployé dans la même application de projet qu'un nouveau Activity. Il partage le même contexte et les mêmes autorisations. Vous n'avez pas besoin d'écrire Code récurrent qui demande une autorisation si elle a déjà été accordée.

Cliquez sur l'icône Run Preview (Exécuter l'aperçu) Exécuter l'aperçu
icône. à côté de l'annotation @Preview ou en haut de l'aperçu, et Android Studio déploie ce @Preview sur votre appareil connecté ou votre émulateur.

Utilisateur cliquant sur l'option "Exécuter l'aperçu" de l'aperçu
bouton

Vidéo de l'utilisateur déployant un aperçu sur la
appareil

Copier le rendu @Preview

Chaque aperçu affiché peut être copié en tant qu'image en effectuant un clic droit dessus.

L'utilisateur clique sur un aperçu pour le copier
l'image.

Plusieurs aperçus de la même annotation @Preview

Vous pouvez présenter plusieurs versions du même composable @Preview avec des spécifications différentes ou des paramètres différents transmis au composable. Ce vous pouvez réduire le code récurrent que vous auriez dû écrire.

Modèles d'aperçus multiples

androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ introduit le Multipreview Modèles d'API: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark, et @PreviewDynamicColors. Ainsi, avec une seule annotation, vous pouvez prévisualiser votre UI Compose dans des scénarios courants.

Prévisualisation de différentes polices et tailles d'écran à l'aide de modèles

Créer des annotations d'aperçus multiples personnalisées

L'aperçu multiple vous permet de définir une classe d'annotation comportant elle-même plusieurs annotations @Preview avec des configurations différentes. Ajout de cette annotation à Une fonction composable affiche automatiquement tous les aperçus au niveau une seule fois. Par exemple, vous pouvez utiliser cette annotation pour prévisualiser plusieurs appareils, tailles de police ou thèmes en même temps sans répéter ces définitions pour chaque composable.

Commencez par créer votre propre classe d'annotation personnalisée :

@Preview(
    name = "small font",
    group = "font scales",
    fontScale = 0.5f
)
@Preview(
    name = "large font",
    group = "font scales",
    fontScale = 1.5f
)
annotation class FontScalePreviews

Vous pouvez utiliser cette annotation personnalisée pour vos composables d'aperçu :

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

Onglet "Conception" d'Android Studio montrant le composable avec "petit" et "grand"
police

Vous pouvez combiner plusieurs annotations d'aperçus multiples et d'aperçus normaux. pour créer un ensemble d'aperçus plus complet. Combiner des annotations d'aperçus multiples ne signifie pas que toutes les différentes combinaisons sont affichées. Chaque annotation d'aperçus multiples agit indépendamment et n'affiche que ses propres variantes.

@Preview(
    name = "Spanish",
    group = "locale",
    locale = "es"
)
@FontScalePreviews
annotation class CombinedPreviews

@CombinedPreviews
@Composable
fun HelloWorldPreview2() {
    MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } }
}

Onglet "Conception" d'Android Studio affichant le composable dans toutes
Configurations

Grâce à la combinaison de l'aperçu multiple et de l'aperçu standard, vous pouvez tester de manière exhaustive de nombreuses propriétés de projets à plus grande échelle.

@Preview et grands ensembles de données

Très souvent, vous avez besoin de transmettre un ensemble de données volumineux à votre composable. un aperçu. Pour ce faire, il vous suffit de transmettre des échantillons de données à une fonction d'aperçu du composable en en ajoutant un paramètre avec @PreviewParameter ; .

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

Pour fournir les exemples de données, créez une classe qui implémente PreviewParameterProvider et renvoie la d'échantillons de données sous forme de séquence.

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

Cela permet d'afficher un aperçu par élément de données de la séquence:

Aperçus d&#39;Elise, Frank et Julia
composables

Vous pouvez utiliser la même classe de fournisseur pour plusieurs aperçus. Si nécessaire, limitez le nombre d'aperçus en définissant le paramètre de limite.

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

Limites et bonnes pratiques

Android Studio exécute le code d'aperçu directement dans la zone d'aperçu. Non nécessitent l'exécution d'un émulateur ou d'un appareil physique, car ils utilisent un port une partie du framework Android appelée Layoutlib. Layoutlib est une valeur personnalisée version du framework Android conçue pour fonctionner en dehors des appareils Android. La l'objectif de la bibliothèque est de fournir un aperçu d'une mise en page dans Android Studio est très proche de son rendu sur les appareils.

Limites des aperçus

En raison de la façon dont les aperçus sont affichés dans Android Studio, ils sont et ne nécessitent pas l'ensemble du framework Android pour les afficher. Toutefois, cette approche s'accompagne des limites suivantes:

  • Aucun accès au réseau
  • Aucun accès aux fichiers
  • Certaines API Context peuvent ne pas être entièrement disponibles.

Aperçus et ViewModels

Les aperçus sont limités lorsque vous utilisez ViewModel dans un composable. Le système de prévisualisation n'est pas en mesure de construire tous les les paramètres transmis à un ViewModel, tels que les dépôts, les cas d'utilisation, les gestionnaires, ou similaire. De plus, si votre ViewModel participe à l'injection de dépendances (comme comme avec Hilt), le système de prévisualisation ne peut pas créer l'intégralité de la dépendance graphique pour construire le ViewModel.

Lorsque vous essayez de prévisualiser un composable avec ViewModel, Android Studio affiche une lors de l'affichage du composable concerné:

Volet du problème Android Studio avec l&#39;échec de l&#39;instanciation d&#39;un ViewModel
message

Si vous souhaitez prévisualiser un composable qui utilise un ViewModel, vous devez créer un autre composable avec les paramètres de ViewModel transmis en tant qu'arguments de le composable. Ainsi, vous n'avez pas besoin de prévisualiser le composable qui utilise le 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 d'annotation @Preview

Vous pouvez toujours utiliser la touche Ctrl ou ⌘+clic. l'annotation @Preview dans Android ; Studio pour obtenir la liste complète des paramètres que vous pouvez ajuster lorsque vous personnalisez votre un aperçu.

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,
)

Ressources supplémentaires

Pour en savoir plus sur la manière dont Android Studio favorise la facilité d'utilisation de @Preview, et pour découvrir plus de conseils sur les outils, consultez le blog Compose Outils :