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

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

مثال على تطبيق الموسيقى المصغّر
الشكل 1. مثال على تطبيق مصغّر للموسيقى

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

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

مكونات الأداة

لإنشاء أداة، تحتاج إلى المكونات الأساسية التالية:

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

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

مسار معالجة أداة التطبيق
الشكل 2. عملية معالجة التطبيق المصغّر

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

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

يُرجى تعريف ملف AppWidgetProviderInfo XML.

يحدّد الكائن AppWidgetProviderInfo الصفات الأساسية للتطبيق المصغّر. تحديد عنصر AppWidgetProviderInfo في ملف مورد XML باستخدام عنصر واحد عنصر <appwidget-provider> وحفظه في مجلد res/xml/ الخاص بالمشروع

يظهر ذلك في المثال التالي:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/example_loading_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

سمات حجم التطبيق المصغّر

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

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

ويوضّح الجدول التالي سمات <appwidget-provider> المتعلقة لتغيير حجم الأداة:

السمات والوصف
targetCellWidth و targetCellHeight (نظام التشغيل Android 12)، minWidth وminHeight
  • بدءًا من نظام التشغيل Android 12، targetCellWidth وtargetCellHeight السمات التي تحدد الحجم التلقائي للتطبيق المصغّر من حيث الشبكة الخلايا. يتم تجاهل هذه السمات في Android 11 وأقل ويمكن تجاهلها إذا لم يتم ذلك إذا لم يتم تنشيط الشاشة الرئيسية تدعم تخطيطًا قائمًا على الشبكة.
  • يعمل minWidth تحدد سمات minHeight الحجم التلقائي للأداة بتنسيق dp. إذا لم تتطابق قيم الحد الأدنى لعرض التطبيق المصغّر أو ارتفاعه أبعاد الخلايا، ثم يتم تقريب القيم إلى لأقرب حجم للخلية.
نقترح تحديد كلتا المجموعتين السمات - targetCellWidth targetCellHeight وminWidth minHeight: ليتمكّن تطبيقك من العودة إلى استخدام minWidth وminHeight إذا كان جهاز المستخدم لا يتوافق مع targetCellWidth targetCellHeight إذا كان ذلك متاحًا، السمتان targetCellWidth وtargetCellHeight لها الأولوية على minWidth وminHeight ذات الصلة.
minResizeWidth و minResizeHeight حدِّد الحد الأدنى المطلق لحجم الأداة. تحدد هذه القيم الحجم الذي يكون فيه التطبيق المصغّر غير مقروء أو غير قابل للاستخدام بأي شكل آخر. استخدام تتيح هذه السمات للمستخدم تغيير حجم الأداة إلى حجم أصغر مقارنةً بحجم التطبيق المصغّر التلقائي السمة minResizeWidth هي وسيتم تجاهله إذا كانت أكبر من minWidth أو إذا كان أفقيًا ميزة تغيير الحجم غير مفعّلة. عرض resizeMode وبالمثل، يتم تجاهل السمة minResizeHeight إذا كانت أكبر من minHeight أو إذا لم يتم تفعيل تغيير الحجم العمودي.
maxResizeWidth و maxResizeHeight حدِّد الحجم الأقصى المُقترَح للأداة. إذا لم تكن القيم مضاعفات أبعاد خلية الشبكة، يتم تقريبها إلى أقرب وحجم الخلية. يتم تجاهل السمة maxResizeWidth إذا كانت: أصغر من minWidth أو إذا لم يتم تغيير الحجم الأفقي مفعّلة. يمكنك الاطّلاع على resizeMode. وبالمثل، يتم تجاهل السمة maxResizeHeight إذا كانت أكبر. من minHeight أو في حال عدم تفعيل تغيير الحجم العمودي. تم طرح هذه الميزة في نظام التشغيل Android 12.
resizeMode تحدّد القواعد التي يمكن من خلالها تغيير حجم أداة. يمكنك استخدام هذه الصفحة لجعل أدوات الشاشة الرئيسية قابلة لتغيير الحجم أفقيًا أو رأسيًا، أو على كلا المحورين. لمس المستخدمون & مع الاستمرار في الضغط على أداة لعرض مقابض تغيير الحجم الخاصة بها ثم اسحب المقابض الأفقية أو الرأسية لتغيير حجمها على شبكة التخطيط. تشمل قيم السمة resizeMode ما يلي: horizontal وvertical وnone إلى الإعلان عن إمكانية تغيير حجم الأداة أفقيًا وعموديًا، واستخدام horizontal|vertical

مثال

