ابزاره‌تان را طوری طراحی کنید که کاربران بتوانند ویژگی‌های خاصی را پیکربندی کنند. برای مثال، ابزارک ساعت می‌تواند به کاربران اجازه دهد پیکربندی کنند کدام منطقه زمانی نمایش داده شود.
اگر می‌خواهید به کاربران اجازه دهید تنظیمات ابزاره‌تان را پیکربندی کنند، پیکربندی ابزاره
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را ارسال نمی‌کند، یعنی در ابتدا وقتی ابزاره ایجاد می‌شود، به‌روزرسانی‌های ابزاره را فراخوانی نمی‌کند. هنگام ایجاد ابزاره برای اولین‌بار، فعالیت پیکربندی مسئولیت دارد که به‌روزرسانی را ازGlanceAppWidgetدرخواست کند. بااین‌حال، به‌روزرسانی‌ها به‌طور خودکار برای چرخه‌های بعدی راه‌اندازی می‌شوند.
- وقتی فعالیت پیکربندی راه‌اندازی می‌شود، سیستم پخش
برای دیدن نمونه‌ای از نحوه برگرداندن نتیجه از پیکربندی و به‌روزرسانی ابزاره Glance، تکه‌کدهای بخش زیر را ببینید.
به‌روزرسانی ابزاره از فعالیت پیکربندی
وقتی ابزاره‌ای از فعالیت پیکربندی استفاده می‌کند، مسئولیت فعالیت این است که ابزاره را پس‌از تکمیل پیکربندی به‌روز کند. می‌توانید این کار را با
راه‌اندازی به‌روزرسانی دستی مستقیماً از نمونه GlanceAppWidget انجام دهید.
در اینجا خلاصه‌ای از روش به‌روزرسانی صحیح ابزاره و بستن فعالیت پیکربندی آورده شده است:
شناسه ابزارک برنامه را از قصدی که فعالیت را راه‌اندازی کرده است دریافت کنید:
val appWidgetId = intent?.extras?.getInt( AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID ) ?: AppWidgetManager.INVALID_APPWIDGET_IDنتیجه فعالیت را روی
RESULT_CANCELEDتنظیم کنید.به‌این‌ترتیب، اگر کاربر قبل‌از رسیدن به پایان فعالیت از آن خارج شود، سیستم به میزبان ابزاره برنامه اطلاع می‌دهد که پیکربندی لغو شده است و میزبان ابزاره را اضافه نمی‌کند:
val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) setResult(Activity.RESULT_CANCELED, resultValue)ابزاره را براساس اولویت‌های کاربر پیکربندی کنید، برای مثال نوشتن انتخاب‌ها در DataStore دائمی یا پایگاه داده محلی.
وقتی پیکربندی تکمیل شد،
GlanceIdمربوط به شناسه ابزارک پلاتفرم را بازیابی کنید:val glanceAppWidgetManager = GlanceAppWidgetManager(context) val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)محتوای ابزاره را با فراخوانی تابع تعلیق
updateدر نمونهGlanceAppWidgetبه‌روز کنید:// Update the GlanceAppWidget directly ExampleGlanceWidget().update(context, glanceId)قصد بازگشت را ایجاد کنید، آن را با نتیجه فعالیت تنظیم کنید، و فعالیت را تمام کنید:
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>
کاربران می‌توانند با لمس کردن و نگه داشتن ابزاره و تک‌ضرب زدن روی دکمه پیکربندی مجدد که در شکل ۱ با برچسب ۱ مشخص شده است، ابزاره خود را دوباره پیکربندی کنند.
استفاده از پیکربندی پیش‌فرض ابزاره
با اجازه دادن به کاربران برای رد شدن از مرحله پیکربندی اولیه، می‌توانید تجربه ابزاره‌ای یکپارچه‌تری ارائه دهید. برای انجام این کار، هر دو پرچم
configuration_optional و reconfigurable را در فیلد
widgetFeatures مشخص کنید. این کار باعث می‌شود فعالیت پیکربندی پس‌از اینکه کاربر ابزاره را اضافه کرد راه‌اندازی نشود. همان‌طور که قبلاً ذکر شد، کاربر همچنان می‌تواند
بعداً ابزاره را دوباره پیکربندی کند. برای مثال، ابزاره ساعت می‌تواند پیکربندی اولیه را دور بزند و منطقه زمانی دستگاه را به‌طور پیش‌فرض نشان دهد.
در اینجا مثالی از نحوه علامت‌گذاری فعالیت پیکربندی به‌عنوان هم قابل‌پیکربندی مجدد و هم اختیاری آورده شده است:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>