إضافة معاينات من إنشاء الذكاء الاصطناعي إلى أداة اختيار التطبيقات المصغّرة

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

لتحسين تجربة اختيار التطبيقات المصغّرة في تطبيقك، يمكنك توفير معاينة للتطبيق المصغّر الذي تم إنشاؤه على أجهزة Android 15 والإصدارات الأحدث، ومعاينة للتطبيق المصغّر تم تغيير حجمها (من خلال تحديد previewLayout) على أجهزة Android 12 إلى Android 14، وpreviewImage للإصدارات الأقدم.

لمزيد من المعلومات، يُرجى الاطّلاع على إثراء تطبيقك من خلال الإشعارات المباشرة والأدوات على YouTube.

إعداد تطبيقك لعرض معاينات التطبيقات المصغّرة التي يتم إنشاؤها

لعرض معاينات التطبيقات المصغّرة التي تم إنشاؤها على جهاز Android 15 أو إصدار أحدث، عليك أولاً ضبط قيمة compileSdk على 35 أو إصدار أحدث في ملف build.gradle الخاص بالوحدة لتتمكّن من تقديم RemoteViews إلى أداة اختيار التطبيقات المصغّرة.

يمكن للتطبيقات بعد ذلك استخدام setWidgetPreview في GlanceAppWidgetManager أو AppWidgetManager. لمنع إساءة الاستخدام والتخفيف من المخاوف بشأن سلامة النظام، setWidgetPreview هي واجهة برمجة تطبيقات محدودة المعدّل. الحدّ التلقائي هو حوالي طلبَين في الساعة.

إنشاء معاينة محدَّثة باستخدام Jetpack Glance

بالنسبة إلى التطبيقات المصغّرة التي تم إنشاؤها باستخدام Jetpack Glance، اتّبِع الخطوات التالية:

1. يمكنك إلغاء وظيفة GlanceAppWidget.providePreview لتوفير المحتوى القابل للإنشاء للمعاينات. كما تفعل في provideGlance، حمِّل بيانات تطبيقك ومرِّرها إلى العنصر القابل للإنشاء في المحتوى الخاص بالأداة، وذلك لضمان عرض بيانات دقيقة في المعاينة. على عكس provideGlance، هذا هو التكوين الفردي بدون إعادة تكوين أو تأثيرات.

2. استخدِم الأمر GlanceAppWidgetManager.setWidgetPreviews لإنشاء المعاينة ونشرها.

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

• إذا كانت الأداة تعرض معلومات ثابتة أو كانت عبارة عن إجراء سريع، اضبط المعاينة عند تشغيل التطبيق للمرة الأولى.
• يمكنك ضبط المعاينة بعد أن يتضمّن تطبيقك بيانات، مثلاً بعد أن يسجّل المستخدم الدخول أو يكمل عملية الإعداد الأولي.
• يمكنك إعداد مهمة دورية لتعديل المعاينات بمعدّل تكرار محدّد.

تحديد المشاكل وحلّها في "المعاينات من إنشاء الذكاء الاصطناعي"

من المشاكل الشائعة أنّه بعد إنشاء معاينة، قد لا تظهر الصور أو الرموز أو العناصر القابلة للإنشاء الأخرى في صورة المعاينة مقارنةً بحجم الإفلات الخاص بالأداة. يتم تحديد حجم النافذة المنبثقة من خلال targetCellWidth وtargetCellHeight إذا تم تحديدهما، أو من خلال minWidth وminHeight في ملف معلومات موفّر أدوات التطبيق.

ويحدث ذلك لأنّ نظام التشغيل Android يعرض تلقائيًا العناصر القابلة للإنشاء المرئية فقط عند الحد الأدنى لحجم التطبيق المصغّر. بمعنى آخر، يضبط نظام التشغيل Android قيمة previewSizeMode على SizeMode.Single تلقائيًا. يستخدم android:minHeight وandroid:minWidth في ملف XML الخاص بمعلومات موفّر أداة التطبيق لتحديد العناصر القابلة للإنشاء التي سيتم رسمها.

