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

تجربة طريقة "الكتابة"

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

‫Jetpack Glance →

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

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

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

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

لإنشاء أداة، يجب توفُّر المكوّنات الأساسية التالية:

عنصر AppWidgetProviderInfo

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

AppWidgetProvider صف

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

عرض التصميم

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

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

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

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

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

تعريف ملف AppWidgetProviderInfo XML

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

للتعرّف على كيفية تحديد ملف XML الخاص بالبيانات الوصفية وإعداده، راجِع قسم تعريف قسم XML الخاص بـ AppWidgetProviderInfo في مستندات Compose-first على Glance.

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

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

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

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

يجب تحديد تصميم أولي للأداة في 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));

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

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

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

لتنفيذ نصف قطر الزوايا أو إعداد أنماط ديناميكية لأجهزة Android القديمة، راجِع قسم تنفيذ الزوايا الدائرية في مستندات Glance حول Compose-first.