Benutzeroberfläche mit zusammensetzbaren Vorschauen als Vorschau ansehen

Ein Composable wird durch eine Funktion definiert und mit @Composable annotiert:

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

Wenn Sie eine Vorschau dieses Composables aktivieren möchten, erstellen Sie ein weiteres Composable, das mit @Composable und @Preview annotiert ist. Dieses neue, annotierte Composable enthält jetzt das ursprünglich erstellte Composable SimpleComposable:

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

Die @Preview Annotation weist Android Studio an, dieses Composable in der Designansicht dieser Datei anzuzeigen. Sie können Live-Updates der Vorschau des Composables sehen, während Sie Änderungen vornehmen.

**Hinweis**: Android Wear verwendet für Vorschauen andere Annotationen (@WearPreviewDevices und @WearPreviewFontScales). Weitere Informationen finden Sie unter Kombinationen von Bildschirm- und Schriftgrößen mit Vorschauen testen.

Sie können in Ihrem Code manuell Parameter hinzufügen, um die Art und Weise anzupassen, wie Android Studio @Preview rendert. Sie können die Annotation @Preview sogar mehrmals derselben Funktion hinzufügen, um eine Vorschau eines Composables mit verschiedenen Eigenschaften zu sehen.

Hinweis: Wenn Sie mehrere Vorschauen von komponierbaren Funktionen haben, sich aber jeweils nur auf eine Vorschau konzentrieren möchten, empfehlen wir, den Konzentrationsmodus zu verwenden, um Renderingressourcen zu sparen. Wechseln Sie in den Raster- oder Listenmodus, wenn Sie alle UI-Varianten gleichzeitig sehen möchten. Sie können über das Menü oben auf dem Tab Design zwischen den Modi wechseln.

Einer der Hauptvorteile der Verwendung von @Preview-Composables besteht darin, dass Sie den Emulator in Android Studio nicht mehr benötigen. Sie können den speicherintensiven Start des Emulators für endgültige Änderungen am Erscheinungsbild aufheben und die Möglichkeit von @Preview nutzen, kleine Codeänderungen einfach vorzunehmen und zu testen.

Wenn Sie die Annotation @Preview optimal nutzen möchten, definieren Sie Ihre Bildschirme anhand des Status, den sie als Eingabe erhalten, und der Ereignisse, die sie ausgeben.

@Preview definieren

Android Studio bietet einige Funktionen, um Vorschauen von Composables zu erweitern. Sie können das Design des Containers ändern, mit ihnen interagieren oder sie direkt in einem Emulator oder auf einem Gerät bereitstellen.

Abmessungen

Standardmäßig werden die @Preview-Abmessungen automatisch so ausgewählt, dass sie den Inhalt umschließen. Wenn Sie die Abmessungen manuell festlegen möchten, fügen Sie die Parameter heightDp und widthDp hinzu. Diese Werte werden bereits als dp interpretiert, sodass Sie .dp nicht hinzufügen müssen:

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

Dynamische Farbvorschau

Wenn Sie in Ihrer App dynamische Farben aktiviert haben, verwenden Sie das Attribut wallpaper, um zwischen Hintergrundbildern zu wechseln und zu sehen, wie Ihre UI auf das vom Nutzer ausgewählte Hintergrundbild reagiert. Wählen Sie aus den verschiedenen Hintergrundbilddesigns der Wallpaper Klasse aus. Für diese Funktion ist Compose 1.4.0 oder höher erforderlich.

Verwendung mit verschiedenen Geräten

In Android Studio Flamingo können Sie den Parameter device der Annotation „Vorschau“ bearbeiten, um Konfigurationen für Ihre Composables auf verschiedenen Geräten zu definieren.

Wenn der Geräteparameter einen leeren String enthält (@Preview(device = "")), können Sie die automatische Vervollständigung aufrufen, indem Sie Ctrl + Space drücken. Anschließend können Sie die Werte der einzelnen Parameter festlegen.

