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

תוכן קומפוזבילי מוגדר על ידי פונקציה ונוסף לו הערות עם @Composable:

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

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

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

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

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

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

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

כשפרמטר המכשיר מכיל מחרוזת ריקה (@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 ספציפי באמולטור או במכשיר פיזי. התצוגה המקדימה פרוסה באותה אפליקציית פרויקט כמו 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 FontScalePreviews
AndroidStudioComposeSnippets.kt

אפשר להשתמש בהערה המותאמת אישית הזו לתכנים קומפוזביליים בגרסת טרום-השקה (Preview):

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

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

@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 Framework שתוכננה לפעול מחוץ למכשירי 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

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

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