Benutzeroberfläche mit zusammensetzbaren Vorschauen als Vorschau ansehen

Eine zusammensetzbare Funktion wird durch eine Funktion definiert und mit @Composable annotiert:

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

Wenn Sie eine Vorschau dieser zusammensetzbaren Funktion aktivieren möchten, erstellen Sie eine weitere zusammensetzbare Funktion, die mit @Composable und @Preview annotiert ist. Diese neue, annotierte zusammensetzbare Funktion enthält jetzt die von Ihnen erstellte zusammensetzbare Funktion SimpleComposable:

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

Die Annotation @Preview teilt Android Studio mit, dass diese zusammensetzbare Funktion in der Designansicht dieser Datei angezeigt werden soll. Sie können Live-Aktualisierungen der zusammensetzbaren Vorschau sehen, während Sie Änderungen vornehmen.

Sie können Ihrem Code manuell Parameter hinzufügen, um anzupassen, wie @Preview in Android Studio gerendert wird. Sie können die Annotation @Preview sogar mehrmals in dieselbe Funktion einfügen, um eine Vorschau einer zusammensetzbaren Funktion mit unterschiedlichen Attributen anzuzeigen.

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

Einer der wichtigsten Vorteile der Verwendung von @Preview-zusammensetzbaren Funktionen besteht darin, die Abhängigkeit vom Emulator in Android Studio zu vermeiden. Sie können den speicherintensiven Start des Emulators ersparen, um endgültige Änderungen am Erscheinungsbild vorzunehmen. Außerdem können Sie mit @Preview problemlos kleine Codeänderungen vornehmen und testen.

Damit Sie die @Preview-Annotation möglichst effektiv nutzen können, sollten Sie die Bildschirme hinsichtlich des Eingabestatus und der ausgegebenen Ereignisse definieren.

@Preview definieren

Android Studio bietet einige Funktionen zum Erweitern zusammensetzbarer Vorschauen. Sie können deren Containerdesign ändern, mit ihnen interagieren oder sie direkt in einem Emulator oder Gerät bereitstellen.

Abmessungen

Standardmäßig werden die Abmessungen @Preview automatisch ausgewählt, um den Inhalt zu 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

Vorschau der dynamischen Farben

Wenn Sie in Ihrer App die dynamische Farbe aktiviert haben, verwenden Sie das Attribut wallpaper, um den Hintergrund zu wechseln und zu sehen, wie die UI auf den vom Nutzer ausgewählten Hintergrund reagiert. Wählen Sie 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 Vorschauanmerkung bearbeiten, um Konfigurationen für Ihre zusammensetzbaren Funktionen auf verschiedenen Geräten zu definieren.

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. Dann können Sie die Werte jedes Parameters 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 angeben, indem Sie spec:width=px,height=px,dpi=int… auswählen, um die einzelnen Werte der einzelnen Parameter festzulegen.

Drücke zum Übernehmen Enter oder brich den Vorgang mit Esc ab.

Wenn du einen ungültigen Wert festlegst, wird die Deklaration rot unterstrichen und eine Korrektur ist möglicherweise verfügbar (Alt + Enter (⌥ + ⏎ für macOS) > Ersetzen durch...). Bei der Prüfung wird eine Lösung gefunden, die Ihrer Eingabe am nächsten kommt.

Sprache

Fügen Sie den Parameter locale hinzu, um verschiedene Nutzersprachen zu testen:

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

Hintergrundfarbe festlegen

Standardmäßig wird die zusammensetzbare Funktion vor einem transparenten Hintergrund angezeigt. Fügen Sie die Parameter showBackground und backgroundColor hinzu, um einen Hintergrund hinzuzufügen. Beachten Sie, dass backgroundColor ein ARGB-Wert 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 einblenden müssen, 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 Configuration.UI_*-Konstante annehmen und das Verhalten der Vorschau entsprechend ändern. Sie können beispielsweise für die Vorschau den Nachtmodus aktivieren, um zu sehen, wie das Design reagiert.

LocalInspectionMode

In LocalInspectionMode CompositionLocal können Sie sehen, ob die zusammensetzbare Funktion in einer Vorschau (in einer Inspectable-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. So können Sie beispielsweise anstelle der echten Daten ein Platzhalterbild im Vorschaufenster anzeigen lassen.

Auf diese Weise können Sie die Einschränkungen umgehen. Beispielsweise werden Beispieldaten angezeigt, 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 definierten Vorschauen interagieren können. Diese Interaktion hilft Ihnen, das Laufzeitverhalten Ihrer Vorschauen zu verstehen, und ermöglicht Ihnen, die Benutzeroberfläche mit Vorschauen besser zu bedienen.

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), in der Sie auf Elemente klicken und Nutzereingaben in die Vorschau eingeben können. So können Sie schnell verschiedene Status, Gesten und sogar Animationen Ihrer zusammensetzbaren Funktion testen.

Codenavigation und zusammensetzbare Gliederungen

