يمكن أن تكون أدوات التطبيقات قابلة للتهيئة. على سبيل المثال، يمكن أن تتيح أداة الساعة للمستخدمين ضبط المنطقة الزمنية التي سيتم عرضها.
إذا كنت تريد السماح للمستخدمين بضبط إعدادات تطبيقك المصغّر، عليك إنشاء
إعداد تطبيق مصغّر 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
.
في ما يلي ملخص لإجراء تحديث الأداة بشكل صحيح وإغلاق نشاط التهيئة:
احصل على معرّف التطبيق المصغَّر من الغرض الذي أطلق النشاط:
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); }
اضبط نتيجة النشاط على
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);
اضبط التطبيق المصغّر وفقًا لإعدادات المستخدم المفضّلة.
عند اكتمال عملية الإعداد، يمكنك الحصول على نسخة افتراضية من
AppWidgetManager
من خلال طلبgetInstance(Context)
:Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
يمكنك تعديل التطبيق المصغّر بتنسيق
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);
أنشئ نية الإرجاع، واضبطها مع نتيجة النشاط، ثم أنهِ النشاط:
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.
استخدام الإعدادات التلقائية للأداة
يمكنك توفير تجربة أداة أكثر سلاسة عن طريق السماح للمستخدمين بتخطّي خطوة الضبط الأولية. لإجراء ذلك، حدِّد كلاً من العلامتَين configuration_optional
وreconfigurable
في الحقل widgetFeatures
. يؤدي ذلك إلى تجاوز تشغيل نشاط الضبط بعد أن يضيف المستخدم الأداة. وكما ذكرنا سابقًا، لا يزال بإمكان المستخدم إعادة ضبط الأداة بعد ذلك. على سبيل المثال، يمكن لأداة الساعة تجاوز الإعدادات الأولية وعرض المنطقة الزمنية للجهاز تلقائيًا.
وفي ما يلي مثال على كيفية وضع علامة على نشاط الضبط باعتباره قابلاً لإعادة الضبط واختياريًا:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>