פונקציה הניתנת להגדרה מוגדרת על ידי פונקציה ומסומנת ב-@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
בכיתה. כדי להשתמש בתכונה הזו צריך 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)) }
הגדרת צבע הרקע
כברירת מחדל, הרכיב המודפס מוצג עם רקע שקוף. כדי להוסיף
רקע, מוסיפים את הפרמטרים 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") }
מצב ממשק המשתמש
הפרמטר 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
אפשר להשתמש בהערה המותאמת אישית הזו לרכיבי ה-Composables בתצוגה המקדימה:
@FontScalePreviews @Composable fun HelloWorldPreview() { Text("Hello World") }
אפשר לשלב כמה הערות מרובות של תצוגה מקדימה והערות רגילות בתצוגה מקדימה כדי ליצור קבוצה שלמה יותר של תצוגות מקדימות. שילוב של הערות עם כמה תצוגות מקדימות לא אומר שכל השילובים השונים מוצגים. במקום זאת, כל הערה של תצוגה מקדימה בכמה גרסאות פועלת בנפרד ומרינדרת רק את הווריאציות שלה.
@Preview( name = "Spanish", group = "locale", locale = "es" ) @FontScalePreviews annotation class CombinedPreviews @CombinedPreviews @Composable fun HelloWorldPreview2() { MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } } }
היכולת לשלב בין תצוגות מקדימות מרובות – ותצוגות מקדימות רגילות! – מאפשרת לבדוק בצורה מקיפה יותר מאפיינים רבים של פרויקטים בקנה מידה גדול יותר.
@Preview
וקבוצות נתונים גדולות
לעיתים קרובות נוצר צורך שבו צריך להעביר מערך נתונים גדול לתוכן הקומפוזבילי
תצוגה מקדימה. כדי לעשות זאת, פשוט מעבירים נתונים לדוגמה לפונקציית Composable 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") ) }
כך נוצרת תצוגה מקדימה אחת לכל רכיב נתונים ברצף:
אפשר להשתמש באותה סוג ספק בכמה תצוגות מקדימות. אם צריך, אפשר להגביל את מספר התצוגות המקדימות על ידי הגדרת הפרמטר limit.
@Preview @Composable fun UserProfilePreview2( @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User ) { UserProfile(user) }
מגבלות ושיטות מומלצות
Android Studio מפעיל את הקוד של התצוגה המקדימה ישירות באזור של התצוגה המקדימה. לא צריך להפעיל אמולטור או מכשיר פיזי, כי הכלי משתמש בחלק שהועבר של מסגרת 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
תמיד אפשר ללחוץ על ההערה @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, )
מקורות מידע נוספים
כדי לקבל מידע נוסף על האופן שבו מערכת Android Studio משפרת את קלות השימוש של @Preview
,
טיפים נוספים בנושא כלים, מומלץ לקרוא את הבלוג כתיבת הודעה
שימוש בכלים.
מומלץ עבורך
- הערה: טקסט הקישור מוצג כאשר JavaScript מושבת
- נתונים ברמת המיקום המקומי באמצעות CompositionLocal
- עיצוב Material 2 ב-Compose
- שימוש בתצוגות ב'כתיבה'