דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

World"

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

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

ההערה @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")
    }
}AndroidStudioComposeSnippets.kt

ריבוע צהוב עם המילים '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))
}AndroidStudioComposeSnippets.kt

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

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

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

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

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

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

אם אתם צריכים להציג את שורת הסטטוס ואת שורת הפעולות בתצוגה המקדימה, מוסיפים את הפרמטר 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 FontScalePreviewsAndroidStudioComposeSnippets.kt

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

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

הכרטיסייה 'עיצוב' ב-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)) } }
}AndroidStudioComposeSnippets.kt

הכרטיסייה 'עיצוב' ב-Android Studio שבה מוצג הרכיב הניתן ליצירה בכל התצורות

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

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

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

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

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

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

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

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

Android Studio מפעיל את הקוד של התצוגות המקדימות ישירות באזור התצוגה המקדימה. לא צריך להפעיל אמולטור או מכשיר פיזי, כי הכלי משתמש בחלק שהועבר של מסגרת 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 עם ההודעה 'Failed to instantiate a 'ViewModel''

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

מומלץ עבורך

הערה: טקסט הקישור מוצג כש-JavaScript מושבת
נתונים ברמת המיקום המקומי באמצעות CompositionLocal
עיצוב Material 2 ב-Compose
שימוש בתצוגות ב'כתיבה'

תצוגה מקדימה של אנימציות וניפוי באגים