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

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

إذا كنت تريد السماح للمستخدمين بضبط إعدادات الأداة، يمكنك إنشاء عملية ضبط للأداة 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>

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

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

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

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

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

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

خيارات تهيئة الأداة

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

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

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

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

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

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

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

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

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