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

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

إذا كنت تريد السماح للمستخدمين بضبط إعدادات الأداة، يمكنك إنشاء عملية ضبط للأداة 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.

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

  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();

يمكنك الاطّلاع على نموذج الصف على GitHub ListWidgetConfigureActivity.kt للحصول على مثال.

خيارات تهيئة الأداة

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

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

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

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

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

يظهر الزر في أسفل الجانب الأيسر.
الشكل 1. زر إعادة ضبط الأداة.

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

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

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

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

السماح للمستخدمين بتثبيت أداة

على الأجهزة التي تعمل بالإصدار 8.0 من نظام التشغيل Android (المستوى 26 لواجهة برمجة التطبيقات) والإصدارات الأحدث، تتيح مشغّلات التطبيقات التي تتيح للمستخدمين إنشاء اختصارات مثبتة أيضًا إمكانية تثبيت التطبيقات المصغّرة على الشاشة الرئيسية. على غرار الاختصارات المثبَّتة، تمنح هذه التطبيقات المصغّرة المثبّتة المستخدمين إمكانية الوصول إلى مهام محدّدة في تطبيقك ويمكن إضافتها إلى الشاشة الرئيسية من التطبيق مباشرةً، كما هو موضّح في الفيديو التالي.

مثال على التنسيق المتجاوب
الشكل 2. مثال على تثبيت تطبيق مصغّر.

في تطبيقك، يمكنك إنشاء طلب للنظام من أجل تثبيت تطبيق مصغّر على مشغّل تطبيقات متوافق من خلال إكمال الخطوات التالية:

  1. احرص على توضيح أداة في ملف البيان الخاص بتطبيقك.

  2. يمكنك استدعاء الطريقة 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);
}