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

تتيح الشاشة الرئيسية على 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، أو بوحدات dp إذا تم تحديد minWidth وminHeight فقط. يُرجى الاطّلاع على سمات تغيير حجم الأداة.

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

بالإضافة إلى المتطلبات المُدرَجة في القسم السابق، تقدّم إصدارات معيّنة من النظام ميزات تفرض مسؤوليات جديدة على المضيف.

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

Android 12

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

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

يقدّم Android 12 أيضًا سمتَي maxResizeWidth و maxResizeHeight بوحدات dp. ننصح بأن لا تتجاوز الأداة التي تستخدم إحدى هاتَين السمتَين على الأقل الحجم المحدّد من خلال السمتَين.

مراجع إضافية

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