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

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

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

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

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

ملاحظة: تتوفّر هذه الخيارات فقط بدءًا من نظام التشغيل Android 12 (المستوى 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>