تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

عنصر نصي بسيط يحتوي على الكلمات "مرحبًا
عالم"

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

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

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

صورة GIF تعرض تعديلات في الوقت الفعلي باستخدام ميزة "إنشاء
معاينة"

يمكنك إضافة مَعلمات يدويًا في الرمز البرمجي لتخصيص طريقة عرض @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 FontScalePreviewsAndroidStudioComposeSnippets.kt

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

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

علامة التبويب "تصميم" في "استوديو Android" تعرِض العنصر القابل للتجميع بخط صغير وخط كبير

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

@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

علامة التبويب "تصميم" في "استوديو Android" تعرِض العنصر القابل للتجميع في جميع
الإعدادات

تتيح لك طبيعة الاختيار والجمع في ميزة "العرض المتعدّد" - وميزة "العرض العادي" أيضًا - اختبار العديد من خصائص المشاريع الأكبر حجمًا بشكلٍ أكثر شمولاً.

`@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" خطأ عند عرض العنصر التركيبي المحدّد:

لوحة مشاكل "استوديو Android" التي تعرض رسالة "تعذّر إنشاء مثيل لـ ViewModel"

إذا كنت تريد معاينة عنصر قابل للتجميع يستخدم 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.

أفلام مُقترَحة لك

ملاحظة: يتم عرض نص الرابط عندما تكون لغة JavaScript غير مفعّلة.
البيانات على النطاق المحلي باستخدام CompositionLocal
تصميم Material Design 2 في ميزة "الإنشاء"
استخدام "طرق العرض" في ميزة "الإنشاء"

معاينة الصور المتحركة وتصحيح أخطائها