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 dieses Composeables aktivieren möchten, erstellen Sie ein weiteres Composeable, das mit @Composable und @Preview gekennzeichnet ist. Dieses neue, kommentierte Composeable enthält jetzt das ursprünglich erstellte Composeable SimpleComposable:

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

Die Anmerkung @Preview teilt Android Studio mit, dass dieses Composeable in der Designansicht dieser Datei angezeigt werden soll. Sie können sich die werden während der Bearbeitung aktualisiert.

Sie können Ihrem Code manuell Parameter hinzufügen, um die Art und Weise anzupassen, wie Android Studio Rendert @Preview. Sie können die Anmerkung @Preview sogar mehrmals derselben Funktion hinzufügen, um eine Vorschau eines Composeables mit verschiedenen Properties zu sehen.

Einer der Hauptvorteile der zusammensetzbaren Funktion von @Preview besteht darin, im Emulator in Android Studio. Sie können das speicherintensive Starten des Emulators für endgültige Änderungen des Erscheinungsbildes speichern und mit @Preview kleine Codeänderungen ganz einfach vornehmen und testen.

Damit Sie die Anmerkung @Preview optimal nutzen können, sollten Sie Ihre Bildschirme in Bezug auf den Status definieren, der als Eingabe empfangen wird, und die Ereignisse, die ausgegeben werden.

@Preview definieren

Android Studio bietet einige Funktionen zur Erweiterung zusammensetzbarer Vorschauen. Sie können das Containerdesign ändern, mit ihnen interagieren oder sie direkt in einem Emulator oder Gerät.

Abmessungen

Standardmäßig werden @Preview-Dimensionen automatisch ausgewählt, um den Inhalt umzubrechen. Wenn Sie die Dimensionen manuell festlegen möchten, fügen Sie die Parameter heightDp und widthDp hinzu. Diese Werte werden bereits als dp interpretiert. Sie müssen ihnen also kein .dp hinzufügen:

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

Vorschau für dynamische Farben

Wenn Sie die Option Dynamische Farbe in Ihrer App verwenden, Verwenden Sie das Attribut wallpaper, um zwischen Hintergründen zu wechseln und zu sehen, wie Ihre Benutzeroberfläche auf unterschiedlichen Nutzenden ausgewählten Hintergrund. Wählen Sie aus den verschiedenen Hintergrundthemen der Klasse Wallpaper aus. 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 Anmerkung „Vorschau“ bearbeiten, um Konfigurationen für Ihre Composeables auf verschiedenen Geräten zu definieren.

Wenn der Geräteparameter einen leeren String (@Preview(device = "")) enthält, können Sie Rufen Sie die automatische Vervollständigung auf, indem Sie Ctrl + Space drücken. Dann können Sie die Werte für jeden Parameter.

Ü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. Wählen Sie dazu spec:width=px,height=px,dpi=int… aus, um die einzelnen Werte der einzelnen Parameter festzulegen.

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

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) > Mit … ersetzen). Bei der Prüfung wird versucht, eine Korrektur vorzunehmen, die Ihrer Eingabe am ehesten entspricht.

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 mit einem transparenten Hintergrund angezeigt. Wenn Sie einen Hintergrund hinzufügen möchten, fügen Sie die Parameter showBackground und backgroundColor hinzu. Behalten backgroundColor ist ein ARGB-Farbraum Long, nicht Color Wert:

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

System-UI

Wenn die Status- und Aktionsleisten in einer Vorschau angezeigt werden sollen, fügen Sie den Parameter showSystemUi-Parameter:

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

UI-Modus

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

LocalInspectionMode

Sie können in der LocalInspectionMode lesen. CompositionLocal, um zu sehen, ob die zusammensetzbare Funktion in einer Vorschau (innerhalb eines Inspectable-Komponente). 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.

Auf diese Weise können Sie auch die Einschränkungen umgehen. Beispielsweise werden Beispieldaten angezeigt, anstatt eine Netzwerkanfrage zu stellen.

@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 Ihren definierten Vorschaubildern interagieren können. So können Sie das Laufzeitverhalten Ihrer Vorschauversionen besser nachvollziehen und sich mithilfe der Vorschauversionen leichter auf der Benutzeroberfläche zurechtfinden.

Interaktiver Modus

Im interaktiven Modus können Sie mit einer Vorschau auf ähnliche Weise interagieren wie auf einem Gerät, auf dem dein Programm läuft, z. B. einem Smartphone oder Tablet. Im interaktiven Modus in einer Sandbox-Umgebung isoliert ist (d. h. von anderen Vorschauen getrennt), in der Sie auf Elemente klicken und Nutzereingaben in die Vorschau eingeben können. So können Sie schnell verschiedene Status, Touch-Gesten und sogar Animationen Ihres Composeables testen.

Codenavigation und zusammensetzbare Überschriften

Wenn Sie den Mauszeiger auf eine Vorschau bewegen, werden die Umrisse der darin enthaltenen Composeables angezeigt. Wenn Sie auf einen zusammensetzbaren Entwurf klicken, wird in der Bearbeitungsansicht die Definition aufgerufen.

Vorschau anzeigen

