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

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

إذا أردت السماح للمستخدمين بضبط إعدادات التطبيق المصغّر، عليك إنشاء تطبيق مصغّر لضبط 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();

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

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

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

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

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

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

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

يظهر الزر في أسفل يسار الصفحة
الشكل 1. زر إعادة الضبط في التطبيق المصغّر

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

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

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

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