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

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

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

يمكنك الاطّلاع على مقتطفات الرموز البرمجية في القسم التالي للحصول على مثال على كيفية عرض نتيجة من الإعدادات وتعديل تطبيق Glance المصغّر.

تعديل التطبيق المصغّر من نشاط الإعدادات

عندما يستخدم التطبيق المصغّر نشاط إعدادات، تقع على عاتق النشاط مسؤولية تعديل التطبيق المصغّر عند اكتمال الإعدادات. يمكنك إجراء ذلك من خلال تشغيل تعديل يدوي مباشرةً من مثيل GlanceAppWidget.

في ما يلي ملخّص للإجراء اللازم لتعديل التطبيق المصغّر بشكل صحيح وإغلاق نشاط الإعدادات:

1. احصل على رقم تعريف التطبيق المصغّر من النية التي شغّلت النشاط:

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

2. اضبط نتيجة النشاط على RESULT_CANCELED.

   بهذه الطريقة، إذا خرج المستخدم من النشاط قبل الوصول إلى نهايته، يُعلم النظام مضيف التطبيق المصغّر بأنّه تم إلغاء الإعدادات ولا يضيف المضيف التطبيق المصغّر:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

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

4. عند اكتمال الإعدادات، استردِ GlanceId المقابل لرقم تعريف التطبيق المصغّر على النظام الأساسي:

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. عدِّل محتوى التطبيق المصغّر من خلال استدعاء الدالة update المعلقة على مثيل GlanceAppWidget:

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. أنشئ نية العرض، واضبطها على نتيجة النشاط، وأنهِ النشاط:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

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

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

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

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

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

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

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

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

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

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