تحسين تطبيقك المصغّر

تجربة طريقة "الكتابة"
‫Jetpack Compose هي مجموعة أدوات واجهة المستخدم التي يُنصح باستخدامها على Android. تعرَّف على كيفية إنشاء أدوات باستخدام واجهات برمجة التطبيقات المتوافقة مع Compose.
Jetpack Glance →

تتضمّن هذه الصفحة تفاصيل حول تحسينات اختيارية على التطبيقات المصغّرة متاحة بدءًا من نظام التشغيل Android 12 (المستوى 31 لواجهة برمجة التطبيقات). هذه الميزات اختيارية، ولكنّها سهلة التنفيذ وتساعد في تحسين تجربة المستخدمين مع التطبيق المصغّر.

استخدام الألوان الديناميكية

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

هناك طريقتان للحصول على ألوان ديناميكية:

بعد ضبط السمة في التصميم الأساسي، يمكنك استخدام سمات الألوان الشائعة في التصميم الأساسي أو أي من العناصر التابعة له لاختيار الألوان الديناميكية.

في ما يلي بعض الأمثلة على سمات الألوان التي يمكنك استخدامها:

  • ?attr/primary
  • ?attr/primaryContainer
  • ?attr/onPrimary
  • ?attr/onPrimaryContainer

في المثال التالي الذي يستخدم مظهر Material 3، يكون لون مظهر الجهاز "أرجوانيًا". يتم ضبط لون التمييز وخلفية الأداة لتناسب الوضعَين الفاتح والداكن، كما هو موضّح في الشكلَين 1 و2.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="?attr/colorPrimaryContainer"
  android:theme="@style/Theme.Material3.DynamicColors.DayNight">

  <ImageView
    ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />

    <!-- Other widget content. -->

</LinearLayout>
التطبيق المصغّر بمظهر فاتح
الشكل 1. تطبيق مصغّر بمظهر فاتح
التطبيقات المصغّرة في المظهر الداكن
الشكل 2. أداة بمظهر داكن

التوافق مع الإصدارات السابقة للألوان الديناميكية

لا تتوفّر الألوان الديناميكية إلا على الأجهزة التي تعمل بالإصدار 12 من نظام التشغيل Android أو الإصدارات الأحدث. لتوفير مظهر مخصّص للإصدارات الأقدم، أنشئ مظهرًا تلقائيًا بألوانك المخصّصة ومحدّدًا جديدًا (values-v31) باستخدام سمات المظهر التلقائي.

في ما يلي مثال على استخدام تصميم Material 3:

/values/styles.xml

<resources>
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    <!-- Override default colorBackground attribute with custom color. -->
    <item name="android:colorBackground">@color/my_background_color</item>

    <!-- Add other colors/attributes. -->

  </style>
</resources>

/values-v31/styles.xml

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

/layout/my_widget_layout.xml

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

تفعيل ميزة "التحكّم الصوتي"

تتيح إجراءات التطبيقات لمساعد Google عرض أدوات استجابةً لطلبات صوتية ذات صلة من المستخدمين. من خلال ضبط إعدادات تطبيقك المصغّر للاستجابة لطلبات البحث المضمّنة (BII)، يمكن لتطبيقك عرض التطبيقات المصغّرة بشكل استباقي على مساحات عرض "مساعد Google"، مثل Android وAndroid Auto. يمكن للمستخدمين تثبيت التطبيقات المصغّرة التي يعرضها "مساعد Google" على مشغّل التطبيقات، ما يشجّع على التفاعل في المستقبل.

على سبيل المثال، يمكنك ضبط أداة ملخّص التمارين الرياضية لتطبيق التمارين الرياضية لتنفيذ الأوامر الصوتية التي يطلقها المستخدمون والتي تؤدي إلى تشغيل GET_EXERCISE_OBSERVATION BII. يعرض "مساعد Google" تطبيقك المصغّر بشكل استباقي عندما يفعّل المستخدمون هذه النية المضمّنة في التطبيق من خلال تقديم طلبات مثل "Ok Google، كم عدد الكيلومترات التي قطعتها هذا الأسبوع باستخدام ExampleApp؟"

