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

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

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