Sie können den Mauszeiger auf eine Vorschau bewegen, um die Umrisse der enthaltenen zusammensetzbaren Funktionen zu sehen. Wenn Sie auf eine zusammensetzbare Gliederung klicken, wird in der Editoransicht die zugehörige Definition aufgerufen.

Vorschau ausführen

Du kannst eine bestimmte @Preview in einem Emulator oder einem physischen Gerät ausführen. Die Vorschau wird in derselben Projekt-App als eine neue Activity bereitgestellt, sodass ihr derselbe Kontext und dieselben Berechtigungen verwendet werden. Sie müssen keinen Boilerplate-Code schreiben, um eine Berechtigung anzufordern, wenn diese bereits erteilt wurden.

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

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

Rendering @Preview kopieren

Jede gerenderte Vorschau kann als Bild kopiert werden, indem Sie mit der rechten Maustaste darauf klicken.

Mehrere Vorschauen derselben @Preview-Anmerkung

Sie können mehrere Versionen derselben zusammensetzbaren Funktion (@Preview) mit unterschiedlichen Spezifikationen präsentieren oder verschiedene Parameter an die zusammensetzbare Funktion übergeben. Auf diese Weise können Sie den Boilerplate-Code reduzieren, den Sie andernfalls schreiben müssten.

Vorlagen für mehrere Vorschauen

Mit androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ werden API-Vorlagen mit mehreren Vorschauen eingeführt: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark und @PreviewDynamicColors. So können Sie mit einer einzigen Annotation in gängigen Szenarien eine Vorschau der Benutzeroberfläche für das Schreiben aufrufen.

Benutzerdefinierte Anmerkungen für mehrere Vorschauen erstellen

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

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

Sie können diese benutzerdefinierte Annotation für Ihre zusammensetzbaren Funktionen in der Vorschau verwenden:

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

Du kannst mehrere Anmerkungen für mehrere Vorschauen und normale Vorschauanmerkungen kombinieren, um einen umfassenderen Satz an Vorschauen zu erhalten. Wenn Annotationen für die Mehrfachvorschau kombiniert werden, bedeutet das nicht, dass alle verschiedenen Kombinationen angezeigt werden. Stattdessen agiert jede Annotation mit mehreren Vorschauen 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

Dank der Kombinationsmöglichkeiten bei der Mehrfachvorschau und der normalen Vorschau können Sie viele Attribute größerer Projekte umfassender testen.

@Preview und große Datasets

Sehr oft besteht die Notwendigkeit, dass Sie ein großes Dataset an die zusammensetzbare Vorschau übergeben müssen. Übergeben Sie dazu einfach Beispieldaten an eine Funktion für die zusammensetzbare Vorschau, indem Sie einen Parameter mit der Annotation @PreviewParameter 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 gegebenenfalls 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

Beschränkungen und Best Practices

Android Studio führt den Vorschaucode direkt im Vorschaubereich aus. Es muss weder ein Emulator noch ein physisches Gerät ausgeführt werden, da es einen portierten Teil des Android-Frameworks namens Layoutlib nutzt. Layoutlib ist eine benutzerdefinierte Version des Android-Frameworks, das für die Ausführung außerhalb von Android-Geräten entwickelt wurde. Das Ziel der Bibliothek ist es, eine Vorschau eines Layouts in Android Studio bereitzustellen, das dem Rendering auf Geräten sehr nahe kommt.

Einschränkungen für Vorschauen

Aufgrund der Art, wie Vorschauen in Android Studio gerendert werden, sind sie einfach und erfordern nicht das gesamte Android-Framework, um sie zu rendern. Dies birgt jedoch folgende Einschränkungen:

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

Vorschau und ViewModels

Vorschauen sind 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 ViewModel an einer Abhängigkeitsinjektion beteiligt ist (z. B. bei Hilt), kann das Vorschausystem nicht die gesamte Abhängigkeitsgrafik erstellen, um die ViewModel zu erstellen.

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

Warnung: Übergeben Sie die ViewModel-Instanzen nicht an andere zusammensetzbare Funktionen. In diesem Fall koppeln Sie die zusammensetzbaren Funktionen mit dem Typ ViewModel. Dadurch sind sie weniger wiederverwendbar, schwerer zu testen und können nicht als Vorschau angezeigt werden.

Falls Sie sich eine Vorschau einer zusammensetzbaren Funktion anzeigen lassen möchten, in der ein ViewModel verwendet wird, sollten Sie eine weitere zusammensetzbare Funktion erstellen. Dabei werden die Parameter aus ViewModel als Argumente der zusammensetzbaren Funktion übergeben. So müssen Sie keine Vorschau der zusammensetzbaren Funktion anzeigen, die das ViewModel verwendet.

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

Annotationsklasse @Preview

Sie können jederzeit bei gedrückter Strg- oder ⌘-Taste auf die Anmerkung @Preview in Android Studio klicken. So erhalten Sie eine vollständige Liste der Parameter, die beim Anpassen der Vorschau angepasst werden 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

Weitere Informationen

Weitere Informationen dazu, wie Android Studio die Nutzerfreundlichkeit von @Preview fördert, und weitere Tipps zu Tools findest du im Blog Compose Tooling.