پیشنمایشهای ویجت تولید شده به شما امکان میدهند پیشنمایشهای پویا و شخصیسازیشدهای برای ویجتهای خود ایجاد کنید که دقیقاً نحوه نمایش آنها در صفحه اصلی کاربر را منعکس میکنند. این پیشنمایشها از طریق یک API ارائه میشوند، به این معنی که برنامه شما پیشنمایش را در هر نقطه از چرخه عمر خود و بدون دریافت درخواست صریح از میزبان ویجت ارائه میدهد.
این راهنما نحوهی ارائهی پیشنمایش برای ویجتهای مبتنی بر Glance را پوشش میدهد. اگر ویجت شما با RemoteViews پیادهسازی شده است، به بخش افزودن پیشنمایشها به انتخابگر ویجت خود مراجعه کنید.
برای بهبود تجربه انتخاب ویجت برنامه خود برای ویجتهای Glance، با استفاده از GlanceAppWidget.providePreview در دستگاههای اندروید ۱۵ و بالاتر، یک پیشنمایش ویجت تولید شده ارائه دهید و برای نسخههای پایینتر، یک previewImage مشخص کنید و در اندروید ۱۵+ در صورت عدم وجود پیشنمایش تولید شده، از آن به عنوان جایگزین استفاده کنید.
برای اطلاعات بیشتر، به بخش «غنیسازی برنامه با بهروزرسانیهای زنده و ویجتها در یوتیوب» مراجعه کنید.
برنامه خود را برای پیشنمایشهای ویجت تولید شده تنظیم کنید
برای نمایش پیشنمایشهای ویجت تولید شده در دستگاه اندروید ۱۵ یا بالاتر، ابتدا مقدار compileSdk را در فایل build.gradle ماژول روی ۳۵ یا بالاتر تنظیم کنید تا پیشنمایشهای تولید شده در انتخابگر ویجت فعال شوند.
سپس برنامهها میتوانند setWidgetPreview در GlanceAppWidgetManager استفاده کنند. برای جلوگیری از سوءاستفاده و کاهش نگرانیهای مربوط به سلامت سیستم، setWidgetPreview یک API با نرخ محدود است. محدودیت پیشفرض تقریباً دو فراخوانی در ساعت است.
پیشنمایش بهروزرسانیشده را با Jetpack Glance ایجاد کنید
برای ویجتهای ساخته شده با Jetpack Glance، مراحل زیر را انجام دهید:
تابع
GlanceAppWidget.providePreviewرا برای ارائه محتوای قابل ترکیب برای پیشنمایش، بازنویسی کنید. همانطور که درprovideGlanceانجام میدهید، دادههای برنامه خود را بارگذاری کرده و آن را به محتوای قابل ترکیب ویجت منتقل کنید تا پیشنمایش، دادههای دقیقی را نشان دهد. برخلافprovideGlance، این یک ترکیب واحد بدون هیچ ترکیببندی مجدد یا افکتی است.برای تولید و انتشار پیشنمایش،
GlanceAppWidgetManager.setWidgetPreviewsرا فراخوانی کنید.
هیچ فراخوانی از سیستم برای ارائه پیشنمایشها وجود ندارد، بنابراین برنامه شما باید تصمیم بگیرد که چه زمانی setWidgetPreviews فراخوانی کند. استراتژی بهروزرسانی به مورد استفاده ویجت شما بستگی دارد:
- اگر ویجت اطلاعات ثابتی دارد یا یک اقدام سریع است، پیشنمایش را هنگام اولین اجرای برنامه تنظیم کنید.
- میتوانید پیشنمایش را زمانی تنظیم کنید که برنامه شما دادهها را دریافت کرده باشد؛ برای مثال، پس از ورود کاربر یا راهاندازی اولیه.
- میتوانید یک وظیفه دورهای تنظیم کنید تا پیشنمایشها را با ریتمی مشخص بهروزرسانی کند.
عیبیابی پیشنمایشهای ایجاد شده
یک مشکل رایج این است که پس از ایجاد پیشنمایش، ممکن است تصاویر، آیکونها یا سایر ترکیبات، نسبت به اندازه افت ویجت، از تصویر پیشنمایش حذف شوند. این اندازه افت توسط targetCellWidth و targetCellHeight در صورت مشخص شدن، یا توسط minWidth و minHeight در فایل اطلاعات ارائه دهنده ویجت برنامه تعریف میشود.
این اتفاق به این دلیل رخ میدهد که اندروید، به طور پیشفرض، فقط کامپوننتهایی را که در حداقل اندازه ویجت قابل مشاهده هستند، رندر میکند. به عبارت دیگر، اندروید به طور پیشفرض previewSizeMode را روی SizeMode.Single تنظیم میکند. android:minHeight و android:minWidth در XML مربوط به ارائه دهنده ویجت برنامه برای تعیین اینکه کدام کامپوننتها را ترسیم کند، استفاده میکند.
برای رفع این مشکل، previewSizeMode در GlanceAppWidget خود لغو کنید و آن را روی SizeMode.Responsive تنظیم کنید و مجموعهای از مقادیر DpSize را ارائه دهید. این به اندروید میگوید که تمام اندازههای طرحبندی مورد نیاز برای رندر برای پیشنمایش چیست، که تضمین میکند همه عناصر به درستی نمایش داده شوند.
برای فاکتورهای فرم خاص بهینه سازی کنید. یک یا دو اندازه را از حداقل شروع کنید و از نقاط شکست ویجت خود پیروی کنید. حداقل یک previewImage برای پشتیبانی از نسخههای پایینتر اندروید مشخص کنید. میتوانید حداقل مقادیر DP مناسب برای اندازههای مختلف شبکه را در راهنمای طراحی ویجت بیابید.
پشتیبانی از نسخههای پایینتر اندروید
برای نمایش پیشنمایش ویجتها در دستگاههایی که اندروید ۱۴ و پایینتر دارند، یا زمانی که پیشنمایش ایجاد شده در اندروید ۱۵ و بالاتر در دسترس نیست، ویژگی previewImage را مشخص کنید.
اگر ظاهر ویجت را تغییر میدهید، تصویر پیشنمایش را بهروزرسانی کنید.