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