تتوفّر عشرات واجهات BII التي تغطي عدة فئات من تفاعلات المستخدمين، ما يتيح لأي تطبيق Android تقريبًا تحسين أدواته المصغّرة لتتوافق مع التفاعل الصوتي. للبدء، راجِع دمج "إجراءات التطبيقات" مع أدوات Android.

تحسين تجربة اختيار التطبيقات المصغّرة في تطبيقك

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

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

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

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

يمكن للتطبيقات استخدام طرق AppWidgetManager وsetWidgetPreview وgetWidgetPreview لتعديل مظهر التطبيقات المصغّرة باستخدام معلومات حديثة ومخصّصة.

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

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

يستخدم المثال التالي Jetpack Glance لإنشاء معاينة معدَّلة. يجب أن يكون إعداد الإصدار compileSdk 35 أو إصدارًا أحدث لكي يظهر setWidgetPreview كطريقة في هذا المقتطف.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    ExampleAppWidget().compose(
        context = appContext
    ),
)

AppWidgetSnippets.kt

إنشاء معاينة محدَّثة بدون 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.

الطُرق المقترَحة لإنشاء معاينات دقيقة

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

<appwidget-provider
    ...
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
صورة تعرض معاينة لتطبيق مصغّر
الشكل 3. معاينة أداة تظهر تلقائيًا في مساحة 3x3، ولكن يمكن أن تتناسب مع مساحة 3x1 بسبب تصميم XML الخاص بها

لعرض معاينة دقيقة، يمكنك تقديم تخطيط الأداة الفعلي مباشرةً مع القيم التلقائية من خلال إكمال الخطوات التالية:

  • ضبط android:text="@string/my_widget_item_fake_1" لعناصر TextView

  • ضبط صورة أو رمز تلقائي أو عنصر نائب، مثل android:src="@drawable/my_widget_icon"، لمكوّنات ImageView

بدون قيم تلقائية، قد تعرض المعاينة قيمًا غير صحيحة أو فارغة. من المزايا المهمة لهذا الأسلوب أنّه يتيح لك تقديم محتوى معاينة مترجم.

للاطّلاع على الطرق المقترَحة لمعاينات أكثر تعقيدًا تحتوي على ListView أو GridView أو StackView، راجِع إنشاء معاينات دقيقة تتضمّن عناصر ديناميكية للحصول على التفاصيل.

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

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

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

إضافة اسم إلى التطبيق المصغّر

يجب أن يكون للأدوات اسم فريد عند عرضها في أداة اختيار الأدوات.

يتم تحميل أسماء التطبيقات المصغّرة من السمة label لعنصر receiver التطبيق المصغّر في ملف AndroidManifest.xml.

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

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

بدءًا من نظام التشغيل Android 12، يجب تقديم وصف لأداة اختيار التطبيقات المصغّرة ليتم عرضه مع التطبيق المصغّر.

صورة تعرض أداة اختيار الأدوات مع أداة ووصفها
الشكل 4. نموذج لأداة اختيار التطبيقات المصغّرة يعرض تطبيقًا مصغّرًا ووصفه

قدِّم وصفًا للأداة باستخدام السمة description الخاصة بالعنصر &lt;appwidget-provider&gt;:

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

يمكنك استخدام السمة descriptionRes في الإصدارات السابقة من Android، ولكن يتجاهلها منتقي التطبيقات المصغّرة.

تفعيل عمليات الانتقال الأكثر سلاسة

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

لتفعيل هذا الانتقال المحسّن، استخدِم @android:id/background أو android.R.id.background لتحديد عنصر الخلفية:

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

يمكن لتطبيقك استخدام الإذن @android:id/background على الإصدارات السابقة من Android بدون حدوث أي مشاكل، ولكن سيتم تجاهله.

استخدام تعديل RemoteViews في وقت التشغيل

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

يوضّح مثال الرمز البرمجي التالي كيفية استخدام بعض هذه الطرق.

Kotlin

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList())

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)

Java

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList());

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);