يمكن ضبط أدوات التطبيقات. على سبيل المثال، يمكن أن تتيح أداة الساعة للمستخدمين ضبط المنطقة الزمنية المراد عرضها.
إذا كنت تريد السماح للمستخدمين بضبط إعدادات الأداة، يمكنك إنشاء عملية ضبط للأداة 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
عند بدء نشاط الضبط، ما يعني أنّه لا يستدعي طريقة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();
يمكنك الاطّلاع على نموذج الصف على GitHub
ListWidgetConfigureActivity.kt
للحصول على مثال.
خيارات تهيئة الأداة
يشغِّل مضيف التطبيق المصغّر نشاط الضبط مرة واحدة فقط تلقائيًا بعد أن يضيف المستخدم الأداة إلى شاشته الرئيسية مباشرةً. مع ذلك، يمكنك تحديد الخيارات التي تتيح لك السماح للمستخدمين بإعادة ضبط التطبيقات المصغّرة الحالية أو تخطّي عملية الإعداد الأولية للأداة من خلال توفير إعدادات تلقائية للإعدادات.
السماح للمستخدمين بإعادة ضبط التطبيقات المصغّرة التي تم وضعها
للسماح للمستخدمين بإعادة ضبط التطبيقات المصغّرة الحالية، حدِّد العلامة
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>
السماح للمستخدمين بتثبيت أداة
على الأجهزة التي تعمل بالإصدار 8.0 من نظام التشغيل Android (المستوى 26 لواجهة برمجة التطبيقات) والإصدارات الأحدث، تتيح مشغّلات التطبيقات التي تتيح للمستخدمين إنشاء اختصارات مثبتة أيضًا إمكانية تثبيت التطبيقات المصغّرة على الشاشة الرئيسية. على غرار الاختصارات المثبَّتة، تمنح هذه التطبيقات المصغّرة المثبّتة المستخدمين إمكانية الوصول إلى مهام محدّدة في تطبيقك ويمكن إضافتها إلى الشاشة الرئيسية من التطبيق مباشرةً، كما هو موضّح في الفيديو التالي.
في تطبيقك، يمكنك إنشاء طلب للنظام من أجل تثبيت تطبيق مصغّر على مشغّل تطبيقات متوافق من خلال إكمال الخطوات التالية:
احرص على توضيح أداة في ملف البيان الخاص بتطبيقك.
يمكنك استدعاء الطريقة
requestPinAppWidget()
، كما هو موضح في مقتطف الرمز التالي:
Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context) val myProvider = ComponentName(context, ExampleAppWidgetProvider::class.java) if (appWidgetManager.isRequestPinAppWidgetSupported()) { // Create the PendingIntent object only if your app needs to be notified // when the user chooses to pin the widget. Note that if the pinning // operation fails, your app isn't notified. This callback receives the ID // of the newly pinned widget (EXTRA_APPWIDGET_ID). val successCallback = PendingIntent.getBroadcast( /* context = */ context, /* requestCode = */ 0, /* intent = */ Intent(...), /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT) appWidgetManager.requestPinAppWidget(myProvider, null, successCallback) }
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context); ComponentName myProvider = new ComponentName(context, ExampleAppWidgetProvider.class); if (appWidgetManager.isRequestPinAppWidgetSupported()) { // Create the PendingIntent object only if your app needs to be notified // when the user chooses to pin the widget. Note that if the pinning // operation fails, your app isn't notified. This callback receives the ID // of the newly pinned widget (EXTRA_APPWIDGET_ID). PendingIntent successCallback = PendingIntent.getBroadcast( /* context = */ context, /* requestCode = */ 0, /* intent = */ new Intent(...), /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT); appWidgetManager.requestPinAppWidget(myProvider, null, successCallback); }