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

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

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

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

اکتیویتی پیکربندی را به عنوان یک اکتیویتی معمولی در فایل مانیفست اندروید اعلام کنید. میزبان ویجت برنامه آن را با اکشن ACTION_APPWIDGET_CONFIGURE اجرا می‌کند، بنابراین اکتیویتی باید این intent را بپذیرد. برای مثال:

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

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

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

3. ویجت را مطابق با تنظیمات کاربر پیکربندی کنید، برای مثال، انتخاب‌ها را در یک پایگاه داده دائمی یا یک پایگاه داده محلی بنویسید.

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>

کاربران می‌توانند با لمس و نگه داشتن ویجت و زدن دکمه‌ی Reconfigure که در شکل ۱ با عدد ۱ مشخص شده است، ویجت خود را مجدداً پیکربندی کنند.

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

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

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

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