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

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

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

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

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

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

مصادر إضافية

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