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

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

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

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

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

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

ملاحظة: تستخدِم أجهزة Android Wear تعليقات توضيحية مختلفة للمعاينات (@WearPreviewDevices و@WearPreviewFontScales)، ولمزيد من المعلومات، يُرجى الاطّلاع على اختبار مجموعات أحجام الشاشة والخطوط باستخدام المعاينات.

يمكنك إضافة مَعلمات يدويًا في الرمز لتخصيص طريقة عرض "استوديو 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 من Compose أو إصدارًا أحدث.

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

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

وضع التفاعل

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

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

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

عرض معاينة

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

ملاحظة: لا يتم تطبيق الوسيطات التي تم تطبيقها على التعليق التوضيحي @Preview (على سبيل المثال، widthDp أو locale وما إلى ذلك) على المعاينة التي يتم تشغيلها و نشرها.

انقر على رمز عرض معاينة بجانب التعليق التوضيحي @Preview أو في أعلى المعاينة، وينشر Android Studio هذا التعليق التوضيحي @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 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

يتم تلقائيًا تسمية المعاينات التي تستخدِم @PreviewParameter باستخدام فهرس المَعلمة واسم السمة (المستخدم 0 والمستخدم 1 والمستخدم 2 وما إلى ذلك)، ما قد يجعل من الصعب التمييز بينها. لتحسين وضوح المعاينة، يمكنك توفير أسماء عرض مخصّصة لكل معاينة عن طريق إلغاء getDisplayName() في PreviewParameterProvider. يساعد ذلك في التمييز بين الاختلافات المختلفة في البيانات أو حالات واجهة المستخدم. على سبيل المثال، يمكنك تصنيف المعاينات استنادًا إلى بيانات الإدخال:

class UserAgePreviewParameterProvider : PreviewParameterProvider<User> {
    // Using a List internally for efficient index-based access
    private val userList = listOf(
        User(name = "Elise", age = 30),
        User(name = "Frank", age = 31),
        User(name = "Julia", age = 40)
    )

    override val values = userList.asSequence()

    override fun getDisplayName(index: Int): String? {
        // Return null or an empty string to use the default index-based name
        val user = userList.getOrNull(index) ?: return null
        return "${user.name} - ${user.age}"
    }
}
AndroidStudioComposeSnippets.kt

ملاحظة: للحصول على أداء أفضل، استخدِم List بدلاً من Sequence في PreviewParameterProvider. يوفّر ذلك وصولاً فعالاً يستند إلى الفهرس في getDisplayName() ويتجنّب عمليات البحث البطيئة في التسلسلات الكبيرة.

إنشاء المعاينة بمساعدة الذكاء الاصطناعي

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

يمكنك إنشاء معاينة Compose باستخدام الذكاء الاصطناعي.

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

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

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

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

المعاينات وViewModels

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

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

**تحذير:** يجب عدم تمرير مثيلات ViewModel إلى دوال العناصر المركّبة الأخرى. عند إجراء ذلك، يتم ربط العناصر المركّبة بنوع ViewModel، ما يجعلها أقل قابلية لإعادة الاستخدام وأكثر صعوبة في الاختبار ولا يمكن معاينتها.

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

@Composable
fun AuthorScreen(viewModel: AuthorViewModel = viewModel()) {
  AuthorScreen(
    name = viewModel.authorName,
    // ViewModel sends the network requests and makes posts available as a state
    posts = viewModel.posts
  )
}

@Composable
fun AuthorScreen(
  name: NameLabel,
  posts: PostsList
) {
  // ...
}

@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]
) {
  AuthorScreen(
      name = NameLabel(name),
      posts = PostsList(posts)
  )
}

مراجع إضافية

• لمزيد من المعلومات حول كيفية تسهيل "استوديو Android" استخدام @Preview، ولمزيد من النصائح حول الأدوات، يُرجى الاطّلاع على مدونة Compose Tooling.
• للاطّلاع على إرشادات طرق العرض القديمة، يُرجى مراجعة تطوير تنسيق باستخدام طرق العرض.