برای بهبود تجربه انتخابگر ویجت برنامه خود، یک پیشنمایش ویجت تولید شده در دستگاههای اندروید ۱۵ و بالاتر، یک پیشنمایش ویجت مقیاسپذیر (با مشخص کردن previewLayout ) برای دستگاههای اندروید ۱۲ تا اندروید ۱۴ و یک previewImage برای نسخههای قبلی ارائه دهید.
پیشنمایشهای ویجت تولید شده به شما امکان میدهند پیشنمایشهای پویا و شخصیسازیشدهای برای ویجتهای خود ایجاد کنید که دقیقاً نحوه نمایش آنها در صفحه اصلی کاربر را منعکس میکنند. برای اندروید ۱۵ و بالاتر، این پیشنمایشها از طریق یک API ارائه میشوند، به این معنی که برنامه شما پیشنمایش را در هر نقطه از چرخه عمر خود بدون دریافت درخواست صریح از میزبان ویجت ارائه میدهد.
برای اطلاعات بیشتر، به بخش «غنیسازی برنامه با بهروزرسانیهای زنده و ویجتها در یوتیوب» مراجعه کنید.
پیشنمایشهای تولید شده را اضافه کنید
برای نمایش پیشنمایشهای ویجت تولید شده در دستگاه اندروید ۱۵ یا بالاتر، ابتدا مقدار compileSdk را در فایل build.gradle ماژول روی ۳۵ یا بالاتر تنظیم کنید تا بتوانید RemoteViews به انتخابگر ویجت ارائه دهید.
برنامهها میتوانند setWidgetPreview در AppWidgetManager استفاده کنند. برای جلوگیری از سوءاستفاده و کاهش نگرانیهای مربوط به سلامت سیستم، setWidgetPreview یک API با نرخ محدود است. محدودیت پیشفرض تقریباً دو فراخوانی در ساعت است.
هیچ فراخوانی از سیستم برای ارائه پیشنمایشها وجود ندارد، بنابراین برنامه شما باید تصمیم بگیرد که چه زمانی setWidgetPreviews فراخوانی کند. استراتژی بهروزرسانی به مورد استفاده ویجت شما بستگی دارد:
- اگر ویجت اطلاعات ثابتی دارد یا یک اقدام سریع است، پیشنمایش را هنگام اولین اجرای برنامه تنظیم کنید.
- میتوانید پیشنمایش را زمانی تنظیم کنید که برنامه شما دادهها را دریافت کرده باشد؛ برای مثال، پس از ورود کاربر یا راهاندازی اولیه.
- میتوانید یک وظیفه دورهای تنظیم کنید تا پیشنمایشها را با ریتمی مشخص بهروزرسانی کند.
مثال زیر یک منبع طرحبندی ویجت XML را بارگذاری کرده و آن را به عنوان پیشنمایش تنظیم میکند. برای نمایش setWidgetPreview به عنوان یک متد در این قطعه کد، تنظیم ساخت compileSdk روی ۳۵ یا بالاتر لازم است.
AppWidgetManager.getInstance(appContext).setWidgetPreview(
ComponentName(
appContext,
ExampleAppWidgetReceiver::class.java
),
AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
RemoteViews("com.example", R.layout.widget_preview)
)
پیشنمایشهای ویجت مقیاسپذیر را اضافه کنید
از اندروید ۱۲ به بعد، پیشنمایش ویجت نمایش داده شده در انتخابگر ویجت، مقیاسپذیر است. شما آن را به عنوان یک طرحبندی XML که روی اندازه پیشفرض ویجت تنظیم شده است، ارائه میدهید. پیش از این، پیشنمایش ویجت یک منبع قابل ترسیم استاتیک بود که در برخی موارد منجر به پیشنمایشهایی میشد که به طور نادرست نحوه نمایش ویجتها را هنگام اضافه شدن به صفحه اصلی منعکس میکردند.
برای پیادهسازی پیشنمایشهای ویجت مقیاسپذیر، از ویژگی previewLayout از عنصر appwidget-provider برای ارائه یک طرحبندی XML استفاده کنید:
<appwidget-provider
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
توصیه میکنیم از همان طرحبندی ویجت واقعی، با مقادیر پیشفرض یا آزمایشی واقعبینانه، استفاده کنید. اکثر برنامهها از previewLayout و initialLayout یکسانی استفاده میکنند. برای راهنمایی در مورد ایجاد طرحبندیهای پیشنمایش دقیق، به Build accurate previews that include dynamic items مراجعه کنید.
توصیه میکنیم هر دو ویژگی previewLayout و previewImage را مشخص کنید تا در صورت عدم پشتیبانی دستگاه کاربر previewLayout ، برنامه شما بتواند به استفاده از previewImage بازگردد. ویژگی previewLayout بر ویژگی previewImage اولویت دارد.
پیشنمایشهای ویجت ثابت را برای سازگاری با نسخههای قبلی اضافه کنید
برای اینکه انتخابگرهای ویجت در اندروید ۱۱ (سطح API 30) یا پایینتر، پیشنمایشهایی از ویجت شما را نمایش دهند، یا به عنوان جایگزینی برای پیشنمایشهای مقیاسپذیر، ویژگی previewImage را مشخص کنید.
اگر ظاهر ویجت را تغییر میدهید، تصویر پیشنمایش را بهروزرسانی کنید.
این ویژگی همچنین به عنوان یک جایگزین برای پیشنمایشهای تولید شده استفاده میشود اگر آن را با استفاده از setWidgetPreview تنظیم نکرده باشید.
پیشنمایشهای دقیقی بسازید که شامل موارد پویا باشند
این بخش رویکرد پیشنهادی برای نمایش چندین آیتم در پیشنمایش ویجت برای ویجتی با نمای مجموعه - یعنی ویجتی که از ListView ، GridView یا StackView استفاده میکند - را توضیح میدهد. این موضوع در مورد پیشنمایشهای ویجت مقیاسپذیر صدق میکند، نه پیشنمایشهای تولید شده.
اگر ویجت شما از یکی از این نماها استفاده میکند، ایجاد یک پیشنمایش مقیاسپذیر با ارائه طرحبندی ویجت واقعی به طور مستقیم در previewLayout میتواند تجربه را هنگامی که پیشنمایش ویجت هیچ آیتمی را نمایش نمیدهد، خراب کند. این اتفاق میافتد زیرا دادههای نمای مجموعه به صورت پویا در زمان اجرا تنظیم میشوند و شبیه به تصویر نشان داده شده در شکل 1 به نظر میرسند.
برای اینکه پیشنمایش ویجتها با نماهای مجموعه به درستی در انتخابگر ویجت نمایش داده شود، توصیه میکنیم یک فایل طرحبندی جداگانه که فقط برای پیشنمایش در نظر گرفته شده است، نگه دارید. این فایل طرحبندی جداگانه باید شامل موارد زیر باشد:
- طرحبندی واقعی ویجت.
- یک placeholder collection view با آیتمهای جعلی. برای مثال، میتوانید با ارائه یک placeholder
LinearLayoutبا چندین آیتم لیست جعلی، از یکListViewتقلید کنید.
برای نشان دادن مثالی برای ListView ، با یک فایل طرحبندی جداگانه شروع کنید:
// res/layout/widget_preview.xml
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="@drawable/widget_background"
android:orientation="vertical">
// Include the actual widget layout that contains ListView.
<include
layout="@layout/widget_view"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
// The number of fake items you include depends on the values you provide
// for minHeight or targetCellHeight in the AppWidgetProviderInfo
// definition.
<TextView android:text="@string/fake_item1"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginVertical="?attr/appWidgetInternalPadding" />
<TextView android:text="@string/fake_item2"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginVertical="?attr/appWidgetInternalPadding" />
</LinearLayout>
هنگام ارائه ویژگی previewLayout از فراداده AppWidgetProviderInfo فایل طرحبندی پیشنمایش را مشخص کنید. شما همچنان طرحبندی واقعی ویجت را برای ویژگی initialLayout مشخص میکنید و هنگام ساخت یک RemoteViews در زمان اجرا، از طرحبندی واقعی ویجت استفاده میکنید.
<appwidget-provider
previewLayout="@layout/widget_preview"
initialLayout="@layout/widget_view" />
موارد لیست پیچیده
مثال بخش قبل، آیتمهای لیست جعلی ارائه میدهد، زیرا آیتمهای لیست، اشیاء TextView هستند. اگر آیتمها طرحبندیهای پیچیدهای داشته باشند، ارائه آیتمهای جعلی میتواند پیچیدهتر باشد.
یک آیتم لیست را در نظر بگیرید که در widget_list_item.xml تعریف شده و از دو شیء TextView تشکیل شده است:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="wrap_content">
<TextView android:id="@id/title"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="@string/fake_title" />
<TextView android:id="@id/content"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="@string/fake_content" />
</LinearLayout>
برای ارائه موارد لیست جعلی، میتوانید طرحبندی را چندین بار وارد کنید، اما این باعث میشود که هر مورد لیست یکسان باشد. برای ارائه موارد لیست منحصر به فرد، این مراحل را دنبال کنید:
مجموعهای از ویژگیها را برای مقادیر متن ایجاد کنید:
<resources> <attr name="widgetTitle" format="string" /> <attr name="widgetContent" format="string" /> </resources>برای تنظیم متن از این ویژگیها استفاده کنید:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="wrap_content"> <TextView android:id="@id/title" android:layout_width="match_parent" android:layout_height="wrap_content" android:text="?widgetTitle" /> <TextView android:id="@id/content" android:layout_width="match_parent" android:layout_height="wrap_content" android:text="?widgetContent" /> </LinearLayout>به تعداد مورد نیاز برای پیشنمایش، سبک ایجاد کنید. مقادیر را در هر سبک دوباره تعریف کنید:
<resources> <style name="Theme.Widget.ListItem"> <item name="widgetTitle"></item> <item name="widgetContent"></item> </style> <style name="Theme.Widget.ListItem.Preview1"> <item name="widgetTitle">Fake Title 1</item> <item name="widgetContent">Fake content 1</item> </style> <style name="Theme.Widget.ListItem.Preview2"> <item name="widgetTitle">Fake title 2</item> <item name="widgetContent">Fake content 2</item> </style> </resources>استایلها را روی آیتمهای تقلبی در طرح پیشنمایش اعمال کنید:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="wrap_content" ...> <include layout="@layout/widget_view" ... /> <include layout="@layout/widget_list_item" android:theme="@style/Theme.Widget.ListItem.Preview1" /> <include layout="@layout/widget_list_item" android:theme="@style/Theme.Widget.ListItem.Preview2" /> </LinearLayout>