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

Ein einfaches Textelement mit den Worten „Hello World“

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

Die Annotation @Preview teilt Android Studio mit, dass diese zusammensetzbare Funktion in der Designansicht dieser Datei angezeigt werden soll. Sie können sich während der Bearbeitung Live-Updates Ihrer composable-Vorschau ansehen.

Ein GIF, das Echtzeitaktualisierungen mit der Funktion „Compose Preview“ zeigt

Sie können Ihrem Code manuell Parameter hinzufügen, um die Darstellung von @Preview in Android Studio anzupassen. Sie können die Annotation @Preview sogar mehrmals derselben Funktion hinzufügen, um eine Vorschau einer zusammensetzbaren Funktion mit unterschiedlichen Eigenschaften zu erhalten.

Einer der Hauptvorteile der Verwendung von @Preview-Kompositionen besteht darin, dass Sie nicht auf den Emulator in Android Studio angewiesen sind. Sie können den speicherintensiven Start des Emulators für weitere Änderungen am Erscheinungsbild aufsparen und die Fähigkeit von @Preview nutzen, kleine Codeänderungen einfach vorzunehmen und zu testen.

Damit Sie die Annotation @Preview optimal nutzen können, sollten Sie Ihre Bildschirme im Hinblick auf den Status, den sie als Eingabe erhalten, und die Ereignisse, die sie ausgeben, definieren.

@Preview definieren

Android Studio bietet einige Funktionen, mit denen sich die Voransichten von komponierbaren Funktionen erweitern lassen. Sie können das Containerdesign ändern, mit ihnen interagieren oder sie direkt auf einem Emulator oder Gerät bereitstellen.

Abmessungen

Standardmäßig werden die Abmessungen von @Preview automatisch so gewählt, dass der Inhalt umschlossen wird. 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")
    }
}

Ein gelbes Quadrat mit dem Text „Hello World“

Vorschau für dynamische Farben

Wenn du in deiner App dynamische Farben aktiviert hast, kannst du mit dem Attribut wallpaper das Hintergrundbild wechseln und sehen, wie deine Benutzeroberfläche auf das von verschiedenen Nutzern ausgewählte Hintergrundbild reagiert. Wähle eines der verschiedenen Hintergrunddesigns aus, die von der Klasse Wallpaper angeboten werden. Für diese Funktion ist Compose 1.4.0 oder höher erforderlich.

Mit verschiedenen Geräten verwenden

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

Beispiel für eine zusammensetzbare Funktion

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

Beispielfunktion bearbeiten

Über die automatische Vervollständigung kannst du 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 Parameter festzulegen.

Spezifikationsliste

Drücken Sie zum Übernehmen Enter oder zum Abbrechen Esc.

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

Beispiel für einen ungültigen Wert

Sprache

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

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

Ein einfaches Textelement mit dem Wort „Bonjour“ und einer französischen Flagge

Hintergrundfarbe festlegen

Standardmäßig wird das Compose-Element 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-Wert und kein Color-Wert ist:

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

Ein grünes Rechteck mit dem Text „Hello World“

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

Ein Vorschaufenster, in dem eine Aktivität mit Status- und Aktionsleiste angezeigt wird.

UI-Modus

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

UI für Erstellung der Vorschau

LocalInspectionMode

Sie können den LocalInspectionMode CompositionLocal auslesen, um zu sehen, ob die komponierbare Funktion in einer Vorschau (innerhalb einer prüfbaren Komponente) gerendert wird. Wenn die Komposition in einer Vorschau gerendert wird, wird LocalInspectionMode.current als true ausgewertet. Anhand dieser Informationen können Sie die Vorschau anpassen. Sie können beispielsweise ein Platzhalterbild im Vorschaufenster anzeigen lassen, anstatt echte Daten zu zeigen.

So können Sie auch die Einschränkungen umgehen. Beispielsweise können Sie Beispieldaten anzeigen, anstatt eine Netzwerkanfrage zu senden.

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

