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

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

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

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

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

5. عدِّل محتوى التطبيق المصغّر من خلال استدعاء الدالة update suspend في مثيل 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>