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

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

    تأكَّد من تنسيق الأداة على الأقل بهذا العدد من dps. بالنسبة على سبيل المثال، يقوم العديد من المضيفين بمحاذاة الأيقونات والأدوات في شبكة. في هذا السيناريو، من خلال بشكل افتراضي، يضيف المضيف الأداة باستخدام الحد الأدنى من عدد الخلايا التي استيفاء قيود 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 المرجعية.