معاينة واجهة المستخدم بمعاينات قابلة للإنشاء

يتم تحديد العنصر القابل للتجميع من خلال دالة ويتم التعليق التوضيحي عليه باستخدام @Composable:

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

لتفعيل معاينة هذا العنصر القابل للتجميع، أنشئ عنصرًا آخر قابلاً للتجميع مع التعليق التوضيحي باستخدام @Composable و@Preview. يحتوي هذا العنصر القابل للتجميع الجديد والموضَّح الآن على العنصر القابل للتجميع الذي أنشأته في البداية، SimpleComposable:

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

يُعلم التعليق التوضيحي @Preview "استوديو Android" بأنّه يجب عرض هذا العنصر المركّب في طريقة عرض التصميم لهذا الملف. يمكنك الاطّلاع على تعديلات تتم مباشرةً في معاينة المحتوى القابل للتجميع أثناء إجراء التعديلات.

يمكنك إضافة مَعلمات يدويًا في الرمز البرمجي لتخصيص طريقة عرض @Preview في Android Studio. يمكنك أيضًا إضافة التعليق التوضيحي @Preview إلى الدالة نفسها عدة مرات لمعاينة عنصر قابل للتجميع بخصائص مختلفة.

تتمثل إحدى الفوائد الأساسية لاستخدام مكونات @Preview في تجنُّب الاعتماد على المحاكي في "استوديو Android". يمكنك حفظ عملية بدء تشغيل الemulator التي تستهلك ذاكرة كبيرة لإجراء المزيد من التغييرات النهائية على المظهر والأسلوب، ويمكنك الاستفادة من قدرة @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 الفئة. تتطلّب هذه الميزة استخدام الإصدار 1.4.0 من تطبيق Compose أو إصدار أحدث.

الاستخدام مع أجهزة مختلفة

في Android Studio Flamingo، يمكنك تعديل المَعلمة device للتعليق التوضيحي Preview لتحديد إعدادات العناصر القابلة للتجميع في الأجهزة المختلفة.

عندما تحتوي مَعلمة 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 Studio ميزات تتيح لك التفاعل مع معاينات التطبيقات التي حدّدتها. يساعدك هذا التفاعل في فهم سلوك معاينات التطبيق أثناء التشغيل ويسمح لك بالتنقّل بشكل أفضل في واجهة المستخدم باستخدام المعاينات.

وضع التفاعل

يتيح لك الوضع التفاعلي التفاعل مع المعاينة بالطريقة نفسها التي تتفاعل بها على جهاز يعمل ببرنامجك، مثل الهاتف أو الجهاز اللوحي. يتم عزل الوضع التفاعلي في بيئة وضع الحماية (أي أنّه معزول عن معاينات أخرى)، حيث يمكنك النقر على العناصر وإدخال بيانات المستخدم في المعاينة. وهي تشكل طريقة سريعة لاختبار حالات الإيماءات المختلفة وحتى الرسوم المتحرّكة للتصميم القابل للتجميع.

التنقّل في الرموز البرمجية والمخططات القابلة للتجميع

يمكنك تمرير مؤشر الماوس فوق معاينة للاطّلاع على مخطّطات العناصر القابلة للتجميع المضمّنة فيها. يؤدي النقر على مخطّط تفصيلي قابل للتركيب إلى تنشيط عرض المحرِّر للانتقال إلى تعريفه.

تشغيل المعاينة

يمكنك تشغيل @Preview معيّن على جهاز محاكاة أو جهاز فعلي. يتم نشر الاطّلاع على المحتوى ضمن تطبيق المشروع نفسه كصفحة Activity جديدة، لذا فإنه يشترك في السياق والأذونات نفسها. ولا يتطلّب منك كتابة رمز برمجي نموذجي لطلب إذن إذا سبق أن تم منحه.

انقر على رمز تشغيل المعاينة بجانب التعليق التوضيحي @Preview أو في أعلى المعاينة، ويعمل Android Studio على نشر هذا التعليق التوضيحي @Preview على جهازك أو المحاكي المتصل.