لتوضيح كيفية تأثير السمات الواردة في الجدول السابق على حجم التطبيق المصغّر، افتراض المواصفات التالية:

  • يبلغ عرض خلية الشبكة 30 وحدة بكسل مستقلة الكثافة وطولها 50 بكسل مستقل الكثافة.
  • يتم تقديم مواصفات السمات التالية:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

بدءًا من نظام التشغيل Android 12:

استخدام السمتَين targetCellWidth وtargetCellHeight كإعداد تلقائي حجم التطبيق المصغّر.

يكون حجم الأداة 2x2 افتراضيًا. يمكن تغيير حجم الأداة إلى 2×1 أو بمعدل يصل إلى 4x3.

نظام التشغيل Android 11 والإصدارات الأقدم:

استخدِم السمتَين minWidth وminHeight لاحتساب الحجم التلقائي الأداة.

العرض التلقائي = Math.ceil(80 / 30) = 3

الارتفاع التلقائي = Math.ceil(80 / 50) = 2

يكون حجم الأداة 3×2 افتراضيًا. يمكن تغيير حجم الأداة إلى 2×1 أو إلى وضع ملء الشاشة.

السمات الإضافية للأداة

ويوضّح الجدول التالي سمات <appwidget-provider> المتعلقة إلى ميزات أخرى غير حجم الأداة.

السمات والوصف
updatePeriodMillis تحدد عدد المرات التي يطلب فيها إطار العمل المصغّر تحديثًا من AppWidgetProvider من خلال الاتصال بـ onUpdate() . فليس من المضمون أن يحدث التحديث الفعلي في هذه القيمة، وننصحك بالتحديث بشكل نادر ممكن - ليس أكثر من مرة في الساعة - للحفاظ على البطارية. للحصول على القائمة الكاملة بالاعتبارات لاختيار فترة تحديث مناسبة، الرؤية تحسينات لتحديث التطبيق المصغَّر المحتوى.
initialLayout يشير إلى مورد التنسيق الذي يحدِّد تنسيق الأداة.
configure تُحدد النشاط الذي يبدأ عندما يضيف المستخدم الأداة، السماح لهم بتهيئة خصائص الأداة. عرض السماح للمستخدمين بضبط الأدوات: بدءًا من نظام التشغيل Android 12، يمكن لتطبيقك تخطي الإعداد الأول التكوين. راجع استخدام والإعداد التلقائي للأداة للاطّلاع على التفاصيل.
description تُحدِّد وصف أداة اختيار التطبيقات المصغّرة لعرضها في التطبيق المصغّر. تم طرح هذه الميزة في نظام التشغيل Android 12.
previewLayout (Android 12) وpreviewImage (الإصدار 11 من نظام التشغيل Android والإصدارات الأقدم)
  • بدءًا من نظام التشغيل Android 12، تحدّد السمة previewLayout معاينة قابلة للتوسّع، التي تقدمها كتنسيق XML تم ضبطه على الحجم التلقائي للتطبيق المصغّر. من الناحية المثالية، تنسيق XML المحدد لأن هذه السمة هو نفس XML للتنسيق هو تطبيق مصغّر بقيم تلقائية واقعية
  • في نظام التشغيل Android 11 أو الإصدارات الأقدم، تتضمّن previewImage معاينة للشكل الذي سيبدو عليه التطبيق المصغّر بعد يظهر للمستخدم عند اختيار أداة التطبيق. إذا لم يكن كذلك يظهر للمستخدم رمز مشغّل تطبيقك بدلاً من ذلك. هذا النمط مع سمة android:previewImage في العنصر <receiver> في ملف AndroidManifest.xml.
ملاحظة: ننصح بتحديد كل من previewImage وpreviewLayout سمات كي يمكن لتطبيقك العودة إلى الحالة السابقة إلى استخدام previewImage إذا لم يكن جهاز المستخدم متوافقًا previewLayout لمزيد من التفاصيل، يُرجى مراجعة التوافق مع الأنظمة القديمة مع قابلية التوسّع معاينات التطبيقات المصغّرة.
autoAdvanceViewId تحدّد رقم تعريف الملف الشخصي للعرض الفرعي للتطبيق المصغّر الذي يتم التقدّم فيه تلقائيًا من خلال مضيف الأداة.
widgetCategory يحدد ما إذا كان يمكن عرض تطبيقك المصغّر على الشاشة الرئيسية (home_screen) أو شاشة القفل (keyguard) كليهما. بالنسبة إلى الإصدار 5.0 من نظام التشغيل Android والإصدارات الأحدث، يكون home_screen فقط صالحًا.
widgetFeatures يعرّف عن الميزات المتوافقة مع التطبيق المصغّر. على سبيل المثال، إذا كنت تريد تطبيقك المصغّر لاستخدام إعداده التلقائي عندما يضيفه مستخدم، وتحديد كلاهما configuration_optional أو reconfigurable الأعلام. يؤدي ذلك إلى تجاوز بدء نشاط الضبط بعد أن يبدأ المستخدم يضيف التطبيق المصغّر. لا يزال بإمكان المستخدم إعادة ضبط التطبيق المصغّر بعد ذلك.

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

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

