تتيح لك معاينات التطبيقات المصغّرة التي تم إنشاؤها إنشاء معاينات ديناميكية ومخصّصة لتطبيقاتك المصغّرة تعكس بدقة طريقة ظهورها على الشاشة الرئيسية للمستخدم. يتم توفيرها من خلال واجهة برمجة تطبيقات لإرسال البيانات، ما يعني أنّ تطبيقك يقدّم المعاينة في أي وقت خلال دورة حياته بدون تلقّي طلب صريح من مضيف التطبيق المصغّر.
يتناول هذا الدليل كيفية تقديم معاينات للتطبيقات المصغّرة المستندة إلى Glance. إذا تم تنفيذ تطبيقك المصغّر باستخدام RemoteViews، يُرجى الاطّلاع على مقالة إضافة معاينات إلى أداة اختيار التطبيقات المصغّرة.
لتحسين تجربة أداة اختيار التطبيقات المصغّرة في تطبيقك لتطبيقات Glance المصغّرة، يمكنك تقديم معاينة تم إنشاؤها باستخدام GlanceAppWidget.providePreview على
أجهزة Android 15 والإصدارات الأحدث، وتحديد previewImage
للإصدارات السابقة، وكحلّ احتياطي على Android 15 والإصدارات الأحدث في حال عدم توفّر معاينة تم إنشاؤها.
لمزيد من المعلومات، يُرجى الاطّلاع على إثراء تطبيقك من خلال التحديثات المباشرة والتطبيقات المصغّرة على YouTube.
إعداد تطبيقك لمعاينات التطبيقات المصغّرة التي تم إنشاؤها
لعرض معاينات التطبيقات المصغّرة التي تم إنشاؤها على جهاز Android 15 أو إصدار أحدث، عليك أولاً ضبط
compileSdk قيمة على 35 أو إصدار أحدث في build.gradle الخاص بالوحدة لتتمكّن من تقديم RemoteViews إلى أداة اختيار التطبيقات المصغّرة.
يمكن للتطبيقات بعد ذلك استخدام 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 15 بعرض معاينات لتطبيقك المصغّر، أو كحلّ احتياطي للمعاينات التي تم إنشاؤها على Android 15 والإصدارات الأحدث، عليك تحديد السمة
previewImage.
إذا غيّرت مظهر التطبيق المصغّر، عليك تعديل صورة المعاينة.