תצוגה מקדימה של ממשק המשתמש עם תצוגות מקדימות קומפוזביליות

פונקציה הניתנת להגדרה מוגדרת על ידי פונקציה ומסומנת ב-@Composable:

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

כדי להפעיל תצוגה מקדימה של ה-Composeable הזה, יוצרים Composeable נוסף ומוסיפים לו הערות באמצעות @Composable ו-@Preview. קובץ ה-Compose החדש עם ההערות מכיל עכשיו את קובץ ה-Compose שיצרתם בהתחלה, SimpleComposable:

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

ההערה @Preview מנחה את Android Studio שצריך להציג את התוכן הקומפוזבילי בתצוגת העיצוב של הקובץ. אתם יכולים לראות את העדכונים בזמן אמת בתצוגה המקדימה של הרכיבים בזמן שאתם עורכים אותם.

אפשר להוסיף פרמטרים באופן ידני לקוד כדי להתאים אישית את האופן שבו @Preview מעבד ב-Android Studio. אפשר גם להוסיף את ההערה @Preview לאותה פונקציה כמה פעמים כדי לראות תצוגה מקדימה של רכיב מורכב עם מאפיינים שונים.

אחד מהיתרונות העיקריים של שימוש ברכיבים הניתנים לקישור מסוג @Preview הוא הימנעות מהתלות באמולטור ב-Android Studio. אתם יכולים לחסוך את ההפעלה של הסימולטור, שדורשת הרבה זיכרון, בשביל שינויים סופיים יותר במראה ובתחושה, ולהשתמש ביכולת של @Preview לבצע ולבדוק בקלות שינויים קטנים בקוד.

כדי להשתמש באנוטציות של @Preview בצורה היעילה ביותר, חשוב להגדיר את המסכים שלכם מבחינת המצב שהיא מקבלת כקלט והאירועים שהיא מקבלת כפלט.

הגדרת @Preview

ב-Android Studio יש כמה תכונות להרחבת תצוגות מקדימות שניתנות ליצירה. אפשר לשנות את עיצוב הקונטיינרים, לבצע איתם אינטראקציה או לפרוס אותם ישירות במהדמה או במכשיר.

מידות

כברירת מחדל, המאפיינים @Preview נבחרים באופן אוטומטי כדי לעטוף את התוכן שלהם. כדי להגדיר את המאפיינים באופן ידני, מוסיפים את הפרמטרים heightDp ו-widthDp. הערכים האלה כבר מפורשים כ-dp, כך שאין צורך להוסיף .dp אליהם:

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

תצוגה מקדימה של צבע דינמי

אם הפעלתם צבע דינמי באפליקציה, תוכלו להשתמש במאפיין wallpaper כדי להחליף טפטים ולראות איך ממשק המשתמש מגיב לטפט שנבחר על ידי משתמשים שונים. בוחרים מתוך עיצובי הטפטים השונים שמוצעים על ידי המחלקה Wallpaper. כדי להשתמש בתכונה הזו צריך Compose בגרסה 1.4.0 ואילך.

שימוש במכשירים שונים

ב-Android Studio Flamingo, אפשר לערוך את הפרמטר device של ההערה Preview כדי להגדיר הגדרות ל-composables במכשירים שונים.

כשפרמטר המכשיר מכיל מחרוזת ריקה (@Preview(device = "")), אפשר להפעיל את ההשלמה האוטומטית בלחיצה על Ctrl + Space. לאחר מכן תוכלו להגדיר את הערכים של כל פרמטר.

בתכונה 'השלמה אוטומטית', אפשר לבחור כל אפשרות של מכשיר מהרשימה – לדוגמה, @Preview(device = "id:pixel_4"). לחלופין, אפשר להזין מכשיר מותאם אישית על ידי בחירה באפשרות spec:width=px,height=px,dpi=int… כדי להגדיר את הערכים הנפרדים של כל פרמטר.

כדי להחיל את השינויים, מקישים על Enter. כדי לבטל, מקישים על Esc.