تعريف التطبيق المصغّر في البيان

أولاً، يجب تحديد الفئة AppWidgetProvider في AndroidManifest.xml الخاصة بتطبيقك. كما هو موضح في المثال التالي:

<receiver android:name="ExampleAppWidgetProvider"
                 android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />
</receiver>

يتطلّب العنصر <receiver> السمة android:name التي تحدّد AppWidgetProvider التي تستخدمها الأداة. يجب عدم تصدير المكوِّن ما لم تكن هناك حاجة إلى إعلان عملية منفصلة على AppWidgetProvider، لذلك قد لا يكون الأمر كذلك عادةً.

يجب أن يشتمل العنصر <intent-filter> على عنصر <action> مع السمة android:name. تحدّد هذه السمة أنّ السمة AppWidgetProvider يقبل ACTION_APPWIDGET_UPDATE البث. هذا هو البث الوحيد الذي يجب الإعلان عنه صراحةً. تشير رسالة الأشكال البيانية AppWidgetManager إرسال جميع عمليات بث التطبيقات المصغّرة الأخرى تلقائيًا إلى AppWidgetProvider اللازمة.

يحدد العنصر <meta-data> المورد AppWidgetProviderInfo السمات التالية:

  • android:name: تحدّد اسم البيانات الوصفية. استخدام android.appwidget.provider لتحديد البيانات باعتبارها الواصف AppWidgetProviderInfo.
  • android:resource: يحدد المورد AppWidgetProviderInfo الموقع.

تنفيذ فئة AppWidgetProvider

تمتد الفئة AppWidgetProvider BroadcastReceiver كـ فئة ملائمة للتعامل مع عمليات بث الأداة. يتلقّى الحدث فقط عمليات البث ذات الصلة بالأداة، مثل وقت تحديث الأداة وحذفها وتفعيلها وإيقافها. وعند وقوع أحداث البث هذه، ينطبق ما يلي: يُطلق على AppWidgetProvider طريقة:

onUpdate()
تسمى هذه الطريقة لتحديث الأداة على الفواصل الزمنية التي تحددها السمة updatePeriodMillis في AppWidgetProviderInfo. اطّلع على الجدول وصف السمات الإضافية للأداة في هذه الصفحة مزيد من المعلومات.
تُسمى هذه الطريقة أيضًا عندما يضيف المستخدم الأداة، بحيث تنفذ مثل تحديد معالِجات الأحداث الكائنات View أو بدء المهام لتحميل البيانات إليه الذي سيتم عرضه في التطبيق المصغَّر. ومع ذلك، إذا أعلنت عن نشاط ضبط ليس له علامة configuration_optional، لا يتم استدعاء هذه الطريقة عندما ينقر المستخدم تضيف الأداة، ولكن يتم استدعاؤها لإجراء التحديثات اللاحقة. إنه مسئولية نشاط التهيئة عن إجراء التحديث الأول عند من التهيئة. راجع السماح للمستخدمين بضبط أدوات التطبيقات للحصول على مزيد من المعلومات.
أهم معاودة الاتصال هي "onUpdate()". يُرجى الاطّلاع على التعامل مع الأحداث باستخدام صف واحد (onUpdate()) في هذه الصفحة لمزيد من المعلومات.
onAppWidgetOptionsChanged()

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

  • OPTION_APPWIDGET_MIN_WIDTH: يحتوي على الحد الأدنى لعرض التطبيق المصغّر، بوحدات بكسل مستقلة الكثافة.
  • OPTION_APPWIDGET_MIN_HEIGHT: يحتوي على الحد الأدنى على ارتفاع، بوحدات بكسل مستقلة، لمثيل التطبيق المصغّر.
  • OPTION_APPWIDGET_MAX_WIDTH: يحتوي على الحد الأعلى للعرض، بوحدات dp، لمثيل التطبيق المصغّر.
  • OPTION_APPWIDGET_MAX_HEIGHT: يحتوي على الحد الأعلى للارتفاع، بوحدات dp، لمثيل التطبيق المصغّر.
  • OPTION_APPWIDGET_SIZES: يحتوي على قائمة بالأحجام المحتملة (List<SizeF>)، بوحدات dp، التي الذي يمكن أن يستغرقه مثيل الأداة. تم طرح هذه الميزة في نظام التشغيل Android 12.