لحلّ هذه المشكلة، عليك إلغاء previewSizeMode في GlanceAppWidget وضبطها على SizeMode.Responsive، مع تقديم مجموعة من قيم DpSize. يخبر هذا الإعداد نظام التشغيل Android بجميع أحجام التصميمات التي يحتاج إلى عرضها للمعاينة، ما يضمن عرض جميع العناصر بشكل صحيح.

التحسين لأشكال أجهزة معيّنة قدِّم حجمًا واحدًا أو حجمَين بدءًا من الحد الأدنى واتّبِع نقاط التوقف الخاصة بالتطبيق المصغّر. حدِّد صورة واحدة على الأقل للتوافق مع الإصدارات القديمة. يمكنك العثور على الحد الأدنى المناسب لقيم DP لأحجام الشبكات المختلفة في إرشادات تصميم التطبيقات المصغّرة.

إنشاء معاينة محدَّثة بدون Jetpack Glance

يمكنك استخدام RemoteViews بدون ميزة "لمحة". يحمّل المثال التالي مصدرًا لتنسيق أداة XML ويضبطه كمعاينة. يجب أن يكون إعداد الإصدار compileSdk‏ 35 أو إصدارًا أحدث حتى يظهر setWidgetPreview كطريقة في هذا المقتطف.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    RemoteViews("com.example", R.layout.widget_preview)
)
AppWidgetSnippets.kt

إضافة معاينات قابلة لتغيير الحجم إلى أداة اختيار التطبيقات المصغّرة

بدءًا من الإصدار 12 من نظام التشغيل Android، يمكن تغيير حجم معاينة التطبيق المصغّر المعروضة في أداة اختيار التطبيقات المصغّرة. يمكنك توفيرها كمجموعة تخطيط XML تم ضبطها على الحجم التلقائي للأداة. في السابق، كانت معاينة التطبيق المصغّر عبارة عن مورد رسومي ثابت، ما كان يؤدي في بعض الحالات إلى عدم دقة المعاينات في عرض شكل التطبيقات المصغّرة عند إضافتها إلى الشاشة الرئيسية.

لتنفيذ معاينات قابلة لتغيير الحجم للأدوات، استخدِم السمة previewLayout للعنصر appwidget-provider من أجل توفير تنسيق XML بدلاً من ذلك:

<appwidget-provider
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

ننصحك باستخدام التنسيق نفسه الخاص بالأداة الفعلية، مع قيم تلقائية أو قيم اختبار واقعية. تستخدم معظم التطبيقات previewLayout وinitialLayout نفسيهما. للحصول على إرشادات حول إنشاء تخطيطات معاينة دقيقة، راجِع القسم التالي في هذه الصفحة.

ننصحك بتحديد السمتَين previewLayout وpreviewImage معًا، ليتمكّن تطبيقك من استخدام previewImage إذا كان جهاز المستخدم لا يتوافق مع previewLayout. تحظى السمة previewLayout بالأولوية على السمة previewImage.

التوافق مع الإصدارات السابقة لمعاينات التطبيقات المصغّرة

للسماح لأدوات اختيار التطبيقات المصغّرة على الإصدار 11 من نظام التشغيل Android (المستوى 30 لواجهة برمجة التطبيقات) أو الإصدارات الأقدم بعرض معاينات للتطبيق المصغّر، أو كبديل للمعاينات التي تم إنشاؤها، حدِّد السمة previewImage.

في حال تغيير مظهر الأداة، عليك تعديل صورة المعاينة.

إنشاء معاينات دقيقة تتضمّن عناصر ديناميكية

يوضّح هذا القسم الطريقة المقترَحة لعرض عناصر متعدّدة في معاينة تطبيق مصغّر يتضمّن عرض مجموعة، أي تطبيق مصغّر يستخدم ListView أو GridView أو StackView. لا ينطبق ذلك على معاينات التطبيقات المصغّرة التي يتم إنشاؤها تلقائيًا.

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

لضمان عرض معاينات التطبيقات المصغّرة التي تتضمّن طرق عرض المجموعات بشكل سليم في أداة اختيار التطبيقات المصغّرة، ننصحك بالاحتفاظ بملف تنسيق منفصل مخصّص للمعاينات فقط. يجب أن يتضمّن ملف التصميم المنفصل ما يلي:

