تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

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

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.provider)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)Host.kt

يجب أن يتحقّق المضيف مما إذا كان التطبيق المصغّر الذي يضيفه المستخدم يحتاج إلى ضبط. لمزيد من المعلومات، يُرجى الاطّلاع على السماح للمستخدمين بضبط تطبيقات مصغّرة.

مسؤوليات المضيف

يمكنك تحديد عدد من إعدادات الضبط للأدوات باستخدام البيانات الوصفية AppWidgetProviderInfo. يمكنك استرداد خيارات الضبط هذه، والتي يتم تناولها بمزيد من التفصيل في الأقسام التالية، من الكائن AppWidgetProviderInfo المرتبط بموفّر التطبيقات المصغّرة.

يتحمّل جميع المضيفين المسؤوليات التالية:

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

ملاحظة: يجب معالجة الحالات غير المنتظمة التي لا يعرض فيها نشاط الضبط أي نتائج أو ينتهي بأخطاء.
تحدّد التطبيقات المصغّرة العرض والارتفاع التلقائيين في البيانات الوصفية AppWidgetProviderInfo. يتم تحديد هذه القيم في الخلايا، بدءًا من الإصدار Android 12، في حال تحديد targetCellWidth وtargetCellHeight، أو في وحدات بكسل مستقلة الكثافة في حال تحديد minWidth وminHeight فقط. يُرجى الاطّلاع على سمات حجم التطبيق المصغّر.

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

نصائح حول نهجك

بالإضافة إلى المتطلبات المذكورة في القسم السابق، ضع في اعتبارك النصائح التالية:

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

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

عندما تحدّد التطبيقات المصغّرة السمتَين maxResizeWidth وmaxResizeHeight بوحدة بكسل مستقلة الكثافة (dp)، ننصح بأنّ لا يتجاوز حجم التطبيق المصغّر الذي يستخدم إحدى هاتين السمتَين على الأقل الحجم المحدّد في السمتَين.

مراجع إضافية

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