onDeleted(Context, int[])

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

onEnabled(Context)

ويتم استدعاء ذلك عند إنشاء مثيل للأداة لأول مرة. على سبيل المثال، إذا أضاف المستخدم حالتين من الأداة، فهذا يسمى فقط للمرة الأولى. إذا كنت بحاجة إلى فتح قاعدة بيانات جديدة أو إجراء إعداد آخر أن يحدث مرة واحدة فقط لجميع مثيلات الأدوات، فحينئذٍ يعد هذا مكانًا جيدًا القيام بذلك.

onDisabled(Context)

ويتم استدعاء ذلك عندما يتم حذف المثيل الأخير لتطبيقك المصغّر من مضيف الأداة. يمكنك هنا محو أي عمل تم إجراؤه في "onEnabled(Context)". مثل حذف قاعدة بيانات مؤقتة.

onReceive(Context, Intent)

ويتم استدعاء ذلك لكل عملية بث وقبل كل معاودة اتصال سابقة الطرق. ولا تحتاج في العادة إلى تنفيذ هذه الطريقة لأن الإعداد التلقائي يؤدي تنفيذ "AppWidgetProvider" إلى فلترة جميع عمليات بث التطبيق المصغّر والاتصال به. الطرق السابقة حسب الحاجة.

يجب الإفصاح عن تنفيذ الفئة AppWidgetProvider على أنّها عملية بث. المستلِم الذي يستخدم العنصر <receiver> في السمة AndroidManifest. راجع إعلان التطبيق المصغّر في البيان في هذه الصفحة للاطّلاع على مزيد من المعلومات.

التعامل مع الأحداث من خلال فئة onUpdate()

أهم استدعاء لـ AppWidgetProvider هو onUpdate()، لأنه عند إضافة كل أداة إلى المضيف، ما لم تستخدم عملية تهيئة نشاط بدون علامة configuration_optional. إذا كان التطبيق المصغّر يقبل أيًّا أحداث تفاعل المستخدم، ثم تسجيل معالِجات الأحداث في عملية معاودة الاتصال هذه. في حال حذف فإن التطبيق المصغّر لا ينشئ ملفات مؤقتة أو قواعد بيانات، أو ينفذ إجراءات أخرى تتطلّب إزالة بعض البيانات، لذلك قد تكون onUpdate() هي طريقة معاودة الاتصال الوحيدة التي تحتاج إلى تعريفها.

على سبيل المثال، إذا كنت تريد أداة تحتوي على زر يشغِّل نشاطًا عندما يمكنك استخدام التنفيذ التالي لـ AppWidgetProvider:

Kotlin

class ExampleAppWidgetProvider : AppWidgetProvider() {

    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray
    ) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        appWidgetIds.forEach { appWidgetId ->
            // Create an Intent to launch ExampleActivity.
            val pendingIntent: PendingIntent = PendingIntent.getActivity(
                    /* context = */ context,
                    /* requestCode = */  0,
                    /* intent = */ Intent(context, ExampleActivity::class.java),
                    /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
            )

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            val views: RemoteViews = RemoteViews(
                    context.packageName,
                    R.layout.appwidget_provider_layout
            ).apply {
                setOnClickPendingIntent(R.id.button, pendingIntent)
            }

            // Tell the AppWidgetManager to perform an update on the current
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views)
        }
    }
}

Java

public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        for (int i=0; i < appWidgetIds.length; i++) {
            int appWidgetId = appWidgetIds[i];
            // Create an Intent to launch ExampleActivity
            Intent intent = new Intent(context, ExampleActivity.class);
            PendingIntent pendingIntent = PendingIntent.getActivity(
                /* context = */ context,
                /* requestCode = */ 0,
                /* intent = */ intent,
                /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
            );

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget_layout);
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // Tell the AppWidgetManager to perform an update on the current app
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}

