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

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

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

רכיב טקסט פשוט שמכיל את המילים "Hello

World"

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

@Preview
@Composable
fun SimpleComposablePreview() {
    SimpleComposable()
}

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

קובץ GIF שמציג עדכונים בזמן אמת באמצעות תצוגה מקדימה של ההודעה

אתם יכולים להוסיף פרמטרים באופן ידני בקוד כדי להתאים אישית את האופן שבו Android Studio תיצור את @Preview. אפשר אפילו להוסיף את ההערה @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")
    }
}

ריבוע צהוב עם המילים 'Hello
World'

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

אם הפעלתם את התכונה צבע דינמי באפליקציה, תוכלו להשתמש במאפיין 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))
}

רכיב טקסט פשוט שמכיל את המילה 'שלום' (Bonjour) עם דגל צרפת

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

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

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

מלבן ירוק עם הכיתוב 'Hello World'

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

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

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

חלון תצוגה מקדימה שבו מוצגת פעילות עם סרגל הסטטוס וסרגל הפעולות.

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

הפרמטר 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!")
    }
}

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

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

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

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

המשתמש לוחץ על הלחצן 'אינטראקטיבי' בתצוגה המקדימה

סרטון של המשתמש מבצע אינטראקציה עם תצוגה מקדימה

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

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

המשתמש מעביר את העכבר מעל תצוגה מקדימה, וכתוצאה מכך מוצגים ב-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

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

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

הכרטיסייה 'עיצוב' ב-Android Studio שבה מוצג ה-composable עם גופן קטן וגופן גדול

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

@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 שמציגה את התוכן הקומפוזבילי בכל ההגדרות

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

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

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

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

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

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

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

תצוגות מקדימות של רכיבי ה-Compose של Elise, ‏ Frank ו-Julia

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

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

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

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

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

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

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

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

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

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

חלונית הבעיה ב-Android Studio עם ההודעה &#39;Failed to instantiate a &#39;ViewModel&#39;&#39;

אם רוצים לראות תצוגה מקדימה של רכיב מורכב שמשתמש ב-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,
)

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

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