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

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

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