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