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

تتيح شاشة 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 محددة، أو dps في حال تحديد minWidth وminHeight فقط. اطّلِع على سمات ضبط حجم التطبيقات المصغّرة.

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

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

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

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

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

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

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

مصادر إضافية

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