Mit @Preview interagieren

Android Studio bietet Funktionen, mit denen Sie mit Ihren definierten Vorabversionen interagieren können. Diese Interaktion hilft Ihnen, das Laufzeitverhalten Ihrer Vorschauen zu verstehen, und ermöglicht es Ihnen, mit Vorschauen besser in Ihrer Benutzeroberfläche zu navigieren.

Interaktiver Modus

Im interaktiven Modus können Sie mit einer Vorschau ähnlich interagieren wie auf einem Gerät, auf dem Ihr Programm ausgeführt wird, z. B. 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 vornehmen. So können Sie schnell verschiedene Zustände, Gesten und sogar Animationen Ihrer komponierbaren Funktion testen.

Der Nutzer klickt in der Vorschau auf den Button „Interaktiv“.

Ein Video, in dem der Nutzer mit einer Vorschau interagiert

Codenavigation und zusammensetzbare Gliederungen

Wenn du den Mauszeiger auf eine Vorschau bewegst, werden die Umrisse der darin enthaltenen Composables angezeigt. Wenn Sie auf eine Gliederung für eine komponierbare Funktion klicken, wird in der Bearbeitungsansicht die entsprechende Definition aufgerufen.

Der Nutzer bewegt den Mauszeiger über eine Vorschau, sodass in Studio die Umrisse der Composables angezeigt werden.

Vorschau ausführen

Sie können einen bestimmten @Preview auf einem Emulator oder einem physischen Gerät ausführen. Die Vorabversion 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 gewährt wurde.

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

Der Nutzer klickt auf die Vorschau,

Video, in dem der Nutzer eine Vorschau auf dem Gerät bereitstellt

@Preview-Rendering kopieren

Jede gerenderte Vorschau kann durch Rechtsklick als Bild kopiert werden.

Der Nutzer klickt auf eine Vorschau, um sie als Bild zu kopieren.

Mehrere Vorschauen derselben @Preview-Annotation

Du kannst mehrere Versionen derselben @Preview komponierbaren Funktion mit unterschiedlichen Spezifikationen oder unterschiedlichen Parametern präsentieren, die an die komponierbare Funktion übergeben werden. So können Sie den Boilerplate-Code reduzieren, den Sie sonst schreiben müssten.

Vorlagen für mehrere Vorschauen

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

Vorschau verschiedener Schriftarten und Bildschirmgrößen mithilfe von Vorlagen

Benutzerdefinierte Multipreview-Annotationen erstellen

Mit der Mehrfachvorschau können Sie eine Annotationsklasse definieren, die selbst mehrere @Preview-Annotationen mit unterschiedlichen Konfigurationen hat. Wenn Sie diese Annotation einer zusammensetzbaren Funktion hinzufügen, werden alle verschiedenen Vorschauen automatisch gleichzeitig gerendert. Mit dieser Annotation können Sie sich beispielsweise mehrere Geräte, Schriftgrößen oder Designs gleichzeitig ansehen, ohne diese Definitionen für jede einzelne zusammensetzbare Funktion wiederholen zu müssen.

Erstellen Sie zuerst Ihre 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

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

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

Android Studio-Design-Tab mit der zusammensetzbaren Funktion mit kleiner und großer Schriftart

Sie können mehrere Multipreview-Annotationen und normale Vorschau-Annotationen kombinieren, um einen vollständigeren Satz von Vorschauen zu erstellen. Wenn Sie mehrere Vorschau-Annotationen kombinieren, werden nicht alle verschiedenen Kombinationen angezeigt. Stattdessen agiert 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)) } }
}

Android Studio-Design-Tab, auf dem die zusammensetzbare Funktion in allen Konfigurationen angezeigt wird

Durch die Kombinationsmöglichkeiten der Mehrfachvorschau und der normalen Vorschau können Sie viele Eigenschaften größerer Projekte umfassender testen.

