یک ترکیب‌پذیر توسط یک تابع تعریف می‌شود و با @Composable حاشیه‌نویسی می‌شود:
@Composable fun SimpleComposable() { Text("Hello World") }
برای فعال کردن پیش‌نمایش این composable، یک composable دیگر ایجاد کنید که با @Composable و @Preview حاشیه‌نویسی شده باشد. این ترکیب‌پذیر جدید حاشیه‌نویسی‌شده اکنون حاوی
ترکیب‌پذیری است که در ابتدا ایجاد کردید، SimpleComposable:
@Preview @Composable fun SimpleComposablePreview() { SimpleComposable() }
حاشیه‌نویسی @Preview به Android Studio می‌گوید که این
ترکیب‌پذیر باید در نمای طراحی این فایل نشان داده شود. می‌توانید به‌روزرسانی‌های زنده پیش‌نمایش ترکیب‌پذیر را هنگام ویرایش ببینید.
می‌توانید پارامترها را به‌صورت دستی در کدتان اضافه کنید تا نحوه رندر کردن @Preview توسط Android Studio را سفارشی‌سازی کنید. حتی می‌توانید حاشیه‌نویسی @Preview را چندین بار به همان تابع اضافه کنید تا پیش‌نمایش یک composable با ویژگی‌های مختلف را ببینید.
یکی از مزایای اصلی استفاده از @Preview composables این است که از اتکا به شبیه‌ساز در «استودیو Android» جلوگیری می‌کند. می‌توانید راه‌اندازی شبیه‌ساز را که حافظه زیادی مصرف می‌کند برای تغییرات نهایی ظاهر و حس نگه دارید و از توانایی @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 نسخه ۱.۴.۰ یا بالاتر نیاز دارد.
استفاده با دستگاه‌های مختلف
در 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)) }
تنظیم رنگ پس‌زمینه
به‌طور پیش‌فرض، composable شما با پس‌زمینه شفاف نمایش داده می‌شود. برای افزودن
پس‌زمینه، پارامترهای showBackground و backgroundColor را اضافه کنید. به‌خاطر داشته باشید که backgroundColor یک Long ARGB است، نه یک مقدار 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 بخوانید تا ببینید آیا composable در پیش‌نمایش (داخل یک
مؤلفه قابل‌بازرسی) رندر شده است یا نه. اگر ترکیب‌بندی در پیش‌نمایش ارائه شود،
LocalInspectionMode.current به true ارزیابی می‌شود. این
اطلاعات به شما امکان می‌دهد پیش‌نمایشتان را سفارشی‌سازی کنید؛ برای مثال، می‌توانید
تصویر جای‌بانی را در پنجره پیش‌نمایش به‌جای نشان دادن داده‌های واقعی نشان دهید.
به‌این‌ترتیب، می‌توانید محدودیت‌ها را هم دور بزنید. برای مثال، نشان دادن داده‌های نمونه به‌جای فراخوانی درخواست شبکه.
@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» ویژگی‌هایی ارائه می‌دهد که به شما امکان می‌دهد با پیش‌نمایش‌های تعریف‌شده‌تان تعامل داشته باشید. این تعامل به شما کمک می‌کند رفتار زمان اجرای پیش‌نمایش‌هایتان را درک کنید و به شما امکان می‌دهد با پیش‌نمایش‌ها بهتر در میان میانای کاربری‌تان پیمایش کنید.
حالت تعاملی
حالت تعاملی به شما امکان می‌دهد با پیش‌نمایش به‌گونه‌ای تعامل داشته باشید که گویی در دستگاهی هستید که برنامه‌تان را اجرا می‌کند، مثل تلفن یا رایانه لوحی. حالت تعاملی در محیط جعبه امن (یعنی جدا از پیش‌نمایش‌های دیگر) جدا شده است، که در آن می‌توانید روی عناصر کلیک کنید و ورودی کاربر را در پیش‌نمایش وارد کنید. این روشی سریع برای آزمایش حالت‌ها، اشاره‌ها، و حتی پویانمایی‌های مختلف ترکیب‌پذیر شما است.
پیمایش کد و طرح‌های کلی قابل‌ساخت
می‌توانید نشانگر را روی پیش‌نمایش نگه دارید تا طرح کلی ترکیب‌پذیرهای موجود در آن را ببینید. با کلیک کردن روی طرح کلی ترکیب‌پذیر، نمای ویرایشگر شما برای پیمایش به تعریف آن فعال می‌شود.
اجرای پیش‌نمایش
می‌توانید @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، تا بتوانید با یک حاشیه‌نویسی، «رابط کاربری 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
می‌توانید از این حاشیه‌نویسی سفارشی برای پیش‌نهادهای پیش‌نمایش خود استفاده کنید:
@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) }
پیش‌نمایش‌هایی که از @PreviewParameter استفاده می‌کنند به‌طور پیش‌فرض بااستفاده از نمایه پارامتر و نام ویژگی (کاربر ۰، کاربر ۱، کاربر ۲، و غیره) نام‌گذاری می‌شوند که می‌تواند تشخیص آن‌ها از یکدیگر را دشوار کند. برای بهبود وضوح پیش‌نمایش، می‌توانید با لغو کردن getDisplayName() در
PreviewParameterProvider، نام‌های نمایشی سفارشی برای هر پیش‌نمایش ارائه دهید. این کار به تشخیص بین انواع مختلف داده‌ها یا حالت‌های میانای کاربر کمک می‌کند. برای مثال، می‌توانید پیش‌نمایش‌ها را براساس داده‌های ورودی برچسب‌گذاری کنید:
class UserAgePreviewParameterProvider : PreviewParameterProvider<User> { // Using a List internally for efficient index-based access private val userList = listOf( User(name = "Elise", age = 30), User(name = "Frank", age = 31), User(name = "Julia", age = 40) ) override val values = userList.asSequence() override fun getDisplayName(index: Int): String? { // Return null or an empty string to use the default index-based name val user = userList.getOrNull(index) ?: return null return "${user.name} - ${user.age}" } }
تولید پیش‌نمایش با کمک هوش مصنوعی
عامل هوش مصنوعی در «استودیو Android» می‌تواند به‌طور خودکار پیش‌نمایش‌های Compose را برای
ترکیب‌بندی‌های شما تولید کند. روی تابع «ترکیب‌پذیر» کلیک راست کنید و
هوش مصنوعی > تولید پیش‌نمایش برای [نام ترکیب‌پذیر] را انتخاب کنید. عامل، ترکیب‌پذیر شما را تجزیه‌وتحلیل می‌کند تا
@Preview کد تکراری لازم را با پارامترهای صحیح تولید کند،
و به شما کمک می‌کند به‌سرعت تأیید کنید که واسط کاربر شما طبق انتظار ارائه می‌شود.
کلاس حاشیه‌نویسی @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 کد پیش‌نمایش‌ها را مستقیماً در ناحیه پیش‌نمایش اجرا می‌کند. این ابزار به اجرای شبیه‌ساز یا دستگاه فیزیکی نیاز ندارد زیرا از بخش منتقل‌شده‌ای از چارچوب Android به نام Layoutlib استفاده می‌کند. Layoutlib نسخه سفارشی‌شده‌ای از چارچوب Android است که برای اجرا در خارج از دستگاه‌های Android طراحی شده است. هدف
کتابخانه ارائه پیش‌نمای چیدمان در Android Studio است که
بسیار نزدیک به رندر آن در دستگاه‌ها است.
محدودیت‌های پیش‌نمایش‌ها
به‌دلیل نحوه ارائه پیش‌نمایش‌ها در Android Studio، آن‌ها سبک هستند و برای ارائه به کل چارچوب Android نیاز ندارند. بااین‌حال، این کار با محدودیت‌های زیر همراه است:
- دسترسی به شبکه وجود ندارد
- بدون دسترسی به فایل
- ممکن است برخی‌از میاناهای برنامه‌سازی کاربردی
Contextبه‌طور کامل دردسترس نباشند
پیش‌نمایش‌ها و ViewModels
پیش‌نمایش‌ها هنگام استفاده از ViewModel در یک
ترکیب‌پذیر محدود هستند. سیستم پیش‌نمایش‌ها قادر به ساختن همه پارامترهای ارسال‌شده به ViewModel نیست، مانند مخازن، موارد استفاده، مدیران، یا موارد مشابه. همچنین، اگر ViewModel شما در تزریق وابستگی شرکت کند (مانند Hilt)، سیستم پیش‌نمایش‌ها نمی‌تواند کل نمودار وابستگی را برای ساختن ViewModel بسازد.
وقتی می‌خواهید یک composable را با ViewModel پیش‌نمایش کنید، Android Studio هنگام رندر کردن آن composable خاص خطایی نشان می‌دهد:
اگر می‌خواهید یک composable را که از ViewModel استفاده می‌کند پیش‌نمایش کنید، باید
composable دیگری با پارامترهای ViewModel که به‌عنوان آرگومان‌های
composable ارسال شده‌اند ایجاد کنید. به‌این‌ترتیب، لازم نیست پیش‌نمایش composable را که از
ViewModel استفاده می‌کند ببینید.
@Composable
fun AuthorScreen(viewModel: AuthorViewModel = viewModel()) {
AuthorScreen(
name = viewModel.authorName,
// ViewModel sends the network requests and makes posts available as a state
posts = viewModel.posts
)
}
@Composable
fun AuthorScreen(
name: NameLabel,
posts: PostsList
) {
// ...
}
@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]
) {
AuthorScreen(
name = NameLabel(name),
posts = PostsList(posts)
)
}
منابع بیشتر
- برای مطالعه بیشتر درباره اینکه Android Studio چگونه
@Previewرا ترویج می‌کند، و برای آشنایی با نکات بیشتر درباره ابزارها، به وبلاگ Compose Tooling مراجعه کنید. - برای راهنمایی درباره «نماهای» قدیمی، به توسعه چیدمان با «نماها» مراجعه کنید.
توصیه‌شده برای شما
- توجه: وقتی جاوا اسکریپت خاموش باشد، نوشتار پیوند نمایش داده می‌شود
- داده‌های با دامنه محلی با CompositionLocal
- Material Design 2 در Compose
- استفاده از «نماها» در Compose