تحدِّد AppWidgetProvider طريقة onUpdate() فقط، ويتم استخدامها إنشاء PendingIntent يتم تشغيله Activity ويرفقها مع الأداة زر باستخدام setOnClickPendingIntent(int, PendingIntent). يتضمن تكرارًا حلقيًا من خلال كل إدخال في appWidgetIds، وهي مصفوفة من أرقام التعريف التي تحدّد كل تطبيق مصغّر أنشأه مقدّم الخدمة هذا. إذا أنشأ المستخدم أكثر من مثيل واحد من الأداة، فعندئذ يتم تحديثها جميعًا في وقت واحد. مع ذلك، يتم إعداد جدول زمني واحد فقط للوضع "updatePeriodMillis". تتم إدارته لجميع مثيلات الأداة. على سبيل المثال، إذا كان الجدول الزمني للتحديث أن يتم تحديدها كل ساعتين، كما تتم إضافة مثال آخر للأداة بعد ساعة واحدة من العمود الأول، يتم تحديث كليهما في الفترة التي تحددها الأول، ويتم تجاهل فترة التحديث الثانية. يتم تحديثهما كل اثنين وليس كل ساعة.

يمكنك الاطّلاع على ExampleAppWidgetProvider.java فئة نموذجية لمزيد من التفاصيل.

تلقّي أهداف بث التطبيق المصغّر

AppWidgetProvider هو فئة صغيرة. إذا أردت تلقّي التطبيق المصغّر أحداث البث مباشرةً، يمكنك تنفيذ BroadcastReceiver أو إلغاء الـ onReceive(Context,Intent) معاودة الاتصال. إنّ النوايا التي يجب الاهتمام بها هي التالي:

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

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

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

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

دعم السلوك المرتبط بالحالة

يتيح نظام التشغيل Android 12 إمكانية تحديد سلوك المستخدم من خلال ما يلي: المكونات الحالية:

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

مثال على تطبيق مصغّر يعرض قائمة التسوّق يعرض السلوك المرتبط بالحالة
الشكل 3. مثال على السلوك القائم على الحالة

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

Kotlin

// 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)
)

Java

// 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، والاستهداف الآخر السابق الإصدار 11 من نظام التشغيل Android أو الإصدارات الأقدم في مجلد res/layout التلقائي.

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

يقدّم Android 12 مَعلمات النظام التالية لضبط نصف قطر الزوايا المستديرة للأداة:

  • system_app_widget_background_radius: نصف قطر الزاوية لخلفية التطبيق المصغّر، والذي لا يزيد أبدًا عن 28 بكسل مستقل الكثافة

  • system_app_widget_inner_radius: نصف قطر الزاوية لأي عرض داخل الأداة. يساوي بالضبط 8 بكسل مستقل الكثافة. أقل من نصف قطر الخلفية، للمحاذاة بشكل جيد عند استخدام 8 dp. المساحة المتروكة.

يوضح المثال التالي أداة تستخدم system_app_widget_background_radius لزاوية التطبيق المصغّر system_app_widget_inner_radius للاطّلاع على طرق العرض داخل التطبيق المصغّر.

تطبيق مصغّر يعرض نصف قطر خلفية التطبيق المصغّر وعدد المشاهدات داخل التطبيق المصغّر
الشكل 4. زوايا دائرية

1 في الزاوية العلوية من التطبيق المصغّر.

2 زاوية عرض داخل التطبيق المصغّر.

اعتبارات مهمة للزوايا المستديرة

  • يمكن للمشغّلات التابعة لجهات خارجية والشركات المصنّعة للأجهزة إلغاء أن يكون حجم المعلَمة system_app_widget_background_radius أقل من 28 بكسل مستقل الكثافة. تكون المعلمة system_app_widget_inner_radius دائمًا أقل من 8 dp من قيمة system_app_widget_background_radius.
  • إذا كان تطبيقك المصغّر لا يستخدم @android:id/background أو حدِّد خلفية يتم اقتصاص المحتوى بناءً على المخطط باستخدام "android:clipToOutline" على true، سيحدِّد مشغّل التطبيقات تلقائيًا الخلفية لاقتصاص التطبيق المصغّر باستخدام مستطيل بزوايا مستديرة حتى 16 بكسل مستقل الكثافة. اطَّلِع على التأكد من توافق التطبيق المصغّر مع Android 12

للتوافق مع الأداة مع إصدارات Android السابقة، نوصي تحديد السمات المخصصة واستخدام مظهر مخصص لإلغائها Android 12، كما هو موضّح في نماذج ملفات XML التالية:

/values/attrs.xml

<resources>
  <attr name="backgroundRadius" format="dimension" />
</resources>

/values/styles.xml

<resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
</resources>

/values-31/styles.xml

<resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
</resources>

/drawable/my_widget_background.xml

<shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  ...
</shape>

/layout/my_widget_layout.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:background="@drawable/my_widget_background" />