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

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

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

خيارات إعداد الأداة

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

ملاحظة: تتوفّر هذه الخيارات فقط بدءًا من نظام التشغيل Android 12 (المستوى 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>