• تنسيق التطبيق المصغّر الفعلي
• طريقة عرض مجموعة العناصر النائبة التي تتضمّن عناصر وهمية على سبيل المثال، يمكنك محاكاة ListView من خلال توفير عنصر نائب LinearLayout يتضمّن عدة عناصر قائمة وهمية.

لتوضيح مثال على ListView، ابدأ بملف تنسيق منفصل:

// res/layout/widget_preview.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
   android:layout_width="match_parent"
   android:layout_height="wrap_content"
   android:background="@drawable/widget_background"
   android:orientation="vertical">

    // Include the actual widget layout that contains ListView.
    <include
        layout="@layout/widget_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    // The number of fake items you include depends on the values you provide
    // for minHeight or targetCellHeight in the AppWidgetProviderInfo
    // definition.

    <TextView android:text="@string/fake_item1"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

    <TextView android:text="@string/fake_item2"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

</LinearLayout>

حدِّد ملف تنسيق المعاينة عند تقديم السمة previewLayout للبيانات الوصفية AppWidgetProviderInfo. سيظل بإمكانك تحديد تنسيق الأداة الفعلي لسمة initialLayout واستخدام تنسيق الأداة الفعلي عند إنشاء RemoteViews في وقت التشغيل.

<appwidget-provider
    previewLayout="@layout/widget_previe"
    initialLayout="@layout/widget_view" />

عناصر القائمة المعقّدة

يقدّم المثال في القسم السابق عناصر قائمة وهمية، لأنّ عناصر القائمة هي كائنات TextView. قد يكون من الصعب توفير عناصر مزيفة إذا كانت العناصر عبارة عن تنسيقات معقّدة.

لنفترض عنصر قائمة محدّدًا في widget_list_item.xml ويتألف من كائنَين من النوع TextView:

<LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">

    <TextView android:id="@id/title"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/fake_title" />

    <TextView android:id="@id/content"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/fake_content" />
</LinearLayout>

لتوفير عناصر قائمة وهمية، يمكنك تضمين التصميم عدة مرات، ولكن يؤدي ذلك إلى أن يكون كل عنصر من عناصر القائمة مطابقًا للعناصر الأخرى. لتقديم عناصر فريدة في القائمة، اتّبِع الخطوات التالية:

1. أنشئ مجموعة من السمات لقيم النص:

   <resources>
       <attr name="widgetTitle" format="string" />
       <attr name="widgetContent" format="string" />
   </resources>
   

2. استخدِم هذه السمات لضبط النص:

   <LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
           android:layout_width="match_parent"
           android:layout_height="wrap_content">
   
       <TextView android:id="@id/title"
           android:layout_width="match_parent"
           android:layout_height="wrap_content"
           android:text="?widgetTitle" />
   
       <TextView android:id="@id/content"
           android:layout_width="match_parent"
           android:layout_height="wrap_content"
           android:text="?widgetContent" />
   </LinearLayout>
   

3. أنشئ العدد الذي تريده من الأنماط لمعاينة المحتوى. أعِد تحديد القيم في كل نمط:

   <resources>
   
       <style name="Theme.Widget.ListItem">
           <item name="widgetTitle"></item>
           <item name="widgetContent"></item>
       </style>
       <style name="Theme.Widget.ListItem.Preview1">
           <item name="widgetTitle">Fake Title 1</item>
           <item name="widgetContent">Fake content 1</item>
       </style>
       <style name="Theme.Widget.ListItem.Preview2">
           <item name="widgetTitle">Fake title 2</item>
           <item name="widgetContent">Fake content 2</item>
       </style>
   
   </resources>
   

4. طبِّق الأنماط على العناصر الوهمية في تخطيط المعاينة:

   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
      android:layout_width="match_parent"
      android:layout_height="wrap_content" ...>
   
       <include layout="@layout/widget_view" ... />
   
       <include layout="@layout/widget_list_item"
           android:theme="@style/Theme.Widget.ListItem.Preview1" />
   
       <include layout="@layout/widget_list_item"
           android:theme="@style/Theme.Widget.ListItem.Preview2" />
   
   </LinearLayout>