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

تتيح شاشة 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() لإلغاء تخصيص معرّف التطبيق المصغّر.

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

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

• تحدّد التطبيقات المصغّرة عرضًا وارتفاعًا تلقائيًا في AppWidgetProviderInfo البيانات الوصفية. يتم تحديد هذه القيم في الخلايا - بدءًا من Android 12، في حال توفُّر targetCellWidth وtargetCellHeight محددة، أو dps في حال تحديد 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 في ملف dps. وننصحك بأن تستخدم الأداة التي تستخدم واحدًا على الأقل من هذه الأدوات لا تتجاوز الحجم المحدد في السمات.

مصادر إضافية

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