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

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

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

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

إضافة المعاينات التي تم إنشاؤها

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

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

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

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

يحمّل المثال التالي مورد تصميم لملف 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

إضافة معاينات قابلة للتكيّف للتطبيقات المصغّرة

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

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

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

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

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

إضافة معاينات ثابتة للتطبيقات المصغّرة من أجل التوافق مع الأنظمة القديمة

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

إذا غيّرت مظهر التطبيق المصغّر، عليك تعديل صورة المعاينة.

تُستخدم هذه السمة أيضًا كخيار احتياطي للمعاينة التي يتم إنشاؤها إذا لم تضبط واحدة باستخدام setWidgetPreview.

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

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

إذا كان التطبيق المصغّر يستخدم إحدى طرق العرض هذه، فإنّ إنشاء معاينة قابلة للتوسيع من خلال توفير تنسيق التطبيق المصغّر الفعلي مباشرةً في previewLayout يمكن أن يؤدي إلى تراجع التجربة عندما لا تعرض معاينة التطبيق المصغّر أي عناصر. يحدث هذا لأنّ بيانات عرض المجموعة يتم ضبطها ديناميكيًا في وقت التشغيل، وتبدو مشابهة للصورة الموضّحة في الشكل 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_preview"
    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>