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

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

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

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

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

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

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

  • ينشئ النظام تلقائيًا AppWidgetHostView، ولكن يمكن للمضيف إنشاء فئة فرعية خاصة به من AppWidgetHostView من خلال تمديدها.
  • اعتبارًا من الإصدار 12 من Android (المستوى 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، يجب أن يعرض تطبيقك مربع حوار يطلب من المستخدم منح الإذن: "السماح" لإضافة التطبيق المصغّر الحالي، أو "السماح دائمًا" ليشمل ذلك جميع عمليات إضافة التطبيقات المصغّرة المستقبلية.

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

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)

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 فقط. اطّلِع على سمات ضبط حجم التطبيقات المصغّرة.

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

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

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

Android 12

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

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

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

مصادر إضافية

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