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

تجربة طريقة Compose

‫Jetpack Compose هي مجموعة أدوات واجهة المستخدِم المقترَحة لنظام التشغيل Android. تعرَّف على كيفية إنشاء التطبيقات المصغّرة باستخدام واجهات برمجة التطبيقات بنمط Compose.

Jetpack Glance →

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

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

للحصول على معلومات حول كيفية تصميم التطبيق المصغّر، اطّلِع على مقالة نظرة عامة على التطبيقات المصغّرة.

مكوّنات التطبيق المصغّر

لإنشاء تطبيق مصغّر، تحتاج إلى المكوّنات الأساسية التالية:

AppWidgetProviderInfo كائن

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

AppWidgetProvider فئة

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

عرض التصميم

يحدّد التنسيق الأولي للتطبيق المصغّر. يتم تحديد التنسيق في ملف XML، كما هو موضّح في هذا المستند.

يوضّح الشكل 2 كيف تتناسب هذه المكوّنات مع تدفق معالجة التطبيق المصغّر بشكل عام.

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

• بدءًا من Android 12 (المستوى 31 لواجهة برمجة التطبيقات)، يمكنك توفير إعدادات تلقائية والسماح للمستخدمين بإعادة ضبط التطبيق المصغّر لاحقًا. لمزيد من التفاصيل، اطّلِع على مقالتَي استخدام الإعدادات التلقائية للتطبيق المصغّر والسماح للمستخدمين بإعادة ضبط التطبيقات المصغّرة التي تم وضعها.
• في Android 11 (مستوى واجهة برمجة التطبيقات 30) أو الإصدارات الأقدم، يتم تشغيل هذا النشاط في كل مرة يضيف فيها المستخدم التطبيق المصغّر إلى الشاشة الرئيسية.

ننصحك أيضًا بإجراء التحسينات التالية: تنسيقات التطبيقات المصغّرة المرنة والتحسينات المتنوعة والتطبيقات المصغّرة المتقدّمة والتطبيقات المصغّرة للمجموعات وإنشاء مضيف تطبيق مصغّر.

تعريف ملف XML الخاص بـ AppWidgetProviderInfo

إنّ تحديد إعدادات البيانات الوصفية (مثل أحجام الخلايا التلقائية وقيود تغيير الحجم ووتيرة التحديث) متطابق تمامًا في كلٍّ من التطبيقات المصغّرة التقليدية المستندة إلى طرق العرض والتطبيقات المصغّرة المستندة إلى Glance.

للتعرّف على كيفية تعريف ملف XML الخاص بالبيانات الوصفية وضبطه، اطّلِع على قسم تعريف ملف XML الخاص بـ AppWidgetProviderInfo أولاً في Compose في مستندات Glance.

استخدام فئة AppWidgetProvider لمعالجة عمليات بث التطبيقات المصغّرة

يتم توحيد آليات أداة استقبال البث في النظام الأساسي وفلاتر تعريف ملف البيان وحلقات أحداث مراحل النشاط ضمن النظام الأساسي. في عملية التطوير التي تركز على Compose أولاً، يتم تنسيق عمليات البث هذه باستخدام برنامج تضمين GlanceAppWidgetReceiver.

للتعرّف على كيفية تسجيل أداة الاستقبال في ملف البيان وتنفيذ عمليات إلغاء مراحل النشاط المتوافقة مع Hilt، اطّلِع على قسم استخدام فئة AppWidgetProvider لمعالجة عمليات البث أولاً في Compose في مستندات Glance.

إنشاء تنسيق التطبيق المصغّر

عليك تحديد تنسيق أولي للتطبيق المصغّر في ملف XML وحفظه في دليل res/layout/ الخاص بالمشروع. اطّلِع على إرشادات التصميم للحصول على التفاصيل.

إنشاء تنسيق التطبيق المصغّر أمر بسيط إذا كنت على دراية بـ التنسيقات. ومع ذلك، يُرجى العِلم أنّ تنسيقات التطبيقات المصغّرة تستند إلى RemoteViews، التي لا تتوافق مع كل أنواع التنسيقات أو التطبيقات المصغّرة لطرق العرض. لا يمكنك استخدام طرق العرض المخصّصة أو الفئات الفرعية لطرق العرض التي تتوافق مع RemoteViews.

RemoteViews تتوافق أيضًا مع ViewStub، وهي View غير مرئية بحجم صفر يمكنك استخدامها لتوسيع موارد التنسيق بشكل مؤجل في وقت التشغيل.

التوافق مع السلوك الذي يحافظ على الحالة

يضيف Android 12 إمكانية المحافظة على الحالة باستخدام المكوّنات الحالية التالية:

• CheckBox

• Switch

• RadioButton

ما زال التطبيق المصغّر لا يحافظ على الحالة. يجب أن يخزّن تطبيقك الحالة وأن يسجّل أحداث تغيير الحالة.

يوضّح مثال الرمز البرمجي التالي كيفية تنفيذ هذه المكوّنات.

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
        R.id.my_checkbox,
        RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));

عليك توفير تنسيقَين: أحدهما يستهدف الأجهزة التي تعمل بنظام التشغيل Android 12 أو الإصدارات الأحدث في res/layout-v31، والآخر يستهدف الإصدارات السابقة من Android 11 أو الإصدارات الأقدم في مجلد res/layout التلقائي.

تنفيذ الزوايا المستديرة

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

لتنفيذ أشعة الزوايا أو إعداد الأنماط الديناميكية لأجهزة Android الأقدم، اطّلِع على قسم تنفيذ الزوايا المستديرة أولاً في Compose في مستندات Glance.