یک composable با یک تابع تعریف می شود و با @Composable
حاشیه نویسی می شود:
@Composable fun SimpleComposable() { Text("Hello World") }
برای فعال کردن یک پیشنمایش از این composable، یک Composable دیگر ایجاد کنید که با @Composable
و @Preview
حاشیهنویسی شده است. این قابلیت ترکیببندی جدید و حاشیهنویسی اکنون حاوی قابلیتی است که در ابتدا ایجاد کردید، SimpleComposable
:
@Preview @Composable fun SimpleComposablePreview() { SimpleComposable() }
حاشیهنویسی @Preview
به اندروید استودیو میگوید که این قابل ترکیب باید در نمای طراحی این فایل نشان داده شود. در حین انجام ویرایشهای خود، میتوانید بهروزرسانیهای زنده پیشنمایش قابل ترکیب خود را مشاهده کنید.
میتوانید پارامترها را به صورت دستی در کد خود اضافه کنید تا نحوه نمایش @Preview
را Android Studio سفارشی کنید. حتی میتوانید حاشیهنویسی @Preview
را چندین بار به یک تابع اضافه کنید تا پیشنمایش یک composable با ویژگیهای مختلف را مشاهده کنید.
یکی از مزایای اصلی استفاده از @Preview
composables اجتناب از اتکا به شبیه ساز در 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(device = "")
)، می توانید با فشار دادن Ctrl
+ Space
، تکمیل خودکار را فراخوانی کنید. سپس، می توانید مقادیر هر پارامتر را تنظیم کنید.
از تکمیل خودکار، میتوانید هر گزینه دستگاهی را از لیست انتخاب کنید – به عنوان مثال، @Preview(device = "id:pixel_4")
. از طرف دیگر، میتوانید با انتخاب spec:width=px,height=px,dpi=int…
یک دستگاه سفارشی را برای تنظیم مقادیر جداگانه هر پارامتر وارد کنید.
برای اعمال، Enter
فشار دهید یا با Esc
لغو کنید.
اگر یک مقدار نامعتبر تنظیم کنید، زیر اعلان با رنگ قرمز خط کشیده میشود و ممکن است یک اصلاح در دسترس باشد ( Alt
+ Enter
(⌥ + ⏎ برای macOS) > Replace with… . Inspection سعی میکند اصلاحی ارائه کند که شبیه ورودی شما باشد.
محلی
برای آزمایش زبان های مختلف کاربر، پارامتر locale
را اضافه کنید:
@Preview(locale = "fr-rFR") @Composable fun DifferentLocaleComposablePreview() { Text(text = stringResource(R.string.greeting)) }
تنظیم رنگ پس زمینه
به طور پیش فرض، composable شما با پس زمینه شفاف نمایش داده می شود. برای افزودن پسزمینه، پارامترهای 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=4&hl=fa)
حالت UI
پارامتر 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 Studio ویژگی هایی را ارائه می دهد که به شما امکان می دهد با پیش نمایش های تعریف شده خود تعامل داشته باشید. این تعامل به شما کمک میکند تا رفتار زمان اجرا پیشنمایشهای خود را درک کنید و به شما امکان میدهد با پیشنمایشها، رابط کاربری خود را بهتر پیمایش کنید.
حالت تعاملی
حالت تعاملی به شما امکان میدهد با یک پیشنمایش مانند دستگاهی که برنامه شما را اجرا میکند، مانند تلفن یا رایانه لوحی، تعامل داشته باشید. حالت تعاملی در یک محیط جعبه شنی (به معنی جدا شده از سایر پیش نمایش ها) جدا شده است، جایی که می توانید روی عناصر کلیک کنید و ورودی کاربر را در پیش نمایش وارد کنید. این یک راه سریع برای آزمایش حالتهای مختلف، حرکات و حتی انیمیشنهای قابل ساخت شما است.
ناوبری کد و خطوط کلی قابل ترکیب
میتوانید ماوس را روی یک پیشنمایش نگه دارید تا رئوس مطالب موجود در آن را ببینید. با کلیک بر روی یک طرح کلی قابل ترکیب، نمای ویرایشگر شما برای رفتن به تعریف آن فعال می شود.
اجرای پیش نمایش
میتوانید یک @Preview
خاص را روی یک شبیهساز یا یک دستگاه فیزیکی اجرا کنید. پیش نمایش در همان برنامه پروژه به عنوان یک Activity
جدید مستقر می شود، بنابراین زمینه و مجوزهای مشابهی را به اشتراک می گذارد. اگر قبلاً اعطا شده باشد، نیازی به نوشتن کد دیگ بخار برای درخواست مجوز نیست.
روی نماد اجرای پیشنمایش کلیک کنید در کنار حاشیهنویسی
@Preview
یا در بالای پیشنمایش، و Android Studio آن @Preview
در دستگاه یا شبیهساز متصل شما پیادهسازی میکند.
رندر @Preview
را کپی کنید
هر پیش نمایش رندر شده را می توان با کلیک راست روی آن به عنوان یک تصویر کپی کرد.
پیش نمایش های متعدد از حاشیه نویسی @Preview
میتوانید چندین نسخه از یک @Preview
composable را با مشخصات مختلف، یا پارامترهای متفاوتی که به composable ارسال شده است، به نمایش بگذارید. به این ترتیب، می توانید کد دیگ بخار را که در غیر این صورت باید بنویسید، کاهش دهید.
قالب های چند پیش نمایش
androidx.compose.ui:ui-tooling-preview
1.6.0-alpha01+ الگوهای API Multipreview را معرفی میکند: @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
میتوانید از این حاشیهنویسی سفارشی برای پیشنمایشهای composable خود استفاده کنید:
@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
به تابع Composable Preview ارسال کنید.
@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 کد پیشنمایش را مستقیماً در قسمت پیشنمایش اجرا میکند. نیازی به اجرای شبیهساز یا دستگاه فیزیکی ندارد زیرا از بخشی منتقل شده از چارچوب Android به نام Layoutlib
استفاده میکند. Layoutlib
یک نسخه سفارشی از چارچوب اندروید است که برای اجرا در خارج از دستگاه های اندرویدی طراحی شده است. هدف این کتابخانه ارائه پیش نمایشی از یک طرح بندی در اندروید استودیو است که به رندر آن در دستگاه ها بسیار نزدیک است.
پیش نمایش محدودیت ها
به دلیل نحوه ارائه پیشنمایشها در اندروید استودیو، سبک وزن هستند و برای رندر کردن آنها به کل چارچوب اندروید نیاز ندارند. با این حال، این با محدودیت های زیر همراه است:
- بدون دسترسی به شبکه
- دسترسی به فایل وجود ندارد
- برخی از
Context
API ممکن است به طور کامل در دسترس نباشند
پیش نمایش ها و ViewModels
هنگام استفاده از ViewModel
در یک composable، پیشنمایشها محدود میشوند. سیستم پیش نمایش قادر به ساخت تمام پارامترهای ارسال شده به ViewModel
نیست، مانند مخازن، موارد استفاده، مدیران یا موارد مشابه. همچنین، اگر ViewModel
شما در تزریق وابستگی شرکت کند (مانند Hilt )، سیستم پیشنمایش نمیتواند کل نمودار وابستگی را برای ساخت ViewModel
بسازد.
هنگامی که سعی میکنید پیشنمایش یک composable را با ViewModel
مشاهده کنید، Android Studio هنگام رندر کردن یک composable خاص، خطایی را نشان میدهد:
اگر میخواهید یک Composable را پیشنمایش کنید که از ViewModel
استفاده میکند، باید composable دیگری با پارامترهای ViewModel
به عنوان آرگومانهای composable ارسال کنید. به این ترتیب، نیازی به پیش نمایش composable که از 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
را ترویج میکند و نکات بیشتر Tooling را بدانید، وبلاگ Compose Tooling را بررسی کنید.
برای شما توصیه می شود
- توجه: وقتی جاوا اسکریپت خاموش است، متن پیوند نمایش داده می شود
- داده های محدوده محلی با CompositionLocal
- Material Design 2 در Compose
- استفاده از Views در Compose