Sie können eine bestimmte @Preview auf einem Emulator oder einem physischen Gerät ausführen. Die Vorschau wird in derselben Projekt-App wie eine neue Activity bereitgestellt und hat daher denselben Kontext und dieselben Berechtigungen. Sie müssen keine Boilerplate-Code, der um eine Berechtigung bittet, falls diese bereits gewährt wurde.

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

@Preview-Renderung 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 präsentieren mit oder unterschiedliche Parameter, die an die zusammensetzbare Funktion übergeben werden. So können Sie den Boilerplate-Code reduzieren, den Sie sonst schreiben müssten.

Vorlagen für die Multivorschau

androidx.compose.ui:ui-tooling-preview Mit Version 1.6.0-alpha01 und höher werden Multi-Preview-API-Vorlagen eingeführt: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark und @PreviewDynamicColors. So können Sie mit einer einzigen Anmerkung eine Vorschau Ihrer Compose-Benutzeroberfläche in gängigen Szenarien anzeigen.

Benutzerdefinierte Multipreview-Anmerkungen erstellen

Mit der Multi-Vorschau können Sie eine Anmerkungsklasse definieren, die selbst mehrere @Preview-Anmerkungen mit unterschiedlichen Konfigurationen enthält. Anmerkung hinzufügen zu rendert eine zusammensetzbare Funktion automatisch alle Vorschauen einmal. So können Sie beispielsweise eine Vorschau für mehrere Geräte, Schriftgrößen oder Themen gleichzeitig anzeigen lassen, ohne diese Definitionen für jedes einzelne Composeable wiederholen zu müssen.

Erstellen Sie zuerst Ihre eigene benutzerdefinierte Anmerkungsklasse:

@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 Anmerkung für Ihre Vorschau-Kompositionen verwenden:

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

Sie können mehrere Anmerkungen der Mehrfachvorschau und der normalen Vorschauanmerkungen kombinieren. um einen umfassenderen Satz von Vorschauen zu erhalten. Wenn du Anmerkungen für mehrere Vorschauen kombinierst, werden nicht alle Kombinationen angezeigt. Stattdessen werden alle Multipreview-Anmerkungen agiert unabhängig voneinander 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

Da Sie die Vorschau in mehreren Größen und die normale Vorschau kombinieren können, lassen sich viele Eigenschaften von Projekten im größeren Maßstab umfassender testen.

@Preview und große Datenmengen

Sehr oft müssen Sie einen großen Datensatz an Ihre Preview für zusammensetzbare Daten übergeben. Dazu übergeben Sie einfach Beispieldaten an eine Funktion für die zusammensetzbare Vorschau, indem Sie einen Parameter mit der Anmerkung @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 und gibt den Fehlerwert als Folge von Beispieldaten an.

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 Anzahl der Vorschauen, indem Sie den Parameter limit festlegen.

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

Einschränkungen und Best Practices

In Android Studio wird der Vorschaucode direkt im Vorschaubereich ausgeführt. Nicht einen Emulator oder ein physisches Gerät ausführen, Teil des Android-Frameworks namens Layoutlib. Layoutlib ist benutzerdefiniert Version des Android-Frameworks, das für die Ausführung außerhalb von Android-Geräten entwickelt wurde. Die Ziel der Bibliothek ist es, eine Vorschau eines Layouts in Android Studio zu bieten, dem Rendering auf Geräten sehr nahe.

Einschränkungen für Vorschauen

Aufgrund der Art und Weise, wie Vorschauen in Android Studio gerendert werden, sind sie effizient und zum Rendern ist nicht das gesamte Android-Framework erforderlich. Dies hat jedoch folgende Einschränkungen:

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

Vorschauen und ViewModels

Bei der Verwendung von ViewModel in einem Composeable sind Vorschauen eingeschränkt. Im Vorschausystem können nicht alle Parameter, die an ein ViewModel übergeben werden, wie Repositories, Anwendungsfälle, Administratoren, oder Ähnliches. Wenn dein ViewModel an der Abhängigkeitsinjektion beteiligt ist (z. B. wie bei Hilt), kann das Vorschausystem nicht die gesamte Abhängigkeit Diagramm, um das ViewModel zu erstellen.

Wenn Sie versuchen, sich eine zusammensetzbare Funktion mit ViewModel in der Vorschau anzusehen, wird in Android Studio eine Fehler beim Rendern der zusammensetzbaren Funktion:

Wenn Sie eine Vorschau einer zusammensetzbaren Funktion mit ViewModel ansehen möchten, erstellen Sie weitere zusammensetzbare Funktion mit den Parametern aus ViewModel, die als Argumente von der zusammensetzbaren Funktion. So müssen Sie keine Vorschau des Composeables mit der ViewModel aufrufen.

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

Anmerkungsklasse @Preview

Du kannst jederzeit „Strg“ oder „⌘ + Klick“ drücken die Anmerkung @Preview in Android Studio an. Dort finden Sie eine vollständige Liste der Parameter, die Sie beim Anpassen Ihres in der Vorschau ansehen.

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

Wenn du mehr darüber erfahren möchtest, wie Android Studio die Nutzerfreundlichkeit von @Preview fördert, Weitere Tool-Tipps finden Sie im Blog Compose Tools.