@Preview und große Datasets

Sehr oft ist es erforderlich, ein großes Dataset an die composable Vorschau zu übergeben. Dazu übergeben Sie einfach Beispieldaten an eine Composable-Vorschaufunktion, indem Sie einen Parameter mit der Annotation @PreviewParameter hinzufügen.

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

Erstellen Sie zum Bereitstellen der Beispieldaten 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")
    )
}

Dadurch wird eine Vorschau pro Datenelement in der Sequenz gerendert:

Vorschauen der Composables „Elise“, „Frank“ und „Julia“

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

Vorschauen mit @PreviewParameter werden standardmäßig mit dem Parameterindex und dem Attributnamen (Nutzer 0, Nutzer 1, Nutzer 2 usw.) benannt. Dadurch kann es schwierig sein, sie voneinander zu unterscheiden. Wenn Sie die Übersichtlichkeit der Vorschau verbessern möchten, können Sie für jede Vorschau benutzerdefinierte Anzeigenamen angeben, indem Sie getDisplayName() in Ihrer PreviewParameterProvider überschreiben. So lassen sich verschiedene Datenvarianten oder UI-Zustände besser 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}"
    }
}

Vorschauen mit benutzerdefinierten Anzeigenamen, die die Composables „Elise – 30“, „Frank – 31“ und „Julia – 40“ zeigen

KI-gestützte Vorschauerstellung

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

Compose-Vorschau mit KI generieren

Anmerkungsklasse @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 aufzurufen, die Sie beim Anpassen der Vorschau ändern 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,
)

Beschränkungen und Best Practices

Android Studio führt den Code für die Vorschau direkt im Vorschaubereich aus. Es ist kein Emulator oder physisches Gerät erforderlich, da ein portierter Teil des Android-Frameworks namens Layoutlib verwendet wird. Layoutlib ist eine benutzerdefinierte Version des Android-Frameworks, die für die Ausführung außerhalb von Android-Geräten entwickelt wurde. Ziel der Bibliothek ist es, in Android Studio eine Vorschau eines Layouts bereitzustellen, die der Darstellung auf Geräten sehr nahe kommt.

Einschränkungen von Vorabversionen

Aufgrund der Art und Weise, wie Vorschauen in Android Studio gerendert werden, sind sie schlank und erfordern nicht das gesamte Android-Framework, um sie zu rendern. 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

Die Vorschau ist eingeschränkt, wenn ViewModel in einer zusammensetzbaren Funktion verwendet wird. Das Vorschausystem kann nicht alle Parameter erstellen, die an ein ViewModel übergeben werden, z. B. Repositories, Anwendungsfälle, Manager oder Ähnliches. Wenn Ihr ViewModel außerdem an der Abhängigkeitsinjektion beteiligt ist (z. B. mit Hilt), kann das Vorschausystem nicht das gesamte Abhängigkeitsdiagramm erstellen, um den ViewModel zu erstellen.

Wenn Sie versuchen, eine Vorschau einer zusammensetzbaren Funktion mit ViewModel aufzurufen, zeigt Android Studio beim Rendern der jeweiligen zusammensetzbaren Funktion einen Fehler an:

Android Studio-Problembereich mit der Meldung „Failed to instantiate a ‚ViewModel‘“

Wenn Sie eine Vorschau einer zusammensetzbaren Funktion mit einem ViewModel erstellen möchten, sollten Sie eine weitere zusammensetzbare Funktion mit den Parametern aus ViewModel als Argumente der zusammensetzbaren Funktion erstellen. So müssen Sie sich keine Vorschau des Composables ansehen, das die 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 Nutzerfreundlichkeit von @Preview fördert, und weitere Tipps zu Tools finden Sie im Blog Compose Tooling.
  • Eine Anleitung zu den alten Ansichten finden Sie unter Layout mit Ansichten entwickeln.
Weiter
Animationen als Vorschau ansehen und Fehler beheben