Benutzeroberfläche mit zusammensetzbaren Vorschauen als Vorschau ansehen

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

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

Ein einfaches Textelement mit den Wörtern „Hallo Welt“

Wenn Sie eine Vorschau dieses Composeables aktivieren möchten, erstellen Sie ein weiteres Composeable, das mit @Composable und @Preview gekennzeichnet ist. Diese neue, mit Anmerkungen versehene zusammensetzbare Funktion enthält jetzt die zuvor erstellte zusammensetzbare Funktion 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. Während Sie Änderungen vornehmen, sehen Sie in der Vorschau Liveaktualisierungen.

Ein GIF, das Echtzeitaktualisierungen mit der Vorschau für das Verfassen von E-Mails zeigt

Sie können Ihrem Code manuell Parameter hinzufügen, um anzupassen, wie Android Studio @Preview rendert. Sie können sogar die Annotation @Preview derselben Funktion mehrmals hinzufügen, um eine zusammensetzbare Funktion mit unterschiedlichen Eigenschaften in der Vorschau anzusehen.

Einer der Hauptvorteile von @Preview-Kompositen besteht darin, dass Sie nicht auf den Emulator in Android Studio angewiesen sind. 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, mit denen sich zusammensetzbare Vorschauen 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 @Preview Pixel für den Umbruch des Inhalts verwendet. 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")
    }
}

Ein gelbes Quadrat mit der Aufschrift „Hallo Welt“

Vorschau für dynamische Farben

Wenn Sie in Ihrer App die dynamische Farbgebung aktiviert haben, können Sie mit dem Attribut wallpaper den Hintergrund wechseln und sehen, wie Ihre Benutzeroberfläche auf den ausgewählten Hintergrund verschiedener Nutzer reagiert. 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 zur Vorabversion bearbeiten, um Konfigurationen für Ihre zusammensetzbaren Funktionen auf verschiedenen Geräten zu definieren.

Beispiel für eine kompostierbare 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.

Durch die Bearbeitung der
Beispielfunktion

Ü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.

Spezifikationsliste

Drücken Sie zum Anwenden Enter oder Esc, um den Vorgang abzubrechen.

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 Überprüfung wird versucht, eine Lösung zu finden, die deiner Eingabe am nächsten kommt.

Beispiel für einen ungültigen Wert

Sprache

Wenn Sie verschiedene Nutzersprachen 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 Composeable 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-Wert Long und kein Color-Wert ist:

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

Ein grünes Rechteck mit den Worten „Hello World“

System-UI

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

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

Ein Vorschaufenster mit einer Aktivität mit Status- und Aktionsleisten.

UI-Modus

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

UI für die Erstellung der Vorschau

LocalInspectionMode

Anhand des 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. Sie können beispielsweise ein Platzhalterbild im Vorschaufenster anzeigen lassen, anstatt echte Daten.

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

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 ähnlich wie auf einem Gerät interagieren, 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 getrennt), in der Sie in der Vorschau auf Elemente klicken und Nutzereingaben eingeben können. So können Sie schnell verschiedene Status, Touch-Gesten und sogar Animationen Ihres Composeables testen.

Wenn der Nutzer auf die
Schaltfläche „interaktiv“ klickt,

Ein Video, in dem der Nutzer mit einer Vorschau interagiert

Codenavigation und zusammensetzbare Überschriften

Sie können den Mauszeiger auf eine Vorschau bewegen, um die Umrisse der darin enthaltenen zusammensetzbaren Funktionen zu sehen. Wenn Sie auf einen zusammensetzbaren Entwurf klicken, wird in der Bearbeitungsansicht die Definition aufgerufen.

Der Nutzer bewegt den Mauszeiger auf eine Vorschau, wodurch in Studio die Umrisse der entsprechenden Composeables angezeigt werden.

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 keinen Boilerplate-Code schreiben, der um eine Berechtigung bittet, wenn diese bereits gewährt wurde.

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

Der Nutzer klickt in der Vorschau auf die Schaltfläche „Vorschau anzeigen“.

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

@Preview kopieren und rendern

Jede gerenderte Vorschau kann durch Klicken mit der rechten Maustaste als Bild kopiert werden.

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

Mehrere Vorschauen derselben @Preview-Anmerkung

Sie können mehrere Versionen derselben zusammensetzbaren Funktion @Preview mit unterschiedlichen Spezifikationen präsentieren oder verschiedene Parameter, die an die zusammensetzbare Funktion übergeben werden. So können Sie den Boilerplate-Code reduzieren, den Sie sonst schreiben müssten.

Vorlagen mit mehreren Vorschaubildern

Mit androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01 und höher werden Multipreview-API-Vorlagen eingeführt: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark und @PreviewDynamicColors. Damit können Sie mit einer einzigen Annotation eine Vorschau der Compose-UI in häufig auftretenden Szenarien sehen.

Mithilfe von Vorlagen eine Vorschau verschiedener Schriftarten und Bildschirmgrößen ansehen

Benutzerdefinierte Anmerkungen für die Multi-Vorschau erstellen

Mit der Multi-Vorschau können Sie eine Anmerkungsklasse definieren, die selbst mehrere @Preview-Anmerkungen mit unterschiedlichen Konfigurationen enthält. Wenn Sie diese Anmerkung zu einer zusammensetzbaren Funktion hinzufügen, werden alle verschiedenen Vorschauen automatisch gleichzeitig gerendert. 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 eine 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

Sie können diese benutzerdefinierte Anmerkung für Ihre Vorschau-Kompositionen verwenden:

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

Android Studio-Designtab mit dem Composeable in kleiner und großer Schrift

Sie können mehrere Anmerkungen für die Multi-Vorschau und normale Vorschau-Anmerkungen kombinieren, um eine umfassendere Auswahl an Vorschauen zu erstellen. Wenn du Anmerkungen für mehrere Vorschauen kombinierst, werden nicht alle Kombinationen angezeigt. Stattdessen funktioniert jede Anmerkung für die Multi-Vorschau 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-Designtab mit dem Composeable in allen Konfigurationen

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

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:

Vorschaubilder mit den Composeable-Assets von 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)
}

Einschränkungen und Best Practices

In Android Studio wird der Vorschaucode direkt im Vorschaubereich ausgeführt. 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, die außerhalb von Android-Geräten ausgeführt werden kann. Das Ziel der Bibliothek ist es, eine Vorschau eines Layouts in Android Studio zu bieten, das dem Rendering auf Geräten sehr nahe kommt.

Einschränkungen der Vorschau

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. Es gelten jedoch die folgenden 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 erstellt werden, die an ViewModel übergeben werden, wie etwa Repositories, Anwendungsfälle oder Manager. Wenn Ihre ViewModel an der Abhängigkeitsinjektion teilnimmt (z. B. mit Hilt), kann das Vorschausystem nicht den gesamten Abhängigkeitsgraphen erstellen, um die ViewModel zu erstellen.

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

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

Wenn Sie eine Vorschau eines Composeables mit einer ViewModel anzeigen möchten, sollten Sie ein weiteres Composeable erstellen, bei dem die Parameter aus ViewModel als Argumente des Composeables übergeben werden. 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)
  }
}

Annotationsklasse @Preview

Sie können in Android Studio jederzeit die Anmerkung @Preview mit Strg oder ⌘ und Klick gedrückt halten, um eine vollständige Liste der Parameter zu erhalten, 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,
)

Weitere Informationen

Weitere Informationen dazu, wie Android Studio die Nutzerfreundlichkeit von @Preview fördert, sowie weitere Tipps zu Tools finden Sie im Blog Compose Tools.