این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

یک عنصر متنی ساده حاوی کلمات "سلام دنیا"

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

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

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

یک gif که به‌روزرسانی‌های زمان واقعی را با استفاده از Compose نشان می‌دهد پیش نمایش

می‌توانید پارامترها را به صورت دستی در کد خود اضافه کنید تا نحوه نمایش @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")
    }
}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

یک عنصر متنی ساده حاوی کلمه "Bonjour" با زبان فرانسوی پرچم

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

به طور پیش فرض، 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 ویژگی هایی را ارائه می دهد که به شما امکان می دهد با پیش نمایش های تعریف شده خود تعامل داشته باشید. این تعامل به شما کمک می‌کند تا رفتار زمان اجرا پیش‌نمایش‌های خود را درک کنید و به شما امکان می‌دهد با پیش‌نمایش‌ها، رابط کاربری خود را بهتر پیمایش کنید.

حالت تعاملی

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

کاربر روی «تعاملی» پیش‌نمایش کلیک می‌کند دکمه

ویدئویی از تعامل کاربر با a پیش نمایش

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

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

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

می‌توانید یک @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 FontScalePreviewsAndroidStudioComposeSnippets.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 خاص نشان می‌دهد:

پنجره مشکل استودیوی Android با «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 را بررسی کنید.

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

برای شما توصیه می شود

توجه: وقتی جاوا اسکریپت خاموش است، متن پیوند نمایش داده می شود
داده های محدوده محلی با CompositionLocal
Material Design 2 در Compose
استفاده از Views در Compose