کاربران را قادر می سازد تا ویجت های برنامه را پیکربندی کنند

ویجت های برنامه قابل تنظیم هستند. برای مثال، ویجت ساعت می‌تواند به کاربران اجازه دهد که منطقه زمانی را برای نمایش پیکربندی کنند.

اگر می‌خواهید به کاربران اجازه دهید تنظیمات ویجت شما را پیکربندی کنند، یک Activity پیکربندی ویجت ایجاد کنید. این فعالیت به طور خودکار توسط میزبان ویجت برنامه یا در زمان ایجاد ویجت یا بعد از آن، بسته به گزینه های پیکربندی که مشخص می کنید، راه اندازی می شود.

فعالیت پیکربندی را اعلام کنید

فعالیت پیکربندی را به عنوان یک فعالیت عادی در فایل مانیفست اندروید اعلام کنید. میزبان ویجت برنامه آن را با عمل 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. شناسه ابزارک برنامه را از هدفی که فعالیت را راه اندازی کرده است دریافت کنید:

   کاتلین

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

   جاوا

   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 تنظیم کنید.

   به این ترتیب، اگر کاربر قبل از رسیدن به پایان فعالیت از فعالیت خارج شود، سیستم به میزبان ویجت برنامه اطلاع می دهد که پیکربندی لغو شده است و میزبان ویجت را اضافه نمی کند:

   کاتلین

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

   جاوا

   int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(Activity.RESULT_CANCELED, resultValue);

3. ویجت را با توجه به ترجیحات کاربر پیکربندی کنید.

4. وقتی پیکربندی کامل شد، با فراخوانی getInstance(Context) یک نمونه از AppWidgetManager را دریافت کنید:

   کاتلین

   val appWidgetManager = AppWidgetManager.getInstance(context)

   جاوا

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

5. با فراخوانی updateAppWidget(int,RemoteViews) ویجت را با طرح‌بندی RemoteViews به‌روزرسانی کنید:

   کاتلین

   val views = RemoteViews(context.packageName, R.layout.example_appwidget)
   appWidgetManager.updateAppWidget(appWidgetId, views)

   جاوا

   RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
   appWidgetManager.updateAppWidget(appWidgetId, views);

6. قصد بازگشت را ایجاد کنید، آن را با نتیجه فعالیت تنظیم کنید و فعالیت را به پایان برسانید:

   کاتلین

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

   جاوا

   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>

کاربران می توانند ویجت خود را با لمس و نگه داشتن ویجت و ضربه زدن روی دکمه Reconfigure که در شکل 1 با شماره 1 مشخص شده است، پیکربندی مجدد کنند.

از پیکربندی پیش فرض ویجت استفاده کنید

می‌توانید با اجازه دادن به کاربران از مرحله پیکربندی اولیه، یک تجربه یکپارچه‌تر از ویجت ارائه دهید. برای انجام این کار، هر دو پرچم configuration_optional و reconfigurable را در قسمت widgetFeatures مشخص کنید. این کار راه اندازی فعالیت پیکربندی را پس از افزودن ویجت توسط کاربر دور می زند. همانطور که قبلا ذکر شد، کاربر همچنان می تواند بعد از آن ویجت را مجدداً پیکربندی کند . برای مثال، یک ویجت ساعت می تواند پیکربندی اولیه را دور بزند و منطقه زمانی دستگاه را به طور پیش فرض نشان دهد.

در اینجا مثالی از نحوه علامت گذاری فعالیت پیکربندی خود به عنوان پیکربندی مجدد و اختیاری آورده شده است:

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