تتيح لك معاينات التطبيقات المصغّرة التي يتم إنشاؤها إنشاء معاينات ديناميكية ومخصّصة لتطبيقاتك المصغّرة تعكس بدقة كيفية ظهورها على الشاشة الرئيسية للمستخدم. ويتم توفيرها من خلال واجهة برمجة تطبيقات فورية، ما يعني أنّ تطبيقك يوفّر المعاينة في أي وقت خلال مراحل نشاطه بدون تلقّي طلب صريح من مضيف التطبيق المصغّر.
يتناول هذا الدليل كيفية تقديم معاينات للتطبيقات المصغّرة المستندة إلى Glance. إذا تم تنفيذ التطبيق المصغّر باستخدام RemoteViews، يمكنك الاطّلاع على إضافة معاينات إلى أداة اختيار التطبيقات المصغّرة.
لتحسين تجربة منتقي التطبيقات المصغّرة في تطبيقك من أجل التطبيقات المصغّرة في Glance، يمكنك تقديم معاينة للتطبيق المصغّر الذي تم إنشاؤه باستخدام GlanceAppWidget.providePreview على الأجهزة التي تعمل بنظام التشغيل Android 15 والإصدارات الأحدث، وتحديد previewImage للإصدارات الأقدم، وكحل احتياطي على نظام التشغيل Android 15 والإصدارات الأحدث في حال عدم توفّر معاينة تم إنشاؤها.
لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إثراء تطبيقك من خلال التغطية المباشرة للأخبار والتطبيقات المصغّرة على YouTube.
إعداد تطبيقك لمعاينات التطبيقات المصغّرة التي تم إنشاؤها
لعرض معاينات التطبيقات المصغّرة التي تم إنشاؤها على جهاز يعمل بنظام التشغيل Android 15 أو إصدار أحدث، عليك أولاً ضبط قيمة compileSdk على 35 أو قيمة أعلى في ملف الوحدة build.gradle لتفعيل المعاينات التي تم إنشاؤها في أداة اختيار التطبيقات المصغّرة.
يمكن للتطبيقات بعد ذلك استخدام setWidgetPreview في GlanceAppWidgetManager. لمنع إساءة الاستخدام والحدّ من المشاكل المتعلّقة بسلامة النظام، تم فرض حدّ أقصى على معدّل استخدام واجهة برمجة التطبيقات setWidgetPreview. الحدّ الأقصى التلقائي هو مكالمتان تقريبًا في الساعة.
إنشاء معاينة محدَّثة باستخدام Jetpack Glance
بالنسبة إلى التطبيقات المصغّرة التي تم إنشاؤها باستخدام Jetpack Glance، اتّبِع الخطوات التالية:
تجاوز دالة
GlanceAppWidget.providePreviewلتوفير المحتوى القابل للإنشاء للمعاينة. كما هو الحال فيprovideGlance، يمكنك تحميل بيانات تطبيقك وتمريرها إلى الدالة المركّبة لمحتوى التطبيق المصغّر، وذلك لعرض بيانات دقيقة في المعاينة. على عكسprovideGlance، هذا تركيب واحد بدون إعادة تركيب أو تأثيرات.يمكنك استدعاء
GlanceAppWidgetManager.setWidgetPreviewsلإنشاء المعاينة ونشرها.
لا يتوفّر ردّ اتصال من النظام لتقديم المعاينات، لذا يجب أن يحدّد تطبيقك وقت استدعاء setWidgetPreviews. تعتمد استراتيجية التحديث على حالة استخدام التطبيق المصغّر:
- إذا كان التطبيق المصغّر يتضمّن معلومات ثابتة أو إجراءً سريعًا، اضبط المعاينة عند تشغيل التطبيق لأول مرة.
- يمكنك ضبط المعاينة بعد أن يتضمّن تطبيقك بيانات، مثلاً بعد تسجيل دخول المستخدم أو الإعداد الأولي.
- يمكنك إعداد مهمة دورية لتعديل المعاينات بوتيرة محدّدة.
تحديد المشاكل وحلّها في المعاينات التي تم إنشاؤها
من المشاكل الشائعة أنّه بعد إنشاء معاينة، قد لا تظهر الصور أو الرموز أو غيرها من
الدوال المركّبة في صورة المعاينة، وذلك حسب حجم
التطبيق المصغّر. يتم تحديد حجم القائمة المنسدلة من خلال targetCellWidth وtargetCellHeight في حال تحديدهما، أو من خلال minWidth وminHeight في ملف معلومات موفّر التطبيقات المصغّرة.
يحدث ذلك لأنّ Android يعرض تلقائيًا الدوال المركّبة المرئية فقط في الحد الأدنى لحجم التطبيق المصغّر. بعبارة أخرى، يضبط Android السمة previewSizeMode على
SizeMode.Single تلقائيًا. ويستخدم android:minHeight وandroid:minWidth
في ملف XML الخاص بمعلومات موفّر التطبيقات المصغّرة لتحديد الدوال المركّبة التي سيتم رسمها.
لحلّ هذه المشكلة، يمكنك إلغاء السمة previewSizeMode في GlanceAppWidget وضبطها على
SizeMode.Responsive، مع تقديم مجموعة من قيم DpSize. يخبر هذا Android بجميع أحجام التخطيط التي يحتاج إلى عرضها للمعاينة، مما يضمن عرض جميع العناصر بشكل صحيح.
تحسين الأداء لأشكال أجهزة معيّنة أدخِل حجمًا واحدًا أو حجمَين بدءًا من الحد الأدنى
واتّبِع نقاط توقُّف التطبيق المصغّر. يُرجى تحديد سمة واحدة على الأقل من سمات
previewImage لإتاحة إصدارات Android الأقدم. يمكنك العثور على
الحد الأدنى المناسب لقيم DP لأحجام الشبكات المختلفة في
إرشادات تصميم التطبيقات المصغّرة.
التوافق مع إصدارات Android الأقدم
لعرض معاينات التطبيقات المصغّرة على الأجهزة التي تعمل بنظام التشغيل Android 14 والإصدارات الأقدم، أو عندما لا تتوفّر معاينة تم إنشاؤها على Android 15 والإصدارات الأحدث، حدِّد السمة previewImage.
إذا غيّرت مظهر التطبيق المصغّر، عليك تعديل صورة المعاينة.