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

تتيح شاشة 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 المستهدَف

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

يتضمّن نظام 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 بوحدات الكثافة في الثانية. وننصحك بألا يتجاوز حجم التطبيق المصغّر الذي يستخدم سمة واحدة على الأقل من هذه السمات المقاس المحدد في السمات.

مراجع إضافية

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