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

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

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

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

تحديد النهج استنادًا إلى إصدار Android المستهدَف

‫Android 12

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

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

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

مراجع إضافية

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