این صفحه شامل جزئیاتی برای بهبودهای اختیاری ویجت است که از Android 12 در دسترس هستند (سطح API 31). این ویژگی ها اختیاری هستند، اما برای پیاده سازی و بهبود تجربه ویجت کاربران شما ساده هستند.
از رنگ های پویا استفاده کنید
با شروع اندروید 12، یک ویجت میتواند از رنگهای تم دستگاه برای دکمهها، پسزمینهها و سایر اجزا استفاده کند. این انتقال نرمتر و سازگاری را در بین ویجتهای مختلف فراهم میکند.
دو راه برای دستیابی به رنگ های پویا وجود دارد:
از تم پیشفرض سیستم (
@android:style/Theme.DeviceDefault.DayNight
) در طرحبندی اصلی استفاده کنید.از طرح زمینه Material 3 (
Theme.Material3.DynamicColors.DayNight
) از کتابخانه Material Components برای Android استفاده کنید که در Material Components برای Android نسخه 1.6.0 موجود است.
هنگامی که موضوع در چیدمان ریشه تنظیم شد، می توانید از ویژگی های رنگ رایج در ریشه یا هر یک از فرزندان آن برای انتخاب رنگ های پویا استفاده کنید.
چند نمونه از ویژگی های رنگی که می توانید استفاده کنید به شرح زیر است:
-
?attr/primary
-
?attr/primaryContainer
-
?attr/onPrimary
-
?attr/onPrimaryContainer
در مثال زیر با استفاده از تم Material 3، رنگ تم دستگاه "بنفش" است. رنگ تاکیدی و پسزمینه ویجت برای حالتهای روشن و تاریک مطابقت دارد، همانطور که در شکلهای 1 و 2 نشان داده شده است.
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:background="?attr/colorPrimaryContainer"
android:theme="@style/Theme.Material3.DynamicColors.DayNight">
<ImageView
...
app:tint="?attr/colorPrimaryContainer"
android:src="@drawable/ic_partly_cloudy" />
<!-- Other widget content. -->
</LinearLayout>
![ویجت در تم حالت روشن](https://developer.android.com/static/images/appwidgets/example-lightmode.png?hl=fa)
![ویجت ها در تم حالت تاریک](https://developer.android.com/static/images/appwidgets/example-darkmode.png?hl=fa)
سازگاری با عقب برای رنگ های پویا
رنگهای پویا فقط در دستگاههای دارای اندروید ۱۲ یا بالاتر در دسترس هستند. برای ارائه یک طرح زمینه سفارشی برای نسخههای پایینتر، با استفاده از ویژگیهای تم پیشفرض، یک تم پیشفرض با رنگهای سفارشی خود و یک واجد شرایط جدید ( values-v31
) ایجاد کنید.
در اینجا یک مثال با استفاده از موضوع Material 3 آورده شده است:
/values/styles.xml
<resources>
<style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
<!-- Override default colorBackground attribute with custom color. -->
<item name="android:colorBackground">@color/my_background_color</item>
<!-- Add other colors/attributes. -->
</style>
</resources>
/values-v31/styles.xml
<resources>
<!-- Do not override any color attribute. -->
<style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>
/layout/my_widget_layout.xml
<resources>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
...
android:background="?android:attr/colorBackground"
android:theme="@style/MyWidgetTheme" />
</resources>
پشتیبانی صوتی را فعال کنید
App Actions به Google Assistant اجازه میدهد ویجتها را در پاسخ به دستورات صوتی کاربر نشان دهد. با پیکربندی ویجت خود برای پاسخ به مقاصد داخلی (BII) ، برنامه شما میتواند به طور فعال ویجتها را روی سطوح دستیار مانند Android و Android Auto نمایش دهد. کاربران این گزینه را دارند که ویجتهای نمایش داده شده توسط Assistant را به لانچر خود پین کنند ، که این امر باعث تشویق در تعامل در آینده میشود.
برای مثال، میتوانید ویجت خلاصه تمرین را برای برنامه تمرین خود پیکربندی کنید تا دستورات صوتی کاربر را که GET_EXERCISE_OBSERVATION
BII را راهاندازی میکنند، انجام دهد. وقتی کاربران این BII را فعال میکنند، «دستیار» با درخواستهایی مانند «Hey Google، چند مایل در این هفته در ExampleApp دویدم؟» به طور فعال ویجت شما را نمایش میدهد؟
دهها BII وجود دارد که چندین دسته از تعاملات کاربر را پوشش میدهد و تقریباً به هر برنامه اندرویدی اجازه میدهد ویجتهای خود را برای صدا ارتقا دهد. برای شروع، به ادغام اقدامات برنامه با ویجت های Android مراجعه کنید.
تجربه انتخابگر ویجت برنامه خود را بهبود بخشید
Android 12 به شما امکان می دهد با افزودن پیش نمایش ویجت پویا و توضیحات ویجت، تجربه انتخابگر ویجت را برای برنامه خود بهبود بخشید.
پیش نمایش ویجت های مقیاس پذیر را به انتخابگر ویجت اضافه کنید
با شروع در اندروید 12، پیش نمایش ویجت نمایش داده شده در انتخابگر ویجت مقیاس پذیر است. شما آن را به عنوان یک طرح بندی XML با اندازه پیش فرض ویجت ارائه می کنید. پیش از این، پیشنمایش ویجت یک منبع قابل ترسیم ثابت بود، که در برخی موارد منجر به پیشنمایشهایی میشد که نحوه نمایش ویجتها را هنگام اضافه شدن به صفحه اصلی نشان میداد.
برای پیادهسازی پیشنمایشهای ویجت مقیاسپذیر، از ویژگی previewLayout
عنصر appwidget-provider
برای ارائه یک طرح XML استفاده کنید:
<appwidget-provider
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
توصیه میکنیم از همان طرحبندی ویجت واقعی، با مقادیر پیشفرض یا آزمایش واقعی استفاده کنید. اکثر برنامه ها از همان previewLayout
و initialLayout
استفاده می کنند. برای راهنمایی در مورد ایجاد طرحبندیهای پیشنمایش دقیق، بخش زیر را در این صفحه ببینید.
توصیه میکنیم هر دو ویژگی previewLayout
و previewImage
را مشخص کنید تا اگر دستگاه کاربر از previewLayout
پشتیبانی نمیکند، برنامه شما بتواند دوباره به استفاده از previewImage
برود. ویژگی previewLayout
بر ویژگی previewImage
اولویت دارد.
روش های پیشنهادی برای ساخت پیش نمایش های دقیق
برای پیاده سازی پیش نمایش ویجت های مقیاس پذیر، از ویژگی previewLayout
عنصر appwidget-provider
برای ارائه یک طرح XML استفاده کنید:
<appwidget-provider
...
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
![تصویری که پیش نمایش ویجت را نشان می دهد](https://developer.android.com/static/images/appwidgets/todo-list-groceries.png?hl=fa)
برای نمایش یک پیشنمایش دقیق، میتوانید با انجام مراحل زیر مستقیماً طرحبندی واقعی ویجت را با مقادیر پیشفرض ارائه کنید:
تنظیم
android:text="@string/my_widget_item_fake_1"
برای عناصرTextView
.تنظیم یک تصویر یا نماد پیشفرض یا مکاننما، مانند
android:src="@drawable/my_widget_icon"
، برای اجزایImageView
.
بدون مقادیر پیشفرض، پیشنمایش ممکن است مقادیر نادرست یا خالی را نشان دهد. یکی از مزایای مهم این رویکرد این است که می توانید محتوای پیش نمایش محلی را ارائه دهید.
برای رویکردهای توصیهشده برای پیشنمایشهای پیچیدهتر که حاوی ListView
، GridView
، یا StackView
هستند، برای جزئیات بیشتر به ساخت پیشنمایشهای دقیق که شامل موارد پویا هستند، مراجعه کنید.
سازگاری به عقب با پیش نمایش ویجت های مقیاس پذیر
برای اینکه انتخابکنندگان ویجت در Android 11 (سطح API 30) یا پایینتر، پیشنمایشهای ویجت شما را نشان دهند، ویژگی previewImage
مشخص کنید.
اگر ظاهر ویجت را تغییر دادید، تصویر پیش نمایش را به روز کنید.
توضیحاتی برای ویجت خود اضافه کنید
با شروع اندروید 12، توضیحاتی را برای انتخابگر ویجت ارائه دهید تا برای ویجت شما نمایش داده شود.
![تصویری که انتخابگر ویجت را نشان می دهد که ویجت و توضیحات آن را نشان می دهد](https://developer.android.com/static/images/appwidgets/description.png?hl=fa)
با استفاده از ویژگی description
<appwidget-provider>
عنصر:
<appwidget-provider
android:description="@string/my_widget_description">
</appwidget-provider>
میتوانید از ویژگی descriptionRes
در نسخههای قبلی اندروید استفاده کنید، اما توسط انتخابگر ویجت نادیده گرفته میشود.
انتقال نرمتر را فعال کنید
با شروع اندروید 12، زمانی که کاربر برنامه شما را از ویجت راه اندازی می کند، لانچرها انتقال نرم تری را ارائه می دهند.
برای فعال کردن این انتقال بهبودیافته، از @android:id/background
یا android.R.id.background
برای شناسایی عنصر پسزمینه خود استفاده کنید:
// Top-level layout of the widget.
<LinearLayout
android:id="@android:id/background">
</LinearLayout>
برنامه شما میتواند از @android:id/background
در نسخههای قبلی اندروید بدون شکستگی استفاده کند، اما نادیده گرفته میشود.
از اصلاح زمان اجرا RemoteViews استفاده کنید
با شروع اندروید 12، میتوانید از چندین روش RemoteViews
استفاده کنید که امکان اصلاح زمان اجرا ویژگیهای RemoteViews
را فراهم میکند. برای لیست کامل روش های اضافه شده به مرجع RemoteViews
API مراجعه کنید.
مثال کد زیر نحوه استفاده از تعدادی از این روش ها را نشان می دهد.
کاتلین
// Set the colors of a progress bar at runtime. remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList()) // Specify exact sizes for margins. remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)
جاوا
// Set the colors of a progress bar at runtime. remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList()); // Specify exact sizes for margins. remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);