پیش‌نمایش کردن واسط کاربر با پیش‌نمایش‌های ترکیب‌شدنی

ترکیب‌پذیر با تابع تعریف می‌شود و با @Composable حاشیه‌نویسی می‌شود:

@Composable
fun SimpleComposable() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

برای فعال کردن پیش‌نمایش این عنصر ترکیبی، عنصر ترکیبی دیگری بسازید که با @Composable و @Preview حاشیه‌نویسی شده باشد. این عنصر ترکیبی جدید حاشیه‌نویسی‌شده اکنون حاوی عنصر ترکیبی‌ای است که در ابتدا ایجاد کردید، SimpleComposable:

@Preview
@Composable
fun SimpleComposablePreview() {
    SimpleComposable()
}
AndroidStudioComposeSnippets.kt

گزارمان @Preview به Android Studio می‌گوید که این ترکیب‌پذیر باید در نمای طراحی این فایل نشان داده شود. می‌توانید به‌روزرسانی‌های زنده پیش‌نمایش ترکیبی را هنگام انجام ویرایش‌ها ببینید.

می‌توانید پارامترها را به‌صورت دستی در کدتان اضافه کنید تا روشی را که Android Studio @Preview را پرداز می‌کند سفارشی‌سازی کنید. حتی می‌توانید چندین بار حاشیه‌نویسی @Preview را به همان تابع اضافه کنید تا یک عنصر ترکیبی را با ویژگی‌های مختلف پیش‌دید کنید.

یکی از مزایای اصلی استفاده از عناصر ترکیبی @Preview اجتناب از اتکا به شبیه‌ساز در «استودیو 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")
    }
}
AndroidStudioComposeSnippets.kt

پیش‌نمایش رنگ پویا

اگر رنگ پویا را در برنامه‌تان فعال کرده‌اید، از ویژگی 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))
}
AndroidStudioComposeSnippets.kt

تنظیم رنگ پس‌زمینه

به‌طور پیش‌فرض، عنصر ترکیبی شما با پس‌زمینه شفاف نمایش داده می‌شود. برای افزودن پس‌زمینه، پارامترهای showBackground و backgroundColor را اضافه کنید. به‌خاطر داشته باشید که backgroundColor یک ARGB Long است، نه یک مقدار Color

@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

واسط کاربری سیستم

اگر نیاز دارید نوار وضعیت و نوار کنش را در پیش‌نمایش نمایش دهید، پارامتر showSystemUi را اضافه کنید:

@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

حالت میانای کاربر

پارامتر uiMode می‌تواند هریک از Configuration.UI_* ثابت‌ها را بگیرد و به شما امکان می‌دهد رفتار پیش‌نمایش را متناسب با آن تغییر دهید. برای مثال، می‌توانید پیش‌نمایش را روی «حالت شب» تنظیم کنید تا ببینید زمینه چگونه واکنش نشان می‌دهد.

LocalInspectionMode

می‌توانید از LocalInspectionMode CompositionLocal بخوانید تا ببینید آیا عنصر ترکیبی در پیش‌نمایش (درون عنصر بازرسی‌پذیر) پرداز می‌شود یا نه. اگر قطعه در پیش‌نمایش پردازنده شود، 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!")
    }
}
AndroidStudioComposeSnippets.kt

تعامل با @Preview

«استودیو Android» ویژگی‌هایی ارائه می‌دهد که به شما امکان می‌دهد با پیش‌نمایش‌های تعریف‌شده‌تان تعامل داشته باشید. این تعامل به شما کمک می‌کند رفتار زمان اجرای پیش‌نمایش‌هایتان را درک کنید و به شما امکان می‌دهد با پیش‌نمایش‌ها بهتر در واسط کاربر ناوبری کنید.

حالت تعاملی

حالت تعاملی به شما امکان می‌دهد با پیش‌نمایش تعامل داشته باشید، درست مانند کاری که در دستگاهی که برنامه شما را اجرا می‌کند، مانند تلفن یا رایانه لوحی، انجام می‌دهید. حالت تعاملی در محیطی امن (یعنی جدا از پیش‌نمایش‌های دیگر) جدا شده است، که در آن می‌توانید روی عناصر کلیک کنید و درونداد کاربر را در پیش‌نمایش وارد کنید. این روشی سریع برای آزمایش حالت‌ها، اشاره‌ها، و حتی پویانمایی‌های مختلف عنصر ترکیبی شما است.