Über die automatische Vervollständigung können Sie eine beliebige Geräteoption aus der Liste auswählen, z. B. @Preview(device = "id:pixel_4"). Alternativ können Sie ein benutzerdefiniertes Gerät eingeben, indem Sie spec:width=px,height=px,dpi=int… auswählen, um die einzelnen Werte der einzelnen Parameter festzulegen.

Drücken Sie Enter, um die Änderungen anzuwenden, oder Esc, um sie zu verwerfen.

Wenn Sie einen ungültigen Wert festlegen, wird die Deklaration rot unterstrichen und möglicherweise ist eine Korrektur verfügbar (Alt + Enter (⌥ + ⏎ für macOS) > Durch … ersetzen). Die Inspektion versucht, eine Korrektur bereitzustellen, die Ihrer Eingabe am nächsten kommt.

Sprache

Wenn Sie verschiedene Sprachen testen möchten, fügen Sie den Parameter locale hinzu:

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

Hintergrundfarbe festlegen

Standardmäßig wird Ihr Composable mit einem transparenten Hintergrund angezeigt. Wenn Sie einen Hintergrund hinzufügen möchten, fügen Sie die Parameter showBackground und backgroundColor hinzu. Beachten Sie, dass backgroundColor ein ARGB Long und kein Color Wert ist:

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

System-UI

Wenn Sie die Status- und Aktionsleisten in einer Vorschau anzeigen möchten, fügen Sie den Parameter showSystemUi hinzu:

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

UI-Modus

Der Parameter uiMode kann eine beliebige der Configuration.UI_* Konstanten annehmen und ermöglicht es Ihnen, das Verhalten der Vorschau entsprechend zu ändern. Sie können beispielsweise den Nachtmodus für die Vorschau festlegen, um zu sehen, wie das Design reagiert.

LocalInspectionMode

Sie können von LocalInspectionMode CompositionLocal lesen, um zu sehen, ob das Composable in einer Vorschau (in einer überprüfbaren Komponente) gerendert wird. Wenn die Komposition in einer Vorschau gerendert wird, wird LocalInspectionMode.current als true ausgewertet. Mit diesen Informationen können Sie Ihre Vorschau anpassen. Sie können beispielsweise ein Platzhalterbild im Vorschaufenster anzeigen, anstatt echte Daten zu verwenden.

Auf diese Weise können Sie auch die Einschränkungen umgehen. Sie können beispielsweise Beispieldaten anzeigen, anstatt eine Netzwerkanfrage aufzurufen.

@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

Mit @Preview interagieren

Android Studio bietet Funktionen, mit denen Sie mit den von Ihnen definierten Vorschauen interagieren können. Diese Interaktion hilft Ihnen, das Laufzeitverhalten Ihrer Vorschauen zu verstehen und besser in Ihrer UI zu navigieren.

Interaktiver Modus

Im interaktiven Modus können Sie mit einer Vorschau so interagieren, wie Sie es auf einem Gerät tun würden, auf dem Ihr Programm ausgeführt wird, z. B. auf einem Smartphone oder Tablet. Der interaktive Modus ist in einer Sandbox-Umgebung isoliert (d. h. von anderen Vorschauen isoliert). Dort können Sie auf Elemente klicken und Nutzereingaben in der Vorschau eingeben. So können Sie schnell verschiedene Status, Gesten und sogar Animationen Ihres Composables testen.

Code-Navigation und Umrisse von Composables

Sie können den Mauszeiger auf eine Vorschau bewegen, um die Umrisse der darin enthaltenen Composables zu sehen. Wenn Sie auf einen Umriss eines Composables klicken, wird in der Editoransicht zu seiner Definition navigiert.

Vorschau ausführen

Sie können eine bestimmte @Preview auf einem Emulator oder einem physischen Gerät ausführen. Die Vorschau wird in derselben Projekt-App als neue Activity bereitgestellt, sodass sie denselben Kontext und dieselben Berechtigungen hat. Sie müssen keinen Boilerplate-Code schreiben, um eine Berechtigung anzufordern, wenn sie bereits erteilt wurde.

