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

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

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

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

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

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

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

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

קובץ 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

ריבוע צהוב עם המילים 'שלום'
עולם"

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

אם הפעלתם את ההגדרה דינמית צבע [color] באפליקציה, אפשר להשתמש במאפיין 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

מלבן ירוק עם המילים 'שלום'
עולם"

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

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

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

המשתמש לוחץ על הלחצן 'הפעלת התצוגה המקדימה'

סרטון של המשתמש שפורס תצוגה מקדימה
המכשיר

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

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

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

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

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

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

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

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

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

כשמשתמשים בתכונה 'תצוגה מקדימה בכמה פורמטים', אפשר להגדיר סוג של הערה שכולל בעצמו כמה הערות @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 Framework שתוכננה לפעול מחוץ למכשירי Android. המטרה של הספרייה היא לספק תצוגה מקדימה של פריסה ב-Android Studio שדומה מאוד לעיבוד שלה במכשירים.

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

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

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

תצוגות מקדימות ו-`ViewModels`

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

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

חלונית בעיות ב-Android Studio עם האפשרות ליצור מופע של '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

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

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

מומלץ עבורך

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

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