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

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

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

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

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

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

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

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