نسخ المعالجة @Preview

يمكن نسخ كل معاينة معروضة كصورة من خلال النقر عليها بزر الماوس الأيمن.

معاينات متعدّدة للتعليق التوضيحي @Preview نفسه

يمكنك عرض إصدارات متعدّدة من العنصر القابل للتجميع @Preview نفسه باستخدام مواصفات مختلفة أو مَعلمات مختلفة يتم تمريرها إلى العنصر القابل للتجميع. وبهذه الطريقة، يمكنك تقليل التعليمات البرمجية النموذجية التي تحتاج إلى كتابتها بخلاف ذلك.

نماذج المعاينة المتعددة

androidx.compose.ui:ui-tooling-preview يوفّر الإصدار 1.6.0-alpha01 والإصدارات الأحدث نماذج واجهة برمجة التطبيقات لميزة "المعاينة المتعدّدة": @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

يمكنك استخدام هذا التعليق التوضيحي المخصّص لعناصر المعاينة القابلة للتجميع:

@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

يؤدي ذلك إلى عرض معاينة واحدة لكل عنصر بيانات في التسلسل:

يمكنك استخدام فئة مقدّم الخدمة نفسها لمعاينات متعددة. يمكنك عند الضرورة تحديد عدد المعاينات من خلال ضبط المَعلمة limit.

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

القيود وأفضل الممارسات

ينفِّذ Android Studio رموز المعاينة مباشرةً في منطقة المعاينة. ولا يتطلب تشغيل محاكي أو جهاز فعلي لأنّه يستفيد من جزء مُعاد برمجته من إطار عمل Android يُسمى Layoutlib. ‫Layoutlib هو إصدار customized من إطار عمل Android مصمّم للتشغيل خارج أجهزة Android. ويتمثل هدف المكتبة في توفير معاينة لتنسيق في Android Studio تكون قريبة جدًا من طريقة عرض المحتوى على الأجهزة.

قيود المعاينات

بسبب طريقة عرض المعاينات في Android Studio، فهي خفيفة الوزن ولا تتطلّب استخدام إطار عمل Android بالكامل لعرضها. ومع ذلك، تسري القيود التالية على هذا الإجراء:

• لا تتوفر إمكانية استخدام الشبكة.
• لا يمكن الوصول إلى الملفات
• قد لا تكون بعض واجهات برمجة التطبيقات Context متاحة بالكامل.

المعاينات وViewModels

تكون المعاينات محدودة عند استخدام ViewModel ضمن عنصر قابل للتركيب. لا يمكن لنظام المعاينات إنشاء كل المَعلمات التي يتم تمريرها إلى ViewModel، مثل المستودعات أو حالات الاستخدام أو المدراء أو ما شابه ذلك. بالإضافة إلى ذلك، إذا كان ViewModel يشارك في حقن التبعيات (مثل استخدام Hilt)، لا يمكن لنظام المعاينات إنشاء ViewModel كاملاً.

عند محاولة معاينة عنصر تركيبي باستخدام ViewModel، يعرض "استوديو Android" خطأ عند عرض العنصر التركيبي المحدّد:

إذا كنت تريد معاينة عنصر قابل للتجميع يستخدم ViewModel، عليك إنشاء عنصر قابل للتجميع آخر باستخدام المَعلمات من ViewModel التي تم تمريرها كوسيطات للعنصر القابل للتجميع. بهذه الطريقة، لن تحتاج إلى معاينة العنصر القابل للتجميع الذي يستخدم الرمز 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

يمكنك في أي وقت استخدام "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,
)
AndroidStudioComposeSnippets.kt

مصادر إضافية

للاطّلاع على مزيد من المعلومات حول كيفية مساعدة Android Studio في @Preview تسهيل الاستخدام، والحصول على مزيد من النصائح حول الأدوات، يمكنك الاطّلاع على مدونة Compose Tooling.