Eine zusammensetzbare Funktion wird durch eine Funktion definiert und mit @Composable annotiert:
@Composable
fun SimpleComposable() {
Text("Hello World")
}
Erstellen Sie eine weitere zusammensetzbare Funktion, die mit @Composable und @Preview annotiert ist, um eine Vorschau dieser zusammensetzbaren Funktion zu aktivieren. 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 an der zusammensetzbaren Vorschau vornehmen, werden diese in Echtzeit aktualisiert.
Sie können Ihrem Code manuell Parameter hinzufügen, um anzupassen, wie Android Studio @Preview rendert. Sie können sogar die Anmerkung @Preview derselben Funktion mehrmals hinzufügen, um eine zusammensetzbare Funktion mit unterschiedlichen Eigenschaften in der Vorschau anzuzeigen.
Einer der Hauptvorteile der Verwendung von zusammensetzbaren @Preview-Funktionen besteht darin, die Abhängigkeit vom Emulator in Android Studio zu vermeiden. Sie können sich den arbeitsspeicherintensiven Start des Emulators ersparen, um noch abschließende Designänderungen zu erhalten. Außerdem können Sie mit @Preview mühelos kleine Codeänderungen vornehmen und testen.
Damit Sie die Annotation @Preview am effektivsten nutzen können, müssen Sie Ihre Bildschirme in Bezug auf den Status definieren, den sie als Eingabe empfängt, und die Ereignisse, die sie ausgegeben haben.
@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 bereitstellen.
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. Da diese Werte bereits als dp interpretiert werden, musst du ihnen .dp nicht hinzufügen:
@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
Box(Modifier.background(Color.Yellow)) {
Text("Hello World")
}
}
Dynamische Farbvorschau
Wenn du in deiner App dynamische Farben aktiviert hast, kannst du mit dem Attribut wallpaper zwischen Hintergründen wechseln und sehen, wie deine UI auf den von Nutzern ausgewählten Hintergrund reagiert. Wählen Sie aus den verschiedenen Hintergrunddesigns 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.
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.
Bei der automatischen 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 individuellen Werte jedes Parameters 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) > Ersetzen durch ...). Bei der Überprüfung wird versucht, eine Lösung zu finden, 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))
}
Hintergrundfarbe festlegen
Standardmäßig wird die zusammensetzbare Funktion mit einem transparenten Hintergrund angezeigt. Fügen Sie die Parameter showBackground und backgroundColor hinzu, um einen Hintergrund hinzuzufügen. backgroundColor ist ein ARGB-Wert Long und kein Color-Wert:
@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
Text("Hello World")
}
System-UI
Wenn die Status- und Aktionsleisten in einer Vorschau angezeigt werden sollen, fügen Sie den Parameter showSystemUi hinzu:
@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
Text("Hello World")
}
UI-Modus
Der Parameter uiMode kann jede der Configuration.UI_*-Konstanten annehmen und ermöglicht es Ihnen, 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.
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. Mit diesen Informationen können Sie die Vorschau anpassen. So können Sie beispielsweise ein Platzhalterbild im Vorschaufenster anzeigen lassen, anstatt echte Daten anzuzeigen.
Auf diese Weise können Sie auch die Einschränkungen umgehen. Beispiel: Anzeigen von Beispieldaten anstelle des Aufrufs einer Netzwerkanfrage.
@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 Vorschauen interagieren können. Diese Interaktion hilft Ihnen, das Laufzeitverhalten der Vorschauen zu verstehen und mit Vorschauen in der UI besser 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. auf einem Smartphone oder Tablet. Der interaktive Modus ist in einer Sandbox-Umgebung isoliert (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 Zustände, 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 darin enthaltenen zusammensetzbaren Funktionen zu sehen. Wenn Sie auf eine zusammensetzbare Struktur klicken, wird in der Editoransicht die zugehörige Definition aufgerufen.
Vorschau anzeigen
Du kannst eine bestimmte @Preview auf einem Emulator oder einem physischen Gerät ausführen. Die Vorschau wird in derselben Projektanwendung 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 
. Android Studio stellt diese @Preview dann auf Ihrem verbundenen Gerät oder Ihrem Emulator bereit.
@Preview kopieren und rendern
Jede gerenderte Vorschau kann durch einen Rechtsklick als Bild kopiert werden.
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. Auf diese Weise können Sie den Boilerplate-Code reduzieren, den Sie andernfalls schreiben müssten.
Vorlagen für die Multivorschau
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 sich mit einer einzigen Annotation in gängigen Szenarien eine Vorschau der Compose-UI ansehen.
Benutzerdefinierte Multipreview-Anmerkungen 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 alle Vorschauen automatisch gleichzeitig gerendert. Sie können diese Annotation beispielsweise verwenden, um mehrere Geräte, Schriftgrößen oder Designs gleichzeitig in der Vorschau anzusehen, ohne diese Definitionen für jede einzelne zusammensetzbare Funktion zu wiederholen.
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
Sie können diese benutzerdefinierte Anmerkung für zusammensetzbare Vorschauen verwenden:
@FontScalePreviews
@Composable
fun HelloWorldPreview() {
Text("Hello World")
}
Sie können mehrere Multipreview-Anmerkungen und normale Vorschauannotationen kombinieren, um einen umfassenderen Satz von Vorschauen zu erhalten. Wenn mehrere Annotationen kombiniert werden, bedeutet das nicht, dass alle möglichen Kombinationen angezeigt werden. Stattdessen agiert jede Annotation mit mehreren Vorschauen 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)) } }
}
Durch die Kombination der Mehrfachvorschau und der normalen Vorschau können Sie viele Attribute größerer Projekte umfassender testen.
@Preview und große Datensätze
Sehr oft besteht die Notwendigkeit, ein großes Dataset an die zusammensetzbare Vorabversion zu übergeben. Dazu übergeben Sie einfach Beispieldaten an eine zusammensetzbare 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 angezeigt:
Sie können dieselbe Anbieterklasse für mehrere Vorschauen verwenden. Schränken Sie bei Bedarf die Anzahl der Vorschauen ein, indem Sie den Parameter "limit" festlegen.
@Preview
@Composable
fun UserProfilePreview2(
@PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
UserProfile(user)
}
Einschrä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, die 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 zu bieten, 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 kompakt und erfordern nicht das gesamte Android-Framework, um sie zu rendern. Dies hat jedoch folgende Einschränkungen:
- Kein Netzwerkzugriff
- Kein Dateizugriff
- Einige
ContextAPIs sind möglicherweise nicht vollständig verfügbar
Vorschauen und ViewModels
Vorschauen sind eingeschränkt, wenn ViewModel in einer zusammensetzbaren Funktion verwendet wird. Im Vorschausystem können nicht alle Parameter erstellt werden, die an ViewModel übergeben werden, wie etwa Repositories, Anwendungsfälle oder Manager. Wenn ViewModel an der Abhängigkeitsinjektion beteiligt ist (z. B. bei Hilt), kann das Vorschausystem nicht das gesamte Abhängigkeitsdiagramm zum Erstellen des ViewModel erstellen.
Wenn Sie versuchen, eine zusammensetzbare Funktion mit ViewModel in der Vorschau anzusehen, zeigt Android Studio beim Rendern der entsprechenden zusammensetzbaren Funktion einen Fehler an:
Wenn Sie eine zusammensetzbare Funktion als Vorschau ansehen möchten, in der ViewModel verwendet wird, erstellen Sie eine weitere zusammensetzbare Funktion, bei der die Parameter aus ViewModel als Argumente der zusammensetzbaren Funktion übergeben werden. So müssen Sie keine Vorschau der zusammensetzbaren Funktion ansehen, in der ViewModel verwendet wird.
@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,
)
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 Tools.
Empfehlungen für dich
- Hinweis: Der Linktext wird angezeigt, wenn JavaScript deaktiviert ist.
- Daten auf lokaler Ebene mit CompositionLocal
- Material Design 2 in Compose
- Ansichten in „Compose“ verwenden