تمت ترجمة هذه الصفحة بواسطة 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 composables في تجنُّب الاعتماد على المحاكي في "استوديو 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 للتعليق التوضيحي "معاينة " لتحديد إعدادات العناصر القابلة للتجميع في الأجهزة المختلفة.

عيّنة دالة
مركّبة

عندما تحتوي مَعلمة 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

مستطيل أخضر مع عبارة
"Hello World"

واجهة مستخدِم النظام

إذا كنت بحاجة إلى عرض شريطَي الحالة والإجراءات داخل معاينة، أضِف المَعلمة 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" هذا @Preview على جهازك المرتبط أو المحاكي.

النقر على زر "تشغيل المعاينة"
في المعاينة

فيديو للمستخدم ينشر معاينة على
الجهاز

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

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

مستخدم ينقر على معاينة لنسخها كأحد
الصور

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

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

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

يقدّم الإصدار androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ نماذج للمعاينة المتعددة نماذج واجهة برمجة التطبيقات: @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 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" معاينات التعليمات البرمجية مباشرةً في منطقة المعاينة. ولا يتطلب تشغيل محاكي أو جهاز فعلي لأنّه يستفيد من جزء مُعاد برمجته من إطار عمل 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 في ميزة "الإنشاء"
استخدام "طرق العرض" في ميزة "الإنشاء"

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