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

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

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

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

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

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

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

ملف GIF يعرض التعديلات في الوقت الفعلي باستخدام ميزة Compose معاينة

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

تجنّب الاعتماد على عناصر @Preview القابلة للإنشاء هي إحدى المزايا الأساسية على المحاكي في "استوديو Android" يمكنك حفظ بدء التشغيل المكثّف للذاكرة المحاكي لإجراء المزيد من التغييرات النهائية على الشكل والأسلوب، وقدرة "@Preview" على إجراء واختبار التغييرات الصغيرة في الرموز بسهولة

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

تحديد @Preview

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

الأبعاد

يتم تلقائيًا اختيار سمات @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 من "إنشاء" أو إصدار أحدث.

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

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

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

عندما تحتوي معلَمة الجهاز على سلسلة فارغة (@Preview(device = ""))، يمكنك إجراء ما يلي: استدعِ الإكمال التلقائي بالضغط على Ctrl + Space. بعد ذلك، يمكنك تعيين القيم لكل معلمة.

تعديل دالّة المثال

من خلال ميزة الإكمال التلقائي، يمكنك اختيار أي خيار جهاز من القائمة، على سبيل المثال، @Preview(device = "id:pixel_4"). بدلاً من ذلك، يمكنك إدخال جهاز مخصّص عن طريق اختيار spec:width=px,height=px,dpi=int… لضبط القيم الفردية لكل مَعلمة.

المواصفات قائمة

للتطبيق، اضغط على Enter، أو للإلغاء اضغط على Esc.

في حال ضبط قيمة غير صالحة، يتم وضع خط أحمر تحت البيان، وقد يتم حلّ المشكلة. متاحة ( Alt + Enter ( ⌥ + ⏎ لنظام التشغيل macOS) > Replace with ... (استبدال بـ ...) يحاول الفحص توفير حل أقرب ما يشبه الإدخال.

مثال على قيمة غير صالحة

اللغة

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

وضع التفاعل

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

المستخدم ينقر على زر "تفاعلي" في المعاينة

فيديو يعرض تفاعل المستخدم مع معاينة

التنقّل في الرموز والمخططات القابلة للإنشاء

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

تمرير مؤشر الماوس فوق معاينة، ما يؤدي إلى عرض "استوديو YouTube" لمخططات العناصر القابلة للتجميع

عرض معاينة

يمكنك تشغيل @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

علامة التبويب "تصميم" في "استوديو 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

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

معاينات تُظهر &quot;إليز&quot; و&quot;فرانك&quot; و&quot;جوليا&quot; عناصر قابلة للإنشاء

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

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

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

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

القيود المفروضة على المعاينات

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

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

معاينات وViewModels

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

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

لوحة مشاكل &quot;استوديو Android&quot; مع تعذُّر إنشاء مثيل &quot;ViewModel&quot; رسالة

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

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" لسهولة استخدام @Preview، وتعلَّم المزيد من النصائح حول الأدوات، اطلع على المدونة Compose الأدوات:

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