פונקציה הניתנת להגדרה מוגדרת על ידי פונקציה ומסומנת ב-@Composable
:
@Composable fun SimpleComposable() { Text("Hello World") }
כדי להפעיל תצוגה מקדימה של ה-Composeable הזה, יוצרים Composeable נוסף ומוסיפים לו הערות באמצעות @Composable
ו-@Preview
. קובץ ה-Compose החדש עם ההערות מכיל עכשיו את קובץ ה-Compose שיצרתם בהתחלה, SimpleComposable
:
@Preview @Composable fun SimpleComposablePreview() { SimpleComposable() }
ההערה @Preview
מורה ל-Android Studio שצריך להציג את ה-composable הזה בתצוגת העיצוב של הקובץ. אפשר לראות עדכונים בזמן אמת בתצוגה המקדימה הקומפוזבילית בזמן העריכה.
אתם יכולים להוסיף פרמטרים באופן ידני בקוד כדי להתאים אישית את האופן שבו 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") } }
תצוגה מקדימה של צבע דינמי
אם הפעלתם את התכונה צבע דינמי באפליקציה, תוכלו להשתמש במאפיין 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
ספציפי במה 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 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
וקבוצות נתונים גדולות
לעיתים קרובות יש צורך להעביר מערך נתונים גדול לתצוגה המקדימה הניתנת ליצירה. לשם כך, פשוט מעבירים את הנתונים לדוגמה לפונקציה של תצוגה מקדימה קומפוזבילית על ידי הוספת פרמטר עם ההערה @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 מפעיל את הקוד של התצוגה המקדימה ישירות באזור של התצוגה המקדימה. לא נדרשת הפעלה של אמולטור או מכשיר פיזי, כי הוא משתמש בחלק שנויד מ-framework של Android בשם Layoutlib
. Layoutlib
היא גרסה מותאמת אישית של מסגרת Android שמיועדת לפעול מחוץ למכשירי Android. המטרה של הספרייה היא לספק תצוגה מקדימה של פריסה ב-Android Studio שדומה מאוד לעיבוד שלה במכשירים.
מגבלות על תצוגות מקדימות
בגלל האופן שבו התצוגות המקדימות נעשות ב-Android Studio, הן קלילות ולא נדרשת להן כל מסגרת Android כדי ליצור אותן. עם זאת, יש לכך מגבלות:
- אין גישה לרשת
- אין גישה לקבצים
- יכול להיות שחלק מממשקי ה-API של
Context
לא יהיו זמינים במלואם
קטעים מקדימים ו-ViewModels
התצוגה המקדימה מוגבלת כשמשתמשים ב-ViewModel
בתוך קומפוזיציה. מערכת התצוגה המקדימה לא יכולה ליצור את כל הפרמטרים שמועברים ל-ViewModel
, כמו מאגרים, תרחישים לדוגמה, מנהלים ועוד. בנוסף, אם ה-ViewModel
משתתף בהזרקת יחסי תלות (כמו ב-Hilt), מערכת התצוגות המקדימות לא יכולה ליצור את תרשים יחסי התלות כולו כדי ליצור את ה-ViewModel
.
כשמנסים להציג תצוגה מקדימה של רכיב composable באמצעות ViewModel
, ב-Android Studio מוצגת שגיאה בזמן היצירה של רכיב ה-composable הספציפי:
אם רוצים לראות תצוגה מקדימה של רכיב מורכב שמשתמש ב-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, )
מקורות מידע נוספים
בבלוג Compose Tooling תוכלו לקרוא מידע נוסף על האופן שבו Android Studio מקדם את קלות השימוש ב-@Preview
, ותוכלו למצוא בו טיפים נוספים לשימוש בכלים.
מומלץ עבורך
- הערה: טקסט הקישור מוצג כש-JavaScript מושבת
- נתונים ברמת המיקום המקומי באמצעות CompositionLocal
- עיצוב Material 2 ב-Compose
- שימוש בתצוגות מפורטות בהצעות לכתיבה