ویجتهای برنامه، نماهای مینیاتوری برنامه هستند که میتوانید در برنامههای دیگر - مانند صفحه اصلی - جاسازی کنید و بهروزرسانیهای دورهای را دریافت کنید. این نماها به عنوان ابزارک در رابط کاربری نامیده میشوند و میتوانید یکی از آنها را با ارائهدهنده ابزارک برنامه (یا ارائهدهنده ویجت ) منتشر کنید. جزء برنامه ای که ویجت های دیگر را نگه می دارد، میزبان ویجت برنامه (یا میزبان ویجت ) نامیده می شود. شکل 1 نمونه ویجت موسیقی را نشان می دهد:
![نمونه ای از ویجت موسیقی](https://developer.android.com/static/images/appwidgets/music.png?authuser=1&hl=fa)
این سند نحوه انتشار یک ویجت با استفاده از ارائه دهنده ویجت را توضیح می دهد. برای جزئیات در مورد ایجاد AppWidgetHost
خود برای میزبانی ابزارک های برنامه، به ساخت میزبان ویجت مراجعه کنید.
برای کسب اطلاعات در مورد نحوه طراحی ویجت خود، به نمای کلی ابزارک های برنامه مراجعه کنید.
اجزای ویجت
برای ایجاد یک ویجت، به اجزای اصلی زیر نیاز دارید:
- شی
AppWidgetProviderInfo
- فراداده یک ویجت را توصیف می کند، مانند طرح بندی ویجت، فرکانس به روز رسانی، و کلاس
AppWidgetProvider
.AppWidgetProviderInfo
در XML تعریف شده است، همانطور که در این سند توضیح داده شده است. - کلاس
AppWidgetProvider
- روشهای اساسی را تعریف میکند که به شما امکان میدهد از طریق برنامهنویسی با ویجت ارتباط برقرار کنید. از طریق آن، هنگامی که ویجت به روز می شود، فعال می شود، غیرفعال می شود یا حذف می شود، پخش ها را دریافت می کنید. شما
AppWidgetProvider
در مانیفست اعلام می کنید و سپس آن را اجرا می کنید ، همانطور که در این سند توضیح داده شده است. - نمایش طرح
- طرح اولیه ویجت را تعریف می کند. طرح در XML تعریف شده است، همانطور که در این سند توضیح داده شده است.
شکل 2 نشان می دهد که چگونه این مؤلفه ها در جریان کلی پردازش ویجت برنامه قرار می گیرند.
![جریان پردازش ویجت برنامه](https://developer.android.com/static/images/appwidgets/flow-diagram.png?authuser=1&hl=fa)
اگر ویجت شما به پیکربندی کاربر نیاز دارد، فعالیت پیکربندی ویجت برنامه را اجرا کنید. این فعالیت به کاربران امکان میدهد تنظیمات ویجت را تغییر دهند - به عنوان مثال، منطقه زمانی ویجت ساعت.
- با شروع Android 12 (سطح API 31)، میتوانید یک پیکربندی پیشفرض ارائه دهید و به کاربران اجازه دهید بعداً ویجت را دوباره پیکربندی کنند. برای جزئیات بیشتر به استفاده از پیکربندی پیش فرض ویجت و فعال کردن کاربران برای پیکربندی مجدد ویجت های قرار داده شده مراجعه کنید.
- در اندروید 11 (سطح API 30) یا پایین تر، هر بار که کاربر ویجت را به صفحه اصلی خود اضافه می کند، این فعالیت راه اندازی می شود.
ما همچنین پیشرفتهای زیر را توصیه میکنیم: طرحبندی ویجتهای انعطافپذیر ، پیشرفتهای متفرقه ، ویجتهای پیشرفته ، ویجتهای مجموعه ، و ساخت میزبان ویجت .
AppWidgetProviderInfo XML را اعلام کنید
شی AppWidgetProviderInfo
کیفیت های اساسی یک ویجت را تعریف می کند. شی AppWidgetProviderInfo
را در یک فایل منبع XML با استفاده از یک عنصر <appwidget-provider>
تعریف کنید و آن را در پوشه res/xml/
پروژه ذخیره کنید.
این در مثال زیر نشان داده شده است:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
android:minWidth="40dp"
android:minHeight="40dp"
android:targetCellWidth="1"
android:targetCellHeight="1"
android:maxResizeWidth="250dp"
android:maxResizeHeight="120dp"
android:updatePeriodMillis="86400000"
android:description="@string/example_appwidget_description"
android:previewLayout="@layout/example_appwidget_preview"
android:initialLayout="@layout/example_loading_appwidget"
android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
android:resizeMode="horizontal|vertical"
android:widgetCategory="home_screen"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>
ویژگی های اندازه ویجت
صفحه اصلی پیشفرض، ویجتها را بر اساس شبکهای از سلولها که ارتفاع و عرض مشخصی دارند، در پنجره خود قرار میدهد. بیشتر صفحههای اصلی تنها به ابزارکها اجازه میدهند اندازههایی را بگیرند که مضرب صحیح سلولهای شبکه هستند - برای مثال، دو سلول به صورت افقی و سه سلول به صورت عمودی.
ویژگیهای اندازه ویجت به شما امکان میدهند یک اندازه پیشفرض برای ویجت خود تعیین کنید و محدودههای پایین و بالایی را برای اندازه ویجت ارائه دهید. در این زمینه، اندازه پیشفرض یک ویجت، اندازهای است که ویجت زمانی که برای اولین بار به صفحه اصلی اضافه میشود، میگیرد.
جدول زیر ویژگی های <appwidget-provider>
مربوط به اندازه ویجت را شرح می دهد:
صفات و شرح | |
---|---|
targetCellWidth و targetCellHeight (اندروید 12)، minWidth و minHeight |
targetCellWidth و targetCellHeight ، و minWidth و minHeight - را مشخص کنید تا اگر دستگاه کاربر از targetCellWidth و targetCellHeight پشتیبانی نمیکند، برنامه شما بتواند به استفاده از minWidth و minHeight بازگردد. در صورت پشتیبانی، ویژگیهای targetCellWidth و targetCellHeight بر ویژگیهای minWidth و minHeight اولویت دارند. |
minResizeWidth و minResizeHeight | حداقل اندازه مطلق ویجت را مشخص کنید. این مقادیر اندازه ای را که ویجت در آن ناخوانا یا غیرقابل استفاده است مشخص می کند. استفاده از این ویژگی ها به کاربر امکان می دهد اندازه ویجت را به اندازه ای کوچکتر از اندازه پیش فرض ویجت تغییر دهد. ویژگی minResizeWidth در صورتی که بزرگتر از minWidth باشد یا تغییر اندازه افقی فعال نباشد نادیده گرفته می شود. resizeMode ببینید. به همین ترتیب، ویژگی minResizeHeight در صورتی که بزرگتر از minHeight باشد یا تغییر اندازه عمودی فعال نباشد نادیده گرفته می شود. |
maxResizeWidth و maxResizeHeight | حداکثر اندازه توصیه شده ویجت را مشخص کنید. اگر مقادیر مضربی از ابعاد سلول شبکه نباشند، به نزدیکترین اندازه سلول گرد می شوند. مشخصه maxResizeWidth اگر کوچکتر از minWidth باشد یا تغییر اندازه افقی فعال نباشد نادیده گرفته می شود. resizeMode ببینید. به همین ترتیب، ویژگی maxResizeHeight در صورتی که بزرگتر از minHeight باشد یا تغییر اندازه عمودی فعال نباشد نادیده گرفته می شود. در اندروید 12 معرفی شد. |
resizeMode | قوانینی را مشخص می کند که با آن می توان اندازه یک ویجت را تغییر داد. می توانید از این ویژگی برای تغییر اندازه ویجت های صفحه اصلی به صورت افقی، عمودی یا در هر دو محور استفاده کنید. کاربران یک ویجت را لمس کرده و نگه می دارند تا دسته های تغییر اندازه آن را نشان دهند، سپس دستگیره های افقی یا عمودی را برای تغییر اندازه آن در شبکه طرح بندی بکشند. مقادیر برای ویژگی resizeMode شامل horizontal ، vertical ، و none است. برای اعلام یک ویجت به عنوان قابل تغییر اندازه افقی و عمودی، از horizontal|vertical استفاده کنید. |
مثال
برای نشان دادن اینکه چگونه ویژگی های جدول قبل بر اندازه ویجت تأثیر می گذارد، مشخصات زیر را در نظر بگیرید:
- یک سلول شبکه ای 30 dp عرض و 50 dp ارتفاع دارد.
- مشخصات ویژگی زیر ارائه شده است:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
android:minWidth="80dp"
android:minHeight="80dp"
android:targetCellWidth="2"
android:targetCellHeight="2"
android:minResizeWidth="40dp"
android:minResizeHeight="40dp"
android:maxResizeWidth="120dp"
android:maxResizeHeight="120dp"
android:resizeMode="horizontal|vertical" />
شروع با اندروید 12:
از ویژگی های targetCellWidth
و targetCellHeight
به عنوان اندازه پیش فرض ویجت استفاده کنید.
اندازه ویجت به طور پیش فرض 2x2 است. اندازه ویجت را می توان به 2x1 یا تا 4x3 تغییر داد.
اندروید 11 و پایین تر:
از ویژگی های minWidth
و minHeight
برای محاسبه اندازه پیش فرض ویجت استفاده کنید.
عرض پیش فرض = Math.ceil(80 / 30)
= 3
ارتفاع پیش فرض = Math.ceil(80 / 50)
= 2
اندازه ویجت به طور پیش فرض 3x2 است. اندازه ویجت را می توان به 2x1 یا تا تمام صفحه تغییر داد.
ویژگی های ویجت اضافی
جدول زیر ویژگی های <appwidget-provider>
مربوط به کیفیت هایی غیر از اندازه ویجت را توضیح می دهد.
صفات و شرح | |
---|---|
updatePeriodMillis | تعیین می کند که فریم ورک ویجت هر چند وقت یکبار از AppWidgetProvider درخواست به روز رسانی می کند با فراخوانی متد onUpdate() callback. تضمین نمیشود که بهروزرسانی واقعی با این مقدار دقیقاً به موقع انجام شود، و توصیه میکنیم تا حد امکان به ندرت - حداکثر یک بار در ساعت - برای صرفهجویی در باتری بهروزرسانی کنید. برای فهرست کامل ملاحظات برای انتخاب دوره بهروزرسانی مناسب، به بهینهسازیها برای بهروزرسانی محتوای ویجت مراجعه کنید. |
initialLayout | به منبع طرحبندی که طرحبندی ویجت را تعریف میکند، اشاره میکند. |
configure | فعالیتی را تعریف میکند که وقتی کاربر ویجت را اضافه میکند، راهاندازی میشود و به او اجازه میدهد خصوصیات ویجت را پیکربندی کند. به فعال کردن کاربران برای پیکربندی ابزارک ها مراجعه کنید. با شروع Android 12، برنامه شما می تواند از پیکربندی اولیه صرف نظر کند. برای جزئیات بیشتر به استفاده از پیکربندی پیش فرض ویجت مراجعه کنید. |
description | شرحی را برای انتخابگر ویجت برای نمایش ویجت شما مشخص می کند. در اندروید 12 معرفی شد. |
previewLayout (اندروید 12) و previewImage (اندروید 11 و پایین تر) |
previewImage و previewLayout را مشخص کنید تا اگر دستگاه کاربر از previewLayout پشتیبانی نمیکند، برنامه شما بتواند به استفاده از previewImage بازگردد. برای جزئیات بیشتر، به سازگاری به عقب با پیش نمایش ویجت های مقیاس پذیر مراجعه کنید. |
autoAdvanceViewId | شناسه نمای زیرنمای ویجت را مشخص می کند که توسط میزبان ویجت به طور خودکار پیشرفته می شود. |
widgetCategory | اعلام میکند که آیا ویجت شما میتواند در صفحه اصلی ( home_screen )، صفحه قفل ( keyguard )، یا هر دو نمایش داده شود. برای Android نسخه 5.0 و بالاتر، فقط home_screen معتبر است. |
widgetFeatures | ویژگی های پشتیبانی شده توسط ویجت را اعلام می کند. به عنوان مثال، اگر میخواهید وقتی کاربر ویجت را اضافه میکند، از پیکربندی پیشفرض خود استفاده کند، هر دو پرچم configuration_optional و reconfigurable را مشخص کنید. این کار راه اندازی فعالیت پیکربندی را پس از افزودن ویجت توسط کاربر دور می زند. کاربر همچنان می تواند پس از آن ویجت را دوباره پیکربندی کند . |
از کلاس AppWidgetProvider برای مدیریت پخش ویجت استفاده کنید
کلاس AppWidgetProvider
پخش ویجت را مدیریت می کند و ویجت را در پاسخ به رویدادهای چرخه حیات ویجت به روز می کند. بخش های زیر نحوه اعلان AppWidgetProvider
در مانیفست و سپس پیاده سازی آن را توضیح می دهد.
یک ویجت را در مانیفست اعلام کنید
ابتدا طبق مثال زیر، کلاس AppWidgetProvider
را در فایل AndroidManifest.xml
برنامه خود اعلام کنید:
<receiver android:name="ExampleAppWidgetProvider"
android:exported="false">
<intent-filter>
<action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
</intent-filter>
<meta-data android:name="android.appwidget.provider"
android:resource="@xml/example_appwidget_info" />
</receiver>
عنصر <receiver>
به ویژگی android:name
نیاز دارد که AppWidgetProvider
مورد استفاده ویجت را مشخص می کند. مؤلفه نباید صادر شود مگر اینکه نیاز باشد یک فرآیند جداگانه به AppWidgetProvider
شما پخش شود، که معمولاً اینطور نیست.
عنصر <intent-filter>
باید دارای عنصر <action>
با ویژگی android:name
باشد. این ویژگی مشخص می کند که AppWidgetProvider
پخش ACTION_APPWIDGET_UPDATE
را می پذیرد. این تنها پخشی است که باید به صراحت اعلام کنید. AppWidgetManager
به طور خودکار سایر پخشهای ویجت را در صورت لزوم به AppWidgetProvider
ارسال میکند.
عنصر <meta-data>
منبع AppWidgetProviderInfo
را مشخص می کند و به ویژگی های زیر نیاز دارد:
-
android:name
: نام ابرداده را مشخص می کند. ازandroid.appwidget.provider
برای شناسایی داده ها به عنوان توصیفگرAppWidgetProviderInfo
استفاده کنید. -
android:resource
: محل منبعAppWidgetProviderInfo
را مشخص می کند.
کلاس AppWidgetProvider را پیاده سازی کنید
کلاس AppWidgetProvider
BroadcastReceiver
به عنوان یک کلاس راحت برای مدیریت پخش ویجت گسترش می دهد. فقط پخش رویدادهایی را دریافت می کند که مربوط به ویجت هستند، مانند زمانی که ویجت به روز می شود، حذف می شود، فعال و غیرفعال می شود. هنگامی که این رویدادهای پخش رخ می دهند، متدهای AppWidgetProvider
زیر فراخوانی می شوند:
-
onUpdate()
- این برای به روز رسانی ویجت در فواصل زمانی مشخص شده توسط ویژگی
updatePeriodMillis
درAppWidgetProviderInfo
نامیده می شود. برای اطلاعات بیشتر به جدولی که ویژگیهای ویجت اضافی را در این صفحه توضیح میدهد، مراجعه کنید. - این روش زمانی که کاربر ویجت را اضافه میکند نیز نامیده میشود، بنابراین تنظیمات ضروری مانند تعریف کنترلکنندههای رویداد برای
View
اشیاء یا شروع کارها برای بارگیری دادهها برای نمایش در ویجت را انجام میدهد. با این حال، اگر یک فعالیت پیکربندی را بدون پرچمconfiguration_optional
اعلام کنید، این روش زمانی که کاربر ویجت را اضافه می کند فراخوانی نمی شود، اما برای به روز رسانی های بعدی فراخوانی می شود . این مسئولیت فعالیت پیکربندی است که پس از تکمیل پیکربندی، اولین به روز رسانی را انجام دهد. برای اطلاعات بیشتر به فعال کردن کاربران برای پیکربندی ابزارکهای برنامه رجوع کنید. - مهم ترین callback
onUpdate()
است. برای اطلاعات بیشتر به Handle events با کلاسonUpdate()
در این صفحه مراجعه کنید. -
onAppWidgetOptionsChanged()
هنگامی که ویجت برای اولین بار قرار می گیرد و هر زمانی که اندازه ویجت تغییر می کند، این نام خوانده می شود. از این تماس برای نمایش یا پنهان کردن محتوا بر اساس محدوده اندازه ویجت استفاده کنید. با فراخوانی
getAppWidgetOptions()
کهBundle
شامل موارد زیر را برمیگرداند، محدودههای اندازه را دریافت کنید - و با شروع Android 12، فهرستی از اندازههای احتمالی که یک نمونه ویجت میتواند بگیرد.-
OPTION_APPWIDGET_MIN_WIDTH
: شامل کران پایینی در عرض، به واحدهای dp، نمونه ویجت است. -
OPTION_APPWIDGET_MIN_HEIGHT
: شامل کران پایینی در ارتفاع، به واحدهای dp، نمونه ویجت است. -
OPTION_APPWIDGET_MAX_WIDTH
: شامل کران بالایی در عرض، به واحدهای dp، نمونه ویجت است. -
OPTION_APPWIDGET_MAX_HEIGHT
: شامل کران بالای ارتفاع، به واحدهای dp، نمونه ویجت است. -
OPTION_APPWIDGET_SIZES
: حاوی لیستی از اندازه های ممکن (List<SizeF>
) در واحدهای dp است که یک نمونه ویجت می تواند بگیرد. در اندروید 12 معرفی شد.
-
-
onDeleted(Context, int[])
هر بار که یک ویجت از میزبان ویجت حذف می شود، این نام خوانده می شود.
-
onEnabled(Context)
هنگامی که یک نمونه از ویجت برای اولین بار ایجاد می شود، این نام خوانده می شود. به عنوان مثال، اگر کاربر دو نمونه از ویجت شما را اضافه کند، این تنها بار اول فراخوانی می شود. اگر نیاز به باز کردن یک پایگاه داده جدید یا انجام تنظیمات دیگری دارید که فقط باید یک بار برای همه نمونه های ویجت انجام شود، این مکان مناسبی برای انجام آن است.
-
onDisabled(Context)
این زمانی فراخوانی می شود که آخرین نمونه ویجت شما از میزبان ویجت حذف شود. این جایی است که شما هر کاری را که در
onEnabled(Context)
انجام می شود، مانند حذف یک پایگاه داده موقت، پاک می کنید.-
onReceive(Context, Intent)
این برای هر پخش و قبل از هر یک از روش های برگشت تماس قبلی فراخوانی می شود. شما معمولاً نیازی به پیادهسازی این روش ندارید، زیرا اجرای پیشفرض
AppWidgetProvider
همه پخشهای ویجت را فیلتر میکند و روشهای قبلی را در صورت لزوم فراخوانی میکند.
شما باید پیاده سازی کلاس AppWidgetProvider
خود را به عنوان گیرنده پخش با استفاده از عنصر <receiver>
در AndroidManifest
اعلام کنید. برای اطلاعات بیشتر به اعلام ویجت در مانیفست در این صفحه مراجعه کنید.
رویدادها را با کلاس onUpdate() مدیریت کنید
مهم ترین فراخوانی AppWidgetProvider
onUpdate()
است، زیرا زمانی که هر ویجت به یک میزبان اضافه می شود، فراخوانی می شود، مگر اینکه از یک فعالیت پیکربندی بدون پرچم configuration_optional
استفاده کنید. اگر ویجت شما رویدادهای تعامل کاربر را می پذیرد، کنترل کننده های رویداد را در این پاسخ به تماس ثبت کنید. اگر ویجت شما فایلها یا پایگاه دادههای موقتی ایجاد نمیکند، یا کارهای دیگری که نیاز به پاکسازی دارند انجام نمیدهد، ممکن است onUpdate()
تنها روشی باشد که باید تعریف کنید.
به عنوان مثال، اگر ویجتی با دکمه ای می خواهید که با ضربه زدن یک فعالیت را راه اندازی کند، می توانید از پیاده سازی زیر AppWidgetProvider
استفاده کنید:
کاتلین
class ExampleAppWidgetProvider : AppWidgetProvider() { override fun onUpdate( context: Context, appWidgetManager: AppWidgetManager, appWidgetIds: IntArray ) { // Perform this loop procedure for each widget that belongs to this // provider. appWidgetIds.forEach { appWidgetId -> // Create an Intent to launch ExampleActivity. val pendingIntent: PendingIntent = PendingIntent.getActivity( /* context = */ context, /* requestCode = */ 0, /* intent = */ Intent(context, ExampleActivity::class.java), /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE ) // Get the layout for the widget and attach an onClick listener to // the button. val views: RemoteViews = RemoteViews( context.packageName, R.layout.appwidget_provider_layout ).apply { setOnClickPendingIntent(R.id.button, pendingIntent) } // Tell the AppWidgetManager to perform an update on the current // widget. appWidgetManager.updateAppWidget(appWidgetId, views) } } }
جاوا
public class ExampleAppWidgetProvider extends AppWidgetProvider { public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { // Perform this loop procedure for each widget that belongs to this // provider. for (int i=0; i < appWidgetIds.length; i++) { int appWidgetId = appWidgetIds[i]; // Create an Intent to launch ExampleActivity Intent intent = new Intent(context, ExampleActivity.class); PendingIntent pendingIntent = PendingIntent.getActivity( /* context = */ context, /* requestCode = */ 0, /* intent = */ intent, /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE ); // Get the layout for the widget and attach an onClick listener to // the button. RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget_layout); views.setOnClickPendingIntent(R.id.button, pendingIntent); // Tell the AppWidgetManager to perform an update on the current app // widget. appWidgetManager.updateAppWidget(appWidgetId, views); } } }
این AppWidgetProvider
تنها متد onUpdate()
را تعریف میکند و از آن برای ایجاد یک PendingIntent
استفاده میکند که یک Activity
را راهاندازی میکند و آن را با استفاده از setOnClickPendingIntent(int, PendingIntent)
به دکمه ویجت متصل میکند. این شامل یک حلقه است که از طریق هر ورودی در appWidgetIds
تکرار میشود، که آرایهای از شناسهها است که هر ویجت ایجاد شده توسط این ارائهدهنده را شناسایی میکند. اگر کاربر بیش از یک نمونه از ویجت را ایجاد کند، همه آنها به طور همزمان به روز می شوند. با این حال، تنها یک برنامه updatePeriodMillis
برای همه نمونههای ویجت مدیریت میشود. به عنوان مثال، اگر زمانبندی بهروزرسانی هر دو ساعت یک بار تعریف شده باشد، و یک نمونه دوم از ویجت یک ساعت پس از اولین مورد اضافه شود، هر دو در دوره تعریفشده توسط دوره اول و دوم بهروزرسانی میشوند. نادیده گرفته می شود. هر دوی آنها هر دو ساعت یک بار به روز می شوند، نه هر ساعت.
برای جزئیات بیشتر به کلاس نمونه ExampleAppWidgetProvider.java
مراجعه کنید.
اهداف پخش ویجت را دریافت کنید
AppWidgetProvider
یک کلاس راحتی است. اگر میخواهید پخشهای ویجت را مستقیماً دریافت کنید، میتوانید BroadcastReceiver
خود را پیادهسازی کنید یا پاسخ تماس onReceive(Context,Intent)
را لغو کنید. اهدافی که باید به آنها اهمیت دهید موارد زیر است:
-
ACTION_APPWIDGET_UPDATE
-
ACTION_APPWIDGET_DELETED
-
ACTION_APPWIDGET_ENABLED
-
ACTION_APPWIDGET_DISABLED
-
ACTION_APPWIDGET_OPTIONS_CHANGED
طرح بندی ویجت را ایجاد کنید
شما باید یک طرح اولیه برای ویجت خود در XML تعریف کنید و آن را در دایرکتوری res/layout/
پروژه ذخیره کنید. برای جزئیات به دستورالعمل های طراحی مراجعه کنید.
اگر با طرحبندیها آشنایی دارید، ایجاد طرحبندی ویجت ساده است. با این حال، توجه داشته باشید که طرحبندی ویجتها بر اساس RemoteViews
هستند که از هر نوع طرحبندی یا ویجت مشاهده پشتیبانی نمیکنند. شما نمی توانید از نماهای سفارشی یا زیر کلاس های نماهایی که توسط RemoteViews
پشتیبانی می شوند استفاده کنید.
RemoteViews
همچنین از ViewStub
پشتیبانی می کند، که یک View
نامرئی و با اندازه صفر است که می توانید از آن برای افزایش تنبلی منابع طرح در زمان اجرا استفاده کنید.
حمایت از رفتار دولتی
Android 12 با استفاده از مؤلفههای موجود زیر، از رفتار حالتپذیر پشتیبانی میکند:
ویجت هنوز بدون وضعیت است. برنامه شما باید وضعیت را ذخیره کند و برای رویدادهای تغییر وضعیت ثبت نام کند.
![نمونه ای از ویجت لیست خرید که رفتار حالتی را نشان می دهد](https://developer.android.com/static/images/appwidgets/home.png?authuser=1&hl=fa)
مثال کد زیر نحوه پیاده سازی این کامپوننت ها را نشان می دهد.
کاتلین
// 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));
دو طرحبندی ارائه دهید: یکی دستگاههای دارای Android 12 یا بالاتر در res/layout-v31
و دیگری هدف قرار دادن Android 11 یا پایینتر در پوشه res/layout
پیشفرض.
گوشه های گرد را اجرا کنید
Android 12 پارامترهای سیستم زیر را برای تنظیم شعاع گوشه های گرد ویجت شما معرفی می کند:
system_app_widget_background_radius
: شعاع گوشه پسزمینه ویجت، که هرگز بزرگتر از 28 dp نیست.system_app_widget_inner_radius
: شعاع گوشه هر نمای داخل ویجت. این دقیقاً 8 dp کمتر از شعاع پسزمینه است تا در هنگام استفاده از یک لایهبندی 8 dp به خوبی تراز شود.
مثال زیر ویجتی را نشان می دهد که از system_app_widget_background_radius
برای گوشه ویجت و system_app_widget_inner_radius
برای نماهای داخل ویجت استفاده می کند.
![ویجتی که شعاع پسزمینه ویجت و نماهای داخل ویجت را نشان میدهد](https://developer.android.com/static/images/appwidgets/widget-weather.png?authuser=1&hl=fa)
1 گوشه ویجت.
2 گوشه نما در داخل ویجت.
ملاحظات مهم برای گوشه های گرد
- راهاندازهای شخص ثالث و سازندگان دستگاه میتوانند پارامتر
system_app_widget_background_radius
را نادیده بگیرند تا کمتر از 28 dp باشد. پارامترsystem_app_widget_inner_radius
همیشه 8 dp کمتر از مقدارsystem_app_widget_background_radius
است. - اگر ویجت شما از
@android:id/background
استفاده نمیکند یا پسزمینهای را تعریف نمیکند که محتوای آن را بر اساس طرح کلی برش میدهد - با تنظیمandroid:clipToOutline
رویtrue
- راهانداز بهطور خودکار پسزمینه را شناسایی میکند و ویجت را با استفاده از یک مستطیل با گوشههای گرد برش میدهد. تا 16 dp اطمینان حاصل کنید که ویجت شما با Android 12 سازگار است .
برای سازگاری ویجت با نسخههای قبلی Android، توصیه میکنیم ویژگیهای سفارشی را تعریف کنید و از یک تم سفارشی برای لغو آنها برای Android 12 استفاده کنید، همانطور که در فایلهای XML نمونه زیر نشان داده شده است:
/values/attrs.xml
<resources>
<attr name="backgroundRadius" format="dimension" />
</resources>
/values/styles.xml
<resources>
<style name="MyWidgetTheme">
<item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
</style>
</resources>
/values-31/styles.xml
<resources>
<style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
<item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
</style>
</resources>
/drawable/my_widget_background.xml
<shape xmlns:android="http://schemas.android.com/apk/res/android"
android:shape="rectangle">
<corners android:radius="?attr/backgroundRadius" />
...
</shape>
/layout/my_widget_layout.xml
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
...
android:background="@drawable/my_widget_background" />