אם מגדירים ערך לא חוקי, ההצהרה תודגש בקו אדום ויכול להיות שיהיה תיקון זמין (Alt + Enter (‏⌥ + ⏎ ב-macOS) > החלפה ב-…. הבדיקה תנסה לספק תיקון שהכי קרוב לקלט שלכם.

שפה ואזור

כדי לבדוק אזורי זמן שונים של משתמשים, מוסיפים את הפרמטר locale:

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

הגדרת צבע הרקע

כברירת מחדל, הרכיב המודפס מוצג עם רקע שקוף. כדי להוסיף רקע, צריך להוסיף את הפרמטרים showBackground ו-backgroundColor. חשוב לזכור ש-backgroundColor הוא ערך ARGB Long, ולא ערך Color:

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

ממשק משתמש של המערכת

אם רוצים להציג את סרגלי הסטטוס והפעולה בתצוגה המקדימה, מוסיפים את הפרמטר showSystemUi:

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

מצב ממשק המשתמש

הפרמטר uiMode יכול לקבל כל אחת מהקבועות Configuration.UI_*, ומאפשר לשנות את ההתנהגות של התצוגה המקדימה בהתאם. לדוגמה, אפשר להגדיר את התצוגה המקדימה למצב לילה כדי לראות איך העיצוב מגיב.

LocalInspectionMode

אפשר לקרוא מה-LocalInspectionMode CompositionLocal כדי לראות אם הרכיב הניתן ליצירה עבר עיבוד בתצוגה מקדימה (בתוך רכיב שניתן לבדיקה). אם הקומפוזיציה עוברת עיבוד בקטע מקדים, הערך של LocalInspectionMode.current הוא true. המידע הזה מאפשר לכם להתאים אישית את התצוגה המקדימה. לדוגמה, תוכלו להציג תמונה של placeholder בחלון התצוגה המקדימה במקום להציג נתונים אמיתיים.

כך תוכלו גם לעקוף את המגבלות. לדוגמה, הצגת נתונים לדוגמה במקום להפעיל בקשת רשת.

@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

אינטראקציה עם @Preview

ב-Android Studio יש תכונות שמאפשרות לכם לנהל אינטראקציה עם התצוגות המקדימות שהוגדרו. בעזרת האינטראקציה הזו תוכלו להבין את ההתנהגות של התצוגות המקדימות בזמן הריצה, ותוכלו לנווט טוב יותר בממשק המשתמש בעזרת תצוגות מקדימות.

מצב אינטראקטיבי

במצב האינטראקטיבי אפשר לבצע אינטראקציה עם התצוגה המקדימה, בדומה לאופן שבו עושים את זה במכשיר שבו פועלת התוכנית, כמו טלפון או טאבלט. המצב האינטראקטיבי מבודד בסביבת חול (כלומר, מבודד מתצוגות מקדימות אחרות), שבה אפשר ללחוץ על רכיבים ולהזין קלט של משתמשים בתצוגה המקדימה. זוהי דרך מהירה לבדוק מצבים, תנועות ואפילו אנימציות שונות של הרכיב הניתן לקישור.

ניווט בקוד ותכנון קווים כלליים שניתן לשנות

אפשר להעביר את העכבר מעל התצוגה המקדימה כדי לראות את קווי המתאר של הרכיבים הניתנים לקישור שמכילים את התצוגה המקדימה. לחיצה על מתאר קומפוזבילי מפעילה את תצוגת העריכה כדי לעבור להגדרה שלו.

הפעלת תצוגה מקדימה

אפשר להריץ @Preview ספציפי במה emultor או במכשיר פיזי. התצוגה המקדימה נפרסת באותה אפליקציית פרויקט בתור Activity חדש, כך שהיא חולקת את אותו הקשר והרשאות. לא צריך לכתוב קוד סטנדרטי לבקשת הרשאה אם היא כבר ניתנה.

לוחצים על הסמל הפעלת תצוגה מקדימה לצד ההערה @Preview או בחלק העליון של התצוגה המקדימה, ו-Android Studio פורסת את @Preview במכשיר או במהדמטור המחובר.

העתקת הרינדור של @Preview

אפשר להעתיק כל תצוגה מקדימה שעברה רינדור כתמונה בלחיצה ימנית עליה.

מספר תצוגות מקדימות של אותה הערה ב-@Preview

אפשר להציג כמה גרסאות של אותו תוכן קומפוזבילי עם @Preview עם מפרטים שונים, או להעביר פרמטרים שונים לתוכן הקומפוזבילי. כך תוכלו לצמצם את הקוד הסטנדרטי שתצטרכו לכתוב אחרת.

תבניות עם תצוגה מקדימה של כמה פריטים

androidx.compose.ui:ui-tooling-preview בגרסה 1.6.0-alpha01 ואילך נוספו תבניות API של תצוגה מקדימה בכמה סביבות: @PreviewScreenSizes,‏ @PreviewFontScales,‏ @PreviewLightDark ו-@PreviewDynamicColors. כך, באמצעות הערה אחת תוכלו לראות תצוגה מקדימה של ממשק המשתמש של Compose בתרחישים נפוצים.

יצירת הערות מותאמות אישית עם כמה תצוגות מקדימות

בעזרת התכונה 'תצוגה מקדימה' אפשר להגדיר מחלקה של הערות שיש לה כמה הערות @Preview בהגדרות שונות. הוספת ההערה הזו לפונקציה שניתנת ליצירה מאפשרת ליצור באופן אוטומטי את כל התצוגות המקדימות השונות בבת אחת. לדוגמה, אפשר להשתמש בהערה הזו כדי לראות תצוגה מקדימה של כמה מכשירים, גדלים של גופנים או עיצובים בו-זמנית, בלי לחזור על ההגדרות האלה לכל תוכן קומפוזבילי אחד.

כדי להתחיל, יוצרים מחלקה של הערות מותאמות אישית משלכם:

@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

אפשר להשתמש בהערה המותאמת אישית הזו לרכיבי ה-Composables בתצוגה המקדימה:

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

תוכלו לשלב כמה הערות מרובות של תצוגה מקדימה והערות רגילות בתצוגה מקדימה כדי ליצור קבוצה שלמה יותר של תצוגות מקדימות. שילוב של הערות עם תצוגה מקדימה לא בהכרח מעיד על כך שכל השילובים השונים מוצגים. במקום זאת, כל הערה של תצוגה מקדימה בכמה גרסאות פועלת בנפרד ומרינדרת רק את הווריאנטים שלה.

@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

היכולת לשלב בין תצוגות מקדימות מרובות – ותצוגות מקדימות רגילות! – מאפשרת לבדוק בצורה מקיפה יותר מאפיינים רבים של פרויקטים בקנה מידה גדול יותר.

@Preview וקבוצות נתונים גדולות

לעיתים קרובות יש צורך להעביר מערך נתונים גדול לתצוגה המקדימה הניתנת ליצירה. לשם כך, פשוט מעבירים את הנתונים לדוגמה לפונקציה של תצוגה מקדימה קומפוזבילית על ידי הוספת פרמטר עם ההערה @PreviewParameter.

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

כדי לספק את נתוני הדוגמה, יוצרים כיתה שמטמיעה את PreviewParameterProvider ומחזירה את נתוני הדוגמה כרצף.

class UserPreviewParameterProvider : PreviewParameterProvider<User> {
    override val values = sequenceOf(
        User("Elise"),
        User("Frank"),
        User("Julia")
    )
}
AndroidStudioComposeSnippets.kt

כך נוצרת תצוגה מקדימה אחת לכל רכיב נתונים ברצף:

אפשר להשתמש באותה סוג ספק בכמה תצוגות מקדימות. אם צריך, כדאי להגביל את מספר התצוגות המקדימות על ידי הגדרת פרמטר המגבלה.

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

מגבלות ושיטות מומלצות

Android Studio מפעיל את הקוד של התצוגה המקדימה ישירות באזור התצוגה המקדימה. לא נדרשת הפעלה של אמולטור או מכשיר פיזי, כי הוא משתמש בחלק שנויד מ-framework של Android בשם Layoutlib. Layoutlib היא גרסה מותאמת אישית של מסגרת Android שמיועדת לפעול מחוץ למכשירי Android. מטרת הספרייה היא לספק תצוגה מקדימה של הפריסה ב-Android Studio שקרובה מאוד לרינדור שלה במכשירים.

מגבלות על תצוגות מקדימות

בגלל האופן שבו התצוגות המקדימות נעשות ב-Android Studio, הן קלילות ולא נדרשת להן כל מסגרת Android כדי ליצור אותן. עם זאת, יש לכך מגבלות:

• אין גישה לרשת
• אין גישה לקבצים
• יכול להיות שחלק מממשקי ה-API של Context לא יהיו זמינים במלואם

קטעים מקדימים ו-ViewModels

התצוגה המקדימה מוגבלת כשמשתמשים ב-ViewModel בתוך קומפוזיציה. מערכת התצוגות המקדימות לא יכולה ליצור את כל הפרמטרים המועברים ל-ViewModel, כמו מאגרים, תרחישי שימוש, מנהלי חשבונות או פריטים דומים. בנוסף, אם ה-ViewModel משתתף בהזרקת יחסי תלות (כמו ב-Hilt), מערכת התצוגות המקדימות לא יכולה ליצור את תרשים יחסי התלות כולו כדי ליצור את ה-ViewModel.

אם תנסו לצפות בתצוגה מקדימה של תוכן קומפוזבילי באמצעות ViewModel, מערכת Android Studio תציג שגיאה במהלך הרינדור של התוכן הקומפוזבילי הספציפי:

אם רוצים לראות תצוגה מקדימה של רכיב מורכב שמשתמש ב-ViewModel, צריך ליצור רכיב מורכב אחר עם הפרמטרים מ-ViewModel שמועברים כארגומנטים של הרכיב המורכב. כך לא תצטרכו להציג תצוגה מקדימה של הרכיב הניתן לקישור שמשתמש ב-ViewModel.

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

סיווג ההערה @Preview

תמיד אפשר ללחוץ על ההערה @Preview ב-Android Studio עם Ctrl או ⌘ + לחיצה כדי לראות רשימה מלאה של הפרמטרים שאפשר לשנות כשמתאימים אישית את התצוגה המקדימה.

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

מקורות מידע נוספים

בבלוג Compose Tooling תוכלו לקרוא מידע נוסף על האופן שבו Android Studio מקדם את קלות השימוש ב-@Preview, ותוכלו למצוא בו טיפים נוספים לשימוש בכלים.