السماح للمستخدمين بضبط التطبيقات المصغّرة للتطبيقات

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

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

الإفصاح عن نشاط الضبط

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

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

حدِّد النشاط في ملف AppWidgetProviderInfo.xml باستخدام السمة android:configure. اطّلِع على مزيد من المعلومات حول الإفصاح عن هذا الملف. في ما يلي مثال على كيفية تحديد نشاط الضبط:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

يتمّ الإعلان عن النشاط باستخدام مساحة اسم مؤهَّلة بالكامل، لأنّ مشغّل التطبيقات يشير إليه من خارج نطاق الحزمة.

هذا كل ما تحتاج إليه لبدء نشاط الضبط. بعد ذلك، عليك تنفيذ النشاط الفعلي.

تنفيذ نشاط الضبط

هناك نقطتان مهمتان يجب تذكّرهما عند تنفيذ النشاط:

• يستدعي مضيف التطبيق المصغّر نشاط الضبط، ويجب أن يعرض نشاط الضبط نتيجة في كلّ الأوقات. يجب أن تتضمّن النتيجة رمز تعريف تطبيقات المصغّرات الذي تم تمريره من خلال النية التي بدأت النشاط، والذي تم حفظه في extras للنية على النحو التالي: EXTRA_APPWIDGET_ID.
• لا يُرسِل النظام البث ACTION_APPWIDGET_UPDATE عند بدء نشاط الضبط، ما يعني أنّه لا يُطلِب الطريقة onUpdate() عند إنشاء التطبيق المصغّر. تتحمّل عملية الضبط مسؤولية طلب تحديث من AppWidgetManager عند إنشاء التطبيق المصغّر لأول مرة. ومع ذلك، يتم استدعاء onUpdate() لإجراء التعديلات اللاحقة، ويتم تخطّيه في المرة الأولى فقط.

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

تعديل التطبيق المصغّر من نشاط الضبط

عندما يستخدم التطبيق المصغّر نشاطًا للضبط، تقع على عاتق النشاط مسؤولية تعديل التطبيق المصغّر عند اكتمال الضبط. يمكنك إجراء ذلك من خلال طلب تعديل مباشرةً من AppWidgetManager.

في ما يلي ملخّص للإجراء الذي يجب اتّباعه لتعديل التطبيق المصغّر بشكل صحيح وإغلاق نشاط الضبط:

1. يمكنك الحصول على معرّف التطبيق المصغّر من النية التي بدأت النشاط:

   Kotlin

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

   Java

   Intent intent = getIntent();
   Bundle extras = intent.getExtras();
   int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
   if (extras != null) {
       appWidgetId = extras.getInt(
               AppWidgetManager.EXTRA_APPWIDGET_ID,
               AppWidgetManager.INVALID_APPWIDGET_ID);
   }
   

2. اضبط نتيجة النشاط على RESULT_CANCELED.

   بهذه الطريقة، إذا تراجع المستخدم عن النشاط قبل الوصول إلى نهايته، يُرسِل النظام إشعارًا إلى مضيف التطبيق المصغّر بأنّه تم إلغاء الضبط، وبالتالي لن يضيف المضيف التطبيق المصغّر:

   Kotlin

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

   Java

   int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(Activity.RESULT_CANCELED, resultValue);
   

3. يمكنك ضبط التطبيق المصغّر وفقًا للإعدادات المفضّلة للمستخدم.

4. عند اكتمال عملية الضبط، احصل على مثيل من AppWidgetManager من خلال استدعاء getInstance(Context):

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)
   

   Java

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
   

5. يمكنك تعديل التطبيق المصغّر باستخدام تنسيق RemoteViews من خلال الاتصال بالرقم updateAppWidget(int,RemoteViews):

   Kotlin

   val views = RemoteViews(context.packageName, R.layout.example_appwidget)
   appWidgetManager.updateAppWidget(appWidgetId, views)
   

   Java

   RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
   appWidgetManager.updateAppWidget(appWidgetId, views);
   

6. أنشئ نية الإرجاع واضبطها باستخدام نتيجة النشاط، ثم أكمِل النشاط:

   Kotlin

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

   Java

   Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(RESULT_OK, resultValue);
   finish();
   

يمكنك الاطّلاع على ملف نموذج الصف الدراسي ListWidgetConfigureActivity.kt على GitHub للحصول على مثال.

خيارات ضبط التطبيقات المصغّرة

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

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

السماح للمستخدمين بإعادة ضبط التطبيقات المصغّرة المُثبَّتة

للسماح للمستخدمين بإعادة ضبط التطبيقات المصغّرة الحالية، حدِّد العلامة reconfigurable في السمة widgetFeatures لعنصر appwidget-provider. اطّلِع على دليل الإفصاح عن ملف AppWidgetProviderInfo.xml للحصول على مزيد من المعلومات. مثلاً:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

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

الشكل 1. زر إعادة ضبط التطبيق المصغّر

ملاحظة: تمّ طرح العلامة reconfigurable في Android 9 (المستوى 28 من واجهة برمجة التطبيقات)، ولكن لم تكن متاحة على نطاق واسع حتى Android 12.

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

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

في ما يلي مثال على كيفية وضع علامة على نشاط الضبط على أنّه قابل لإعادة الضبط واختياري:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>