إنشاء مضيف تطبيق مصغّر

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

تركّز هذه الصفحة على المسؤوليات التي ينطوي عليها تنفيذ علامة AppWidgetHost مخصّصة. للاطّلاع على مثال محدّد حول كيفية تنفيذ AppWidgetHost، اطّلِع على رمز المصدر لشاشة Android الرئيسية LauncherAppWidgetHost.

في ما يلي نظرة عامة على الفئات والمفاهيم الأساسية المستخدَمة في تنفيذ AppWidgetHost مخصّصة:

• مضيف أداة التطبيق: يوفّر AppWidgetHost التفاعل مع خدمة AppWidget للتطبيقات التي تضمّن الأدوات في واجهة المستخدم. يجب أن يكون للحقل AppWidgetHost معرّف فريد ضمن حزمة المضيف الخاصة. ويستمر رقم التعريف هذا في جميع استخدامات المضيف. عادةً ما يكون المعرّف عبارة عن قيمة ذات ترميز ثابت تخصصه في تطبيقك.

• رقم تعريف التطبيق المصغّر: يتم تخصيص رقم تعريف فريد لكل مثيل للتطبيق المصغّر في وقت الربط. يمكنك الاطّلاع على bindAppWidgetIdIfAllowed() لمزيد من التفاصيل، يمكنك الاطّلاع على قسم التطبيقات المصغّرة للربط التالي. ويحصل المضيف على المعرّف الفريد باستخدام allocateAppWidgetId(). ويبقى رقم التعريف هذا صالحًا طوال مدة عمل الأداة إلى أن يتم حذفه من المضيف. يجب الاحتفاظ بأي حالة خاصة بالمضيف، مثل حجم الأداة وموقعها، من خلال حزمة الاستضافة وربطها بمعرّف التطبيق المصغَّر للتطبيق.

• عرض مضيف تطبيق مصغّر: يمكنك اعتبار AppWidgetHostView إطارًا يتم التفاف التطبيق المصغّر فيه كلما احتاجت إلى عرضه. يتم ربط تطبيق مصغّر بـ AppWidgetHostView في كل مرة يضخّم فيها المضيف الأداة.

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

• حزمة الخيارات: تستخدم AppWidgetHost حزمة الخيارات لإيصال معلومات إلى AppWidgetProvider حول كيفية عرض الأداة، مثل قائمة نطاقات الحجم وما إذا كانت الأداة على شاشة القفل أم على الشاشة الرئيسية. تتيح هذه المعلومات لـ AppWidgetProvider تخصيص محتوى التطبيق المصغّر ومظهره استنادًا إلى طريقة ومكان عرضه. يمكنك استخدام updateAppWidgetOptions() وupdateAppWidgetSize() لتعديل حزمة أداة. تؤدي هاتان الطريقتان إلى رد استدعاء onAppWidgetOptionsChanged() إلى AppWidgetProvider.

ربط التطبيقات المصغّرة

عندما يضيف مستخدم أداة إلى المضيف، تحدث عملية تُسمى الربط. يشير الربط إلى ربط معرّف تطبيق مصغّر بمضيف محدّد وAppWidgetProvider محدّد.

تتيح واجهات برمجة التطبيقات للربط أيضًا للمضيف توفير واجهة مستخدم مخصّصة للربط. لاستخدام هذه العملية، يجب أن يتضمّن تطبيقك بيانًا بإذن BIND_APPWIDGET في بيان المضيف:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

ولكن هذه ليست سوى الخطوة الأولى. في وقت التشغيل، يجب أن يمنح المستخدم إذنًا صريحًا لتطبيقك للسماح له بإضافة أداة إلى المضيف. لاختبار ما إذا كان تطبيقك يملك الإذن بإضافة الأداة، استخدِم الطريقة bindAppWidgetIdIfAllowed(). إذا عرض bindAppWidgetIdIfAllowed() الرمز false، يجب أن يعرض تطبيقك مربّع حوار يطلب من المستخدم منح الإذن: "السماح" لإضافة الأداة الحالية أو "السماح دائمًا" لتغطية جميع إضافات التطبيقات المصغّرة المستقبلية.

يقدّم هذا المقتطف مثالاً على كيفية عرض مربّع الحوار:

Kotlin

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

Java

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

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

مسؤوليات المضيف

يمكنك تحديد عدد من إعدادات الضبط للتطبيقات المصغّرة باستخدام بيانات AppWidgetProviderInfo الوصفية. يمكنك استرداد خيارات الإعداد هذه، التي يتم تناولها بمزيد من التفاصيل في الأقسام التالية، من عنصر AppWidgetProviderInfo المرتبط بموفِّر التطبيقات المصغّرة.

بغض النظر عن إصدار Android الذي تستهدفه، تقع على عاتق جميع المضيفين المسؤوليات التالية:

• عند إضافة أداة، خصِّص معرّفها كما هو موضّح سابقًا. عند إزالة أداة من المضيف، استدعاء deleteAppWidgetId() لتخصيص معرّف الأداة.

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

  ملاحظة: التعامل مع الحالات غير المنتظمة التي لا يظهر فيها نشاط الضبط أو ينتهي فيه مع حدوث أخطاء.

• تحدّد التطبيقات المصغّرة عرضًا وارتفاعًا تلقائيين في البيانات الوصفية AppWidgetProviderInfo. يتم تحديد هذه القيم في الخلايا، بدءًا من نظام التشغيل Android 12، في حال تحديد targetCellWidth وtargetCellHeight، أو عدد النقاط لكل ثانية في حال تحديد minWidth وminHeight فقط. يُرجى الاطّلاع على سمات حجم التطبيقات المصغّرة.

  تأكَّد من تنسيق الأداة على الأقل بهذا العدد من dps. على سبيل المثال، يقوم العديد من المضيفين بمحاذاة الأيقونات والأدوات في شبكة. في هذا السيناريو، يضيف المضيف تلقائيًا الأداة باستخدام الحد الأدنى من عدد الخلايا التي تلبي قيود minWidth وminHeight.

بالإضافة إلى المتطلبات المذكورة في القسم السابق، تقدّم إصدارات محددة من المنصات ميزات تضع مسؤوليات جديدة على المضيف.

تحديد أسلوبك استنادًا إلى إصدار Android المستهدَف

الإصدار 12 من نظام التشغيل Android

يوفّر Android 12 (المستوى 31 لواجهة برمجة التطبيقات) حزمة List<SizeF> إضافية تحتوي على قائمة بالأحجام المحتملة dps التي يمكن أن يتخذها مثيل أداة في حزمة الخيارات. ويعتمد عدد الأحجام المقدّمة على تنفيذ المضيف. يوفر المضيفون عادةً حجمين للهواتف، رأسي وأفقي، وأربعة أحجام للأجهزة القابلة للطي.

ويمكن استخدام MAX_INIT_VIEW_COUNT (16) كحدّ أقصى لعدد RemoteViews المختلفة التي يمكن للسمة AppWidgetProvider تقديمها إلى RemoteViews. بما أنّ عناصر AppWidgetProvider تربط كائن RemoteViews بكل حجم في List<SizeF>، يجب عدم تحديد أكثر من MAX_INIT_VIEW_COUNT مقاس.

يقدّم Android 12 أيضًا السمتَين maxResizeWidth وmaxResizeHeight بالوحدة البوصة في الثانية. ننصح بأن لا يتجاوز التطبيق المصغّر الذي يستخدم واحدة على الأقل من هذه السمات الحجم المحدّد بواسطة السمات.

مصادر إضافية

• اطّلِع على مستندات Glance المرجعية.