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

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

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

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

إضافة معاينات من إنشاء الذكاء الاصطناعي

لعرض معاينات التطبيقات المصغّرة التي تم إنشاؤها على جهاز يعمل بالإصدار 15 من نظام التشغيل Android أو الإصدارات الأحدث، عليك أولاً ضبط قيمة 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.

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

للسماح لأدوات اختيار التطبيقات المصغّرة على الإصدار 11 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 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>