ویجتهای برنامه، نماهای مینیاتوری برنامه هستند که میتوانید در برنامههای دیگر - مانند صفحه اصلی - جاسازی کنید و بهروزرسانیهای دورهای را دریافت کنید. این نماها در رابط کاربری به عنوان ویجت شناخته میشوند و میتوانید یکی از آنها را با یک ارائهدهنده ویجت برنامه (یا ارائهدهنده ویجت ) منتشر کنید. یک مؤلفه برنامه که ویجتهای دیگر را در خود جای میدهد، میزبان ویجت برنامه (یا میزبان ویجت ) نامیده میشود. شکل 1 یک ویجت موسیقی نمونه را نشان میدهد:
این سند نحوه انتشار یک ویجت با استفاده از یک ارائهدهنده ویجت را شرح میدهد. برای جزئیات بیشتر در مورد ایجاد AppWidgetHost خود برای میزبانی ویجتهای برنامه، به ساخت میزبان ویجت مراجعه کنید.
برای اطلاعات در مورد نحوه طراحی ویجت خود، به نمای کلی ویجتهای برنامه مراجعه کنید.
اجزای ویجت
برای ایجاد یک ویجت، به اجزای اساسی زیر نیاز دارید:
- شیء
AppWidgetProviderInfo - فرادادههای یک ویجت، مانند طرحبندی ویجت، تعداد دفعات بهروزرسانی و کلاس
AppWidgetProviderتوصیف میکند.AppWidgetProviderInfoدر XML تعریف شده است، همانطور که در این سند توضیح داده شده است. - کلاس
AppWidgetProvider - متدهای پایهای را تعریف میکند که به شما امکان میدهد از طریق برنامهنویسی با ویجت ارتباط برقرار کنید. از طریق آن، هنگام بهروزرسانی، فعال، غیرفعال یا حذف ویجت، اعلانهایی دریافت میکنید. شما
AppWidgetProviderرا در مانیفست اعلام میکنید و سپس آن را پیادهسازی میکنید ، همانطور که در این سند توضیح داده شده است. - مشاهده طرحبندی
- طرح اولیه ویجت را تعریف میکند. این طرح در XML تعریف شده است، همانطور که در این سند توضیح داده شده است.
شکل ۲ نشان میدهد که چگونه این اجزا در جریان کلی پردازش ویجت برنامه قرار میگیرند.
اگر ویجت شما نیاز به پیکربندی کاربر دارد، فعالیت پیکربندی ویجت برنامه را پیادهسازی کنید. این فعالیت به کاربران امکان میدهد تنظیمات ویجت را تغییر دهند - برای مثال، منطقه زمانی برای ویجت ساعت.
- از اندروید ۱۲ (سطح API 31)، میتوانید یک پیکربندی پیشفرض ارائه دهید و به کاربران اجازه دهید ویجت را بعداً دوباره پیکربندی کنند. برای جزئیات بیشتر به «استفاده از پیکربندی پیشفرض ویجت» و «فعال کردن کاربران برای پیکربندی مجدد ویجتهای قرار داده شده» مراجعه کنید.
- در اندروید ۱۱ (سطح API 30) یا پایینتر، این اکتیویتی هر بار که کاربر ویجت را به صفحه اصلی خود اضافه میکند، اجرا میشود.
ما همچنین بهبودهای زیر را توصیه میکنیم: طرحبندیهای انعطافپذیر ویجت ، بهبودهای متفرقه ، ویجتهای پیشرفته ، ویجتهای مجموعه و ساخت یک میزبان ویجت .
اعلان فایل XML مربوط به AppWidgetProviderInfo
تعریف تنظیمات متادیتا (مانند اندازههای پیشفرض سلولها، محدودیتهای تغییر اندازه و فرکانسهای بهروزرسانی) دقیقاً در هر دو ویجت سنتی Views و Glance-based یکسان است.
برای یادگیری نحوه تعریف و پیکربندی فایل XML فراداده خود، به بخش Compose-first Declare the AppWidgetProviderInfo XML در مستندات Glance مراجعه کنید.
از کلاس AppWidgetProvider برای مدیریت پخش ویجتها استفاده کنید
مکانیزمهای دریافتکنندهی اعلان پلتفرم، فیلترهای اعلان مانیفست و حلقههای رویداد چرخهی حیات در زیر پلتفرم یکپارچه شدهاند. در توسعهی Compose-first، این پخشها با استفاده از پوشش GlanceAppWidgetReceiver هماهنگ میشوند.
برای درک نحوه ثبت گیرنده خود در مانیفست و پیادهسازی overrideهای چرخه عمر سازگار با Hilt، به بخش Compose-first Use the AppWidgetProvider class to handle broadcasts در مستندات Glance مراجعه کنید.
طرح بندی ویجت را ایجاد کنید
شما باید یک طرح اولیه برای ویجت خود در XML تعریف کنید و آن را در پوشه res/layout/ پروژه ذخیره کنید. برای جزئیات بیشتر به دستورالعملهای طراحی مراجعه کنید.
اگر با طرحبندیها آشنا باشید، ایجاد طرحبندی ویجت ساده است. با این حال، توجه داشته باشید که طرحبندیهای ویجت مبتنی بر RemoteViews هستند که از هر نوع طرحبندی یا ویجت نمایشی پشتیبانی نمیکند. شما نمیتوانید از نماهای سفارشی یا زیرکلاسهای نماهایی که توسط RemoteViews پشتیبانی میشوند، استفاده کنید.
RemoteViews همچنین از ViewStub پشتیبانی میکند، که یک View نامرئی و با اندازه صفر است که میتوانید از آن برای افزایش تدریجی منابع طرحبندی در زمان اجرا استفاده کنید.
پشتیبانی از رفتار حالتمند
اندروید ۱۲ با استفاده از اجزای موجود زیر، پشتیبانی از رفتار stateful را اضافه میکند:
ویجت هنوز بدون وضعیت است. برنامه شما باید وضعیت را ذخیره کند و برای رویدادهای تغییر وضعیت ثبت نام کند.
نمونه کد زیر نحوه پیادهسازی این اجزا را نشان میدهد.
کاتلین
// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)
// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)
// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
R.id.my_checkbox,
RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)
جاوا
// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);
// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);
// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
R.id.my_checkbox,
RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));
دو طرحبندی ارائه دهید: یکی دستگاههایی را هدف قرار میدهد که اندروید ۱۲ یا بالاتر را در res/layout-v31 اجرا میکنند و دیگری دستگاههای اندروید ۱۱ یا پایینتر را که در پوشه پیشفرض res/layout قرار دارند، هدف قرار میدهد.
پیادهسازی گوشههای گرد
محاسبهی شعاعهای متناسب پسزمینهی بیرونی و داخلی، استاندارد و مشترک است. در توسعهی Compose-first، این مورد میتواند به صورت پویا در کاتلین در کنار منابع قالب سفارشی تنظیم شود.
برای پیادهسازی شعاع گوشهها یا تنظیم سبکهای پویا برای دستگاههای اندروید قدیمیتر، به بخش Compose-first Implement rounded corners در مستندات Glance مراجعه کنید.