תוכן קומפוזבילי מוגדר על ידי פונקציה ונוסף לו הערות עם @Composable
:
@Composable fun SimpleComposable() { Text("Hello World") }
כדי להפעיל תצוגה מקדימה של התוכן הקומפוזבילי הזה, צריך ליצור תוכן קומפוזבילי נוסף עם הערות
עם @Composable
ועם @Preview
. התוכן הקומפוזבילי החדש עם הערות מכיל עכשיו
התוכן הקומפוזבילי שיצרתם בהתחלה, SimpleComposable
:
@Preview @Composable fun SimpleComposablePreview() { SimpleComposable() }
ההערה @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") } }
תצוגה מקדימה של צבע דינמי
אם הפעלתם את ההגדרה דינמית,
צבע [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)) }
הגדרת צבע הרקע
כברירת מחדל, התוכן הקומפוזבילי מוצג עם רקע שקוף. כדי להוסיף
רקע, מוסיפים את הפרמטרים showBackground
ו-backgroundColor
. שמירה ב:
חשוב לזכור ש-backgroundColor
הוא ARGB Long
, ולא Color
ערך:
@Preview(showBackground = true, backgroundColor = 0xFF00FF00) @Composable fun WithGreenBackground() { Text("Hello World") }
ממשק משתמש של המערכת
אם אתם רוצים להציג את סרגלי הסטטוס והפעולה בתוך תצוגה מקדימה, הוסיפו את
הפרמטר showSystemUi
:
@Preview(showSystemUi = true) @Composable fun DecoratedComposablePreview() { Text("Hello World") }
![חלון תצוגה מקדימה שבו מוצגת פעילות עם סרגלי הסטטוס והפעולה.](https://developer.android.com/static/develop/ui/compose/images/tooling-decorated-preview.png?authuser=0&hl=he)
מצב ממשק משתמש
הפרמטר 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 מספק תכונות שמאפשרות לך ליצור אינטראקציה עם המודעות שהגדרת תצוגות מקדימות. האינטראקציה הזו עוזרת לך להבין את התצוגות המקדימות התנהגות בסביבת זמן ריצה ומאפשר לכם לנווט בצורה טובה יותר בממשק המשתמש באמצעות תצוגות מקדימות.
מצב אינטראקטיבי
המצב האינטראקטיבי מאפשר לבצע אינטראקציה עם התצוגה המקדימה באופן דומה לזה. במכשיר שבו פועלת התוכנית, כמו טלפון או טאבלט. המצב האינטראקטיבי מבודד בסביבת ארגז חול (כלומר, מבודד מתצוגות מקדימות אחרות), שבו אפשר ללחוץ על רכיבים ולהזין קלט של משתמשים בתצוגה המקדימה. זו הזדמנות דרך לבדוק מצבים שונים, תנועות ואפילו אנימציות של התוכן הקומפוזבילי.
ניווט באמצעות קוד וקווי מתאר קומפוזביליים
אפשר להעביר את העכבר מעל תצוגה מקדימה כדי לראות את קווי המתאר של התכנים הקומפוזביליים הכלולים בטווח. לחיצה על מתאר קומפוזבילי מפעילה את תצוגת העריכה להגדרה שלו.
הפעלת תצוגה מקדימה
אפשר להריץ @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
אפשר להשתמש בהערה המותאמת אישית הזו לתכנים קומפוזביליים בגרסת טרום-השקה (Preview):
@FontScalePreviews @Composable fun HelloWorldPreview() { Text("Hello World") }
אפשר לשלב כמה הערות מרובות של תצוגה מקדימה והערות רגילות בתצוגה מקדימה כדי ליצור קבוצה שלמה יותר של תצוגות מקדימות. שילוב של הערות עם כמה תצוגות מקדימות לא אומר שכל השילובים השונים מוצגים. במקום זאת, כל אחד אנוטציות מסוג Multipreview פועלת באופן עצמאי ומעבדת רק את הווריאציות שלה.
@Preview( name = "Spanish", group = "locale", locale = "es" ) @FontScalePreviews annotation class CombinedPreviews @CombinedPreviews @Composable fun HelloWorldPreview2() { MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } } }
אופי השילוב וההתאמה של ריבוי תצוגה מקדימה-- ותצוגה מקדימה רגילה!-- מאפשר לך לבדוק באופן מקיף מאפיינים רבים של פרויקטים בקנה מידה גדול.
@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") ) }
הפעולה הזו מעבדת תצוגה מקדימה אחת לכל רכיב נתונים ברצף:
אפשר להשתמש באותה מחלקה של ספק כדי ליצור כמה תצוגות מקדימות. במקרה הצורך, מגבילים מספר התצוגות המקדימות על ידי הגדרת פרמטר המגבלה.
@Preview @Composable fun UserProfilePreview2( @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User ) { UserProfile(user) }
מגבלות ושיטות מומלצות
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, )
מקורות מידע נוספים
כדי לקבל מידע נוסף על האופן שבו מערכת Android Studio משפרת את קלות השימוש של @Preview
,
טיפים נוספים בנושא כלים, מומלץ לקרוא את הבלוג כתיבת הודעה
שימוש בכלים.
מומלץ עבורך
- הערה: טקסט הקישור מוצג כאשר JavaScript מושבת
- נתונים בהיקף מקומי באמצעות CompositionLocal
- עיצוב Material 2 ב-Compose
- שימוש בתצוגות מפורטות בהצעות לכתיבה