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

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

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

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

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

ملاحظة: لا تتوفّر هذه الخيارات إلا بدءًا من الإصدار 12 من نظام التشغيل Android (المستوى 31 من واجهة برمجة التطبيقات). إِنْتَ يمكنك تحديدها للإصدارات السابقة من Android، ولكن لا يستطيع النظام ويتجاهلها وتتّبع السلوك التلقائي.

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

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

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

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

الشكل 1. زر إعادة ضبط التطبيق المصغّر

ملاحظة: تمّ طرح العلامة reconfigurable في Android 9 (المستوى 28 من واجهة برمجة التطبيقات)، ولكن لم تكن متاحة على نطاق واسع حتى Android 12.

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

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

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

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