پیش نمایش UI خود را با پیش نمایش های قابل ترکیب

یک composable توسط یک تابع تعریف می شود و با @Composable حاشیه نویسی می شود:

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

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

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

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

توجه: Android Wear از حاشیه نویسی های مختلفی برای پیش نمایش استفاده می کند ( @WearPreviewDevices و @WearPreviewFontScales )؛ برای اطلاعات بیشتر به آزمایش ترکیب اندازه های صفحه و فونت با استفاده از پیش نمایش ها مراجعه کنید.

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

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

یکی از مزایای اصلی استفاده از @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")
    }
}
AndroidStudioComposeSnippets.kt

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

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

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

به طور پیش فرض، composable شما با پس زمینه شفاف نمایش داده می شود. برای افزودن پس‌زمینه، پارامترهای 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 بخوانید تا ببینید آیا 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!")
    }
}
AndroidStudioComposeSnippets.kt

با @Preview خود تعامل داشته باشید

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

حالت تعاملی

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

ناوبری کد و خطوط قابل ترکیب

می‌توانید ماوس را روی یک پیش‌نمایش نگه دارید تا رئوس مطالب موجود در آن را ببینید. با کلیک بر روی یک طرح کلی قابل ترکیب، نمای ویرایشگر شما برای رفتن به تعریف آن فعال می شود.

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

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

توجه: آرگومان های اعمال شده در حاشیه نویسی @Preview (به عنوان مثال، widthDp ، locale ، و غیره) برای پیش نمایشی که اجرا و اجرا می شود اعمال نمی شود.

روی نماد اجرای پیش‌نمایش کلیک کنید در کنار حاشیه‌نویسی @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
AndroidStudioComposeSnippets.kt

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

@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 به تابع Composable Preview ارسال کنید.

@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

محدودیت ها و بهترین شیوه ها

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

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

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

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

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

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

هنگامی که می‌خواهید پیش‌نمایش یک composable را با ViewModel مشاهده کنید، Android Studio خطایی را هنگام رندر کردن یک composable خاص نشان می‌دهد:

هشدار: شما نباید نمونه های ViewModel را به سایر توابع قابل ترکیب منتقل کنید. وقتی این کار را انجام می‌دهید، Composable‌ها را با نوع ViewModel جفت می‌کنید، که باعث می‌شود کمتر قابل استفاده مجدد باشند، آزمایش آن‌ها سخت‌تر باشد و پیش‌نمایش آن‌ها ناتوان باشد.

اگر می‌خواهید یک 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,
)
AndroidStudioComposeSnippets.kt

منابع اضافی

برای خواندن اطلاعات بیشتر در مورد اینکه چگونه Android Studio سهولت استفاده @Preview را ترویج می‌کند و نکات بیشتر Tooling را بدانید، وبلاگ Compose Tooling را بررسی کنید.

{% کلمه به کلمه %} {% آخر کلمه %}