Hinweis: Die Argumente, die auf die Annotation @Preview angewendet werden (z. B. widthDp, locale usw.), werden nicht auf die ausgeführte und bereitgestellte Vorschau angewendet.

Klicken Sie neben der Annotation @Preview oder oben in der Vorschau auf das Symbol Vorschau ausführen . Android Studio stellt diese @Preview dann auf Ihrem verbundenen Gerät oder Emulator bereit.

@Preview-Rendering kopieren

Jede gerenderte Vorschau kann als Bild kopiert werden. Klicken Sie dazu mit der rechten Maustaste darauf.

Mehrere Vorschauen derselben @Preview-Annotation

Sie können mehrere Versionen desselben @Preview-Composables mit unterschiedlichen Spezifikationen oder unterschiedlichen Parametern, die an das Composable übergeben werden, präsentieren. So können Sie den Boilerplate-Code reduzieren, den Sie sonst schreiben müssten.

Vorlagen für mehrere Vorschauen

Mit androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ werden Vorlagen für die Multipreview API eingeführt: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark und @PreviewDynamicColors. So können Sie mit einer einzigen Annotation eine Vorschau Ihrer Compose UI in gängigen Szenarien sehen.

Benutzerdefinierte Multipreview-Annotationen erstellen

Mit Multipreview können Sie eine Annotationsklasse definieren, die selbst mehrere @Preview-Annotationen mit unterschiedlichen Konfigurationen enthält. Wenn Sie diese Annotation einer Composable-Funktion hinzufügen, werden automatisch alle verschiedenen Vorschauen gleichzeitig gerendert. Sie können diese Annotation beispielsweise verwenden, um gleichzeitig eine Vorschau auf mehreren Geräten, mit verschiedenen Schriftgrößen oder Designs zu sehen, ohne diese Definitionen für jedes einzelne Composable zu wiederholen.

Erstellen Sie zuerst eine eigene benutzerdefinierte Annotationsklasse:

@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

Sie können diese benutzerdefinierte Annotation für Ihre Vorschau-Composables verwenden:

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

Sie können mehrere Multipreview-Annotationen und normale Vorschau-Annotationen kombinieren, um eine umfassendere Reihe von Vorschauen zu erstellen. Wenn Sie Multipreview-Annotationen kombinieren, werden nicht alle verschiedenen Kombinationen angezeigt. Stattdessen funktioniert jede Multipreview-Annotation unabhängig und rendert nur ihre eigenen Varianten.

@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

Durch die Kombination von Multipreview- und normalen Vorschau-Annotationen können Sie viele Eigenschaften von Projekten im größeren Maßstab umfassender testen.

@Preview und große Datasets

Sehr oft müssen Sie ein großes Dataset an Ihre Composable-Vorschau übergeben. Dazu übergeben Sie einfach Beispieldaten an eine Composable-Vorschaufunktion, indem Sie einen Parameter mit der @PreviewParameter Annotation hinzufügen.

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

Um die Beispieldaten bereitzustellen, erstellen Sie eine Klasse, die PreviewParameterProvider implementiert und die Beispieldaten als Sequenz zurückgibt.

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

Dadurch wird eine Vorschau pro Datenelement in der Sequenz gerendert:

Sie können dieselbe Anbieterklasse für mehrere Vorschauen verwenden. Begrenzen Sie bei Bedarf die Anzahl der Vorschauen, indem Sie den Parameter „limit“ festlegen.

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

Vorschauen mit @PreviewParameter werden standardmäßig mit dem Parameterindex und dem Eigenschaftsnamen benannt (Nutzer 0, Nutzer 1, Nutzer 2 usw.), was es schwierig machen kann, sie zu unterscheiden. Um die Übersichtlichkeit der Vorschau zu verbessern, können Sie benutzerdefinierte Anzeigenamen für jede Vorschau angeben, indem Sie getDisplayName() in Ihrem PreviewParameterProvider überschreiben. So können Sie zwischen verschiedenen Datenvarianten oder UI-Status unterscheiden. Sie können Vorschauen beispielsweise anhand der Eingabedaten kennzeichnen:

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

Tipp: Für eine bessere Leistung sollten Sie Ihre Sequence in der PreviewParameterProvider mit einer List sichern. So erhalten Sie einen effizienten indexbasierten Zugriff in getDisplayName() und vermeiden langsame Suchvorgänge in großen Sequenzen.

KI-gestützte Vorschaugenerierung

Der KI-Agent in Android Studio kann automatisch Compose-Vorschauen für Ihre Composables generieren. Klicken Sie mit der rechten Maustaste auf eine Composable-Funktion und wählen Sie KI > Vorschau für [Composable-Name]generieren aus. Der Agent analysiert Ihr Composable, um den erforderlichen Boilerplate-Code für @Preview mit den richtigen Parametern zu generieren. So können Sie schnell überprüfen, ob Ihre UI wie erwartet gerendert wird.

Compose-Vorschau mit KI generieren

Annotationsklasse @Preview

Sie können in Android Studio jederzeit mit „Strg + Klick“ oder „⌘ + Klick“ auf die Annotation @Preview klicken, um eine vollständige Liste der Parameter zu sehen, die Sie beim Anpassen Ihrer Vorschau anpassen können.

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

Beschränkungen und Best Practices

Android Studio führt den Code für die Vorschau direkt im Vorschaufenster aus. Es ist nicht erforderlich, einen Emulator oder ein physisches Gerät auszuführen, da ein portierter Teil des Android-Frameworks namens Layoutlib verwendet wird. Layoutlib ist eine benutzerdefinierte Version des Android-Frameworks, die außerhalb von Android-Geräten ausgeführt werden kann. Ziel der Bibliothek ist es, eine Vorschau eines Layouts in Android Studio zu bieten, die der Darstellung auf Geräten sehr nahe kommt.

Einschränkungen bei Vorschauen

Da Vorschauen in Android Studio gerendert werden, sind sie ressourcenschonend und erfordern nicht das gesamte Android-Framework. Dies ist jedoch mit den folgenden Einschränkungen verbunden:

• Kein Netzwerkzugriff
• Kein Dateizugriff
• Einige Context-APIs sind möglicherweise nicht vollständig verfügbar

Vorschauen und ViewModels

Vorschauen sind eingeschränkt, wenn Sie ViewModel in einem Composable verwenden. Das Vorschausystem kann nicht alle Parameter erstellen, die an ein ViewModel übergeben werden, z. B. Repositories, Anwendungsfälle, Manager oder Ähnliches. Wenn Ihr ViewModel an der Abhängigkeitsinjektion beteiligt ist (z. B. mit Hilt), kann das Vorschausystem außerdem nicht den gesamten Abhängigkeitsgraphen erstellen, um das ViewModel zu erstellen.

Wenn Sie versuchen, eine Vorschau eines Composables mit ViewModel zu sehen, zeigt Android Studio beim Rendern des jeweiligen Composables einen Fehler an:

Warnung: Sie sollten die ViewModel Instanzen nicht an andere Composable Funktionen übergeben. Dadurch werden die Composables mit dem ViewModel-Typ gekoppelt, was sie weniger wiederverwendbar, schwieriger zu testen und nicht in der Vorschau anzeigbar macht.

Wenn Sie eine Vorschau eines Composables sehen möchten, das ein ViewModel verwendet, sollten Sie ein weiteres Composable erstellen, wobei die Parameter aus ViewModel als Argumente des Composables übergeben werden. So müssen Sie keine Vorschau des Composables sehen, das das ViewModel verwendet.

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

Zusätzliche Ressourcen

• Weitere Informationen dazu, wie Android Studio die Verwendung von @Preview erleichtert, und erfahren Sie mehr Tipps zu den Tools, lesen Sie den Blog Compose Tooling.
• Eine Anleitung für die Legacy-Ansichten finden Sie unter Layout mit Ansichten entwickeln.