پیمایش کد و نمای کلی ترکیب‌کردنی

می‌توانید نشانگر را روی پیش‌نمایش نگه دارید تا خطوط کلی عناصر ترکیبی موجود در آن را ببینید. با کلیک کردن روی یک نمای کلی ترکیبی، نمای ویرایشگر شما را برای پیمایش به تعریف آن راه‌اندازی می‌کند.

اجرای پیش‌نمایش

می‌توانید @Preview خاصی را در شبیه‌ساز یا دستگاه فیزیکی اجرا کنید. پیش‌نمایش در همان برنامه پروژه به‌عنوان Activity جدیدی پیاده‌سازی می‌شود، بنابراین از زمینه و اجازه‌های یکسانی استفاده می‌کند. اگر قبلاً اجازه داده شده باشد، نیازی نیست کد کلیشه‌ای درخواست اجازه را بنویسید.

روی نماد اجرای پیش‌نمایش در کنار @Preview گزارمان یا در بالای پیش‌نمایش کلیک کنید، و Android Studio آن @Preview را در دستگاه متصل یا شبیه‌ساز شما مستقر می‌کند.

کپی کردن @Preview پردازنده

هر پیش‌نمایش پردازش‌شده را می‌توان با کلیک راست کردن روی آن به‌عنوان تصویر کپی کرد.

چندین پیش‌نمایش از همان گزارمان @Preview

می‌توانید چندین نسخه از همان @Preview قابل ترکیب را با مشخصات مختلف یا پارامترهای مختلفی که به قابل ترکیب ارسال شده است نمایش دهید. به‌این‌ترتیب، می‌توانید کد کلیشه‌ای را که درغیراین‌صورت باید می‌نوشتید کاهش دهید.

الگوهای پیش‌نمایش چندگانه

‫androidx.compose.ui:ui-tooling-preview نسخه 1.6.0-alpha01+ الگوهای API «پیش‌نمایش چندگانه» را معرفی می‌کند: الگوهای 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
AndroidStudioComposeSnippets.kt

می‌توانید از این حاشیه‌نویسی سفارشی برای عناصر ترکیبی پیش‌نمایش استفاده کنید:

@FontScalePreviews
@Composable
fun HelloWorldPreview() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

می‌توانید چندین گل‌نویسی چندپیش‌نمایش و گل‌نویسی پیش‌نمایش معمولی را با هم ترکیب کنید تا مجموعه کامل‌تری از پیش‌نمایش‌ها ایجاد کنید. ترکیب کردن گلچین‌های چندپیش‌نمایش به این معنی نیست که همه ترکیب‌های مختلف نشان داده می‌شوند. درعوض، هر گزارمان چندپیش‌نمایش به‌صورت مستقل عمل می‌کند و فقط گونه‌های خود را پرداز می‌کند.

@Preview(
    name = "Spanish",
    group = "locale",
    locale = "es"
)
@FontScalePreviews
annotation class CombinedPreviews

@CombinedPreviews
@Composable
fun HelloWorldPreview2() {
    MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } }
}
AndroidStudioComposeSnippets.kt

ماهیت ترکیب و تطبیق پیش‌نمایش چندگانه-- و پیش‌نمایش معمولی!-- به شما امکان می‌دهد بسیاری از ویژگی‌های پروژه‌های بزرگ‌تر را به‌طور جامع‌تر آزمایش کنید.

‫@Preview و مجموعه‌های بزرگ داده

اغلب، نیاز پیش می‌آید که مجموعه داده بزرگی را به پیش‌نمایش ترکیب‌پذیرتان منتقل کنید. برای انجام این کار، کافی است با افزودن پارامتری با حاشیه‌نویسی @PreviewParameter ، داده‌های نمونه را به تابع «پیش‌نمایش ترکیبی» ارسال کنید.

@Preview
@Composable
fun UserProfilePreview(
    @PreviewParameter(UserPreviewParameterProvider::class) user: User
) {
    UserProfile(user)
}
AndroidStudioComposeSnippets.kt

برای ارائه داده‌های نمونه، کلاسی ایجاد کنید که PreviewParameterProvider را پیاده‌سازی کند و داده‌های نمونه را به‌صورت توالی برگرداند.

class UserPreviewParameterProvider : PreviewParameterProvider<User> {
    override val values = sequenceOf(
        User("Elise"),
        User("Frank"),
        User("Julia")
    )
}
AndroidStudioComposeSnippets.kt

این کار یک پیش‌نمایش برای هر عنصر داده در توالی ارائه می‌دهد:

می‌توانید از کلاس ارائه‌دهنده یکسانی برای چندین پیش‌نمایش استفاده کنید. درصورت لزوم، با تنظیم پارامتر محدودیت، تعداد پیش‌نمایش‌ها را محدود کنید.

@Preview
@Composable
fun UserProfilePreview2(
    @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
    UserProfile(user)
}
AndroidStudioComposeSnippets.kt

پیش‌نمایش‌هایی که از @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}"
    }
}
AndroidStudioComposeSnippets.kt

تولید پیش‌نمایش با کمک هوش مصنوعی

عامل هوش مصنوعی در «استودیو Android» می‌تواند پیش‌نمایش‌های Compose را به‌طور خودکار برای ترکیب‌پذیرهایتان تولید کند. روی یک تابع «ترکیب‌شدنی» کلیک راست کنید و هوش مصنوعی > تولید پیش‌نمایش برای [نام «ترکیب‌شدنی»] را انتخاب کنید. نماینده با تجزیه‌وتحلیل عنصر ترکیبی شما، @Preview کلیشه ضروری را با پارامترهای صحیح تولید می‌کند و به شما کمک می‌کند به‌سرعت تأیید کنید که رابط کاربری شما همان‌طور که انتظار می‌رود پرداز می‌شود.

کلاس گزارمان @Preview

همیشه می‌توانید در Android Studio با «ctrl یا ⌘ + کلیک» روی @Preview گزارمان، فهرست کاملی از پارامترهایی که هنگام سفارشی‌سازی پیش‌نمایش قابل‌تنظیم هستند را ببینید.

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,
)
AndroidStudioComposeSnippets.kt

محدودیت‌ها و روال‌های مطلوب

‫Android Studio کد پیش‌نمایش را مستقیماً در ناحیه پیش‌نمایش اجرا می‌کند. این کار به اجرای شبیه‌ساز یا دستگاه فیزیکی نیاز ندارد زیرا از بخش انتقال‌یافته چارچوب Android به‌نام Layoutlib استفاده می‌کند. ‫Layoutlib نسخه سفارشی چارچوب Android است که برای اجرا در خارج از دستگاه‌های Android طراحی شده است. هدف کتابخانه این است که پیش‌نمایی از چیدمان در Android Studio ارائه دهد که بسیار نزدیک به پرداز آن در دستگاه‌ها است.

محدودیت‌های پیش‌نمایش

به‌دلیل نحوه پرداز پیش‌نمایش‌ها در Android Studio، این پیش‌نمایش‌ها سبک هستند و برای پرداز کردن آن‌ها به کل چارچوب Android نیاز نیست. بااین‌حال، این کار محدودیت‌های زیر را به‌همراه دارد:

• دسترسی به شبکه وجود ندارد
• بدون دسترسی به فایل
• برخی‌از APIهای Context ممکن است به‌طور کامل دردسترس نباشند

پیش‌نمایش‌ها و ViewModels

وقتی از ViewModel در یک ترکیب‌پذیر استفاده می‌کنید، پیش‌نمایش‌ها محدود است. سیستم پیش‌نمایش نمی‌تواند همه پارامترهای ارسال‌شده به ViewModel را، مثل مخزن‌ها، موارد استفاده، مدیران، یا موارد مشابه، بسازد. همچنین، اگر ViewModel شما در تزریق وابستگی شرکت می‌کند (مثلاً با Hilt)، سیستم پیش‌نمایش نمی‌تواند کل گراف وابستگی را برای ساختن ViewModel بسازد.

وقتی سعی می‌کنید یک عنصر ترکیبی را با ViewModel پیش‌نمایش کنید، Android Studio هنگام پرداز کردن عنصر ترکیبی خاص، خطایی نشان می‌دهد:

اگر می‌خواهید پیش‌نمایش عنصر ترکیبی‌ای را که از ViewModel استفاده می‌کند ببینید، باید عنصر ترکیبی دیگری با پارامترهای ViewModel ایجاد کنید که به‌عنوان آرگومان‌های عنصر ترکیبی ارسال شده باشد. به‌این‌ترتیب، لازم نیست از عنصر ترکیبی که از 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 را بررسی کنید.
• برای راهنمای قدیمی «نماها»، به توسعه چیدمان با «نماها» مراجعه کنید.