پیش نمایش های ایجاد شده را به انتخابگر ویجت خود اضافه کنید

پیش‌نمایش‌های ویجت تولید شده به شما امکان می‌دهند پیش‌نمایش‌های پویا و شخصی‌سازی‌شده‌ای برای ویجت‌های خود ایجاد کنید که دقیقاً نحوه نمایش آنها در صفحه اصلی کاربر را منعکس می‌کنند. این پیش‌نمایش‌ها از طریق یک API ارائه می‌شوند، به این معنی که برنامه شما پیش‌نمایش را در هر نقطه از چرخه عمر خود و بدون دریافت درخواست صریح از میزبان ویجت ارائه می‌دهد.

برای بهبود تجربه انتخابگر ویجت برنامه خود، یک پیش‌نمایش ویجت تولید شده در دستگاه‌های اندروید ۱۵ و بالاتر، یک پیش‌نمایش ویجت مقیاس‌پذیر (با مشخص کردن previewLayout ) برای دستگاه‌های اندروید ۱۲ تا اندروید ۱۴ و یک previewImage برای نسخه‌های قبلی ارائه دهید.

برای اطلاعات بیشتر، به بخش «غنی‌سازی برنامه با به‌روزرسانی‌های زنده و ویجت‌ها در یوتیوب» مراجعه کنید.

برنامه خود را برای پیش‌نمایش‌های ویجت تولید شده تنظیم کنید

برای نمایش پیش‌نمایش‌های ویجت تولید شده در دستگاه اندروید ۱۵ یا بالاتر، ابتدا مقدار compileSdk را در فایل build.gradle ماژول روی ۳۵ یا بالاتر تنظیم کنید تا بتوانید RemoteViews به انتخابگر ویجت ارائه دهید.

سپس برنامه‌ها می‌توانند از setWidgetPreview در GlanceAppWidgetManager یا AppWidgetManager استفاده کنند. برای جلوگیری از سوءاستفاده و کاهش نگرانی‌های مربوط به سلامت سیستم، setWidgetPreview یک API با نرخ محدود است. محدودیت پیش‌فرض تقریباً دو فراخوانی در ساعت است.

پیش‌نمایش به‌روزرسانی‌شده را با Jetpack Glance ایجاد کنید

برای ویجت‌های ساخته شده با Jetpack Glance، مراحل زیر را انجام دهید:

1. تابع GlanceAppWidget.providePreview را برای ارائه محتوای قابل ترکیب برای پیش‌نمایش، بازنویسی کنید. همانطور که در provideGlance انجام می‌دهید، داده‌های برنامه خود را بارگذاری کرده و آن را به محتوای قابل ترکیب ویجت منتقل کنید تا مطمئن شوید پیش‌نمایش داده‌های دقیقی را نشان می‌دهد. برخلاف provideGlance ، این یک ترکیب واحد بدون هیچ ترکیب‌بندی مجدد یا افکتی است.

2. برای تولید و انتشار پیش‌نمایش، GlanceAppWidgetManager.setWidgetPreviews فراخوانی کنید.

هیچ فراخوانی از سیستم برای ارائه پیش‌نمایش‌ها وجود ندارد، بنابراین برنامه شما باید تصمیم بگیرد که چه زمانی setWidgetPreviews فراخوانی کند. استراتژی به‌روزرسانی به مورد استفاده ویجت شما بستگی دارد:

• اگر ویجت اطلاعات ثابتی دارد یا یک اقدام سریع است، پیش‌نمایش را هنگام اولین اجرای برنامه تنظیم کنید.
• می‌توانید پیش‌نمایش را زمانی تنظیم کنید که برنامه شما داده‌ها را دریافت کرده باشد؛ برای مثال، پس از ورود کاربر یا راه‌اندازی اولیه.
• می‌توانید یک وظیفه دوره‌ای تنظیم کنید تا پیش‌نمایش‌ها را با ریتمی مشخص به‌روزرسانی کند.

عیب‌یابی پیش‌نمایش‌های تولید شده

یک مشکل رایج این است که پس از ایجاد پیش‌نمایش، ممکن است تصاویر، آیکون‌ها یا سایر ترکیبات، نسبت به اندازه افت ویجت، از تصویر پیش‌نمایش حذف شوند. این اندازه افت توسط targetCellWidth و targetCellHeight در صورت مشخص شدن، یا توسط minWidth و minHeight در فایل اطلاعات ارائه دهنده ویجت برنامه تعریف می‌شود.

این اتفاق به این دلیل رخ می‌دهد که اندروید، به طور پیش‌فرض، فقط کامپوننت‌هایی را که در حداقل اندازه ویجت قابل مشاهده هستند، رندر می‌کند. به عبارت دیگر، اندروید به طور پیش‌فرض previewSizeMode روی SizeMode.Single تنظیم می‌کند. android:minHeight و android:minWidth در XML مربوط به ارائه دهنده ویجت برنامه برای تعیین اینکه کدام کامپوننت‌ها را ترسیم کند، استفاده می‌کند.

برای رفع این مشکل، previewSizeMode در GlanceAppWidget خود لغو کنید و آن را روی SizeMode.Responsive تنظیم کنید و مجموعه‌ای از مقادیر DpSize را ارائه دهید. این به اندروید می‌گوید که تمام اندازه‌های طرح‌بندی مورد نیاز برای رندر برای پیش‌نمایش چیست، که تضمین می‌کند همه عناصر به درستی نمایش داده شوند.

برای فاکتورهای فرم خاص بهینه سازی کنید. ۱ یا ۲ اندازه را از حداقل شروع کنید و نقاط شکست ویجت خود را دنبال کنید. حداقل یک تصویر را برای سازگاری با نسخه‌های قبلی مشخص کنید. می‌توانید حداقل مقادیر DP مناسب را برای اندازه‌های مختلف شبکه در راهنمای طراحی ویجت پیدا کنید.

پیش‌نمایش به‌روزرسانی‌شده را بدون Jetpack Glance ایجاد کنید

شما می‌توانید از RemoteViews بدون Glance استفاده کنید. مثال زیر یک منبع طرح‌بندی ویجت XML را بارگذاری کرده و آن را به عنوان پیش‌نمایش تنظیم می‌کند. برای نمایش setWidgetPreview به عنوان یک متد در این قطعه کد، تنظیم build کامپایل Sdk روی ۳۵ یا بالاتر لازم است.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    RemoteViews("com.example", R.layout.widget_preview)
)
AppWidgetSnippets.kt

پیش‌نمایش‌های ویجت مقیاس‌پذیر را به انتخابگر ویجت اضافه کنید

از اندروید ۱۲ به بعد، پیش‌نمایش ویجت نمایش داده شده در انتخابگر ویجت، مقیاس‌پذیر است. شما آن را به عنوان یک طرح‌بندی XML که روی اندازه پیش‌فرض ویجت تنظیم شده است، ارائه می‌دهید. پیش از این، پیش‌نمایش ویجت یک منبع قابل ترسیم استاتیک بود که در برخی موارد منجر به پیش‌نمایش‌هایی می‌شد که به طور نادرست نحوه نمایش ویجت‌ها را هنگام اضافه شدن به صفحه اصلی منعکس می‌کردند.

برای پیاده‌سازی پیش‌نمایش‌های ویجت مقیاس‌پذیر، از ویژگی previewLayout از عنصر appwidget-provider برای ارائه یک طرح‌بندی XML استفاده کنید:

<appwidget-provider
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

توصیه می‌کنیم از همان طرح‌بندی ویجت اصلی، با مقادیر پیش‌فرض یا آزمایشی واقع‌بینانه، استفاده کنید. اکثر برنامه‌ها از previewLayout و initialLayout یکسانی استفاده می‌کنند. برای راهنمایی در مورد ایجاد طرح‌بندی‌های پیش‌نمایش دقیق، به بخش زیر در این صفحه مراجعه کنید.

توصیه می‌کنیم هر دو ویژگی previewLayout و previewImage را مشخص کنید تا در صورت عدم پشتیبانی دستگاه کاربر previewLayout ، برنامه شما بتواند به استفاده از previewImage بازگردد. ویژگی previewLayout بر ویژگی previewImage اولویت دارد.

سازگاری با نسخه‌های قبلی با پیش‌نمایش ویجت‌ها

برای اینکه انتخابگرهای ویجت در اندروید ۱۱ (سطح API 30) یا پایین‌تر، پیش‌نمایش‌هایی از ویجت شما را نمایش دهند، یا به عنوان جایگزینی برای پیش‌نمایش‌های تولید شده، ویژگی previewImage مشخص کنید.

اگر ظاهر ویجت را تغییر می‌دهید، تصویر پیش‌نمایش را به‌روزرسانی کنید.

پیش‌نمایش‌های دقیقی بسازید که شامل موارد پویا باشند

این بخش رویکرد پیشنهادی برای نمایش چندین آیتم در پیش‌نمایش ویجت برای ویجتی با نمای مجموعه - یعنی ویجتی که از ListView ، GridView یا StackView استفاده می‌کند - را توضیح می‌دهد. این موضوع در مورد پیش‌نمایش‌های ویجت تولید شده صدق نمی‌کند.

اگر ویجت شما از یکی از این نماها استفاده می‌کند، ایجاد یک پیش‌نمایش مقیاس‌پذیر با ارائه مستقیم طرح‌بندی ویجت واقعی، وقتی پیش‌نمایش ویجت هیچ آیتمی را نمایش نمی‌دهد، تجربه را خراب می‌کند. این اتفاق می‌افتد زیرا داده‌های نمای مجموعه به صورت پویا در زمان اجرا تنظیم می‌شوند و شبیه به تصویر نشان داده شده در شکل ۱ هستند.

برای اینکه پیش‌نمایش ویجت‌ها با نماهای مجموعه به درستی در انتخابگر ویجت نمایش داده شود، توصیه می‌کنیم یک فایل طرح‌بندی جداگانه که فقط برای پیش‌نمایش در نظر گرفته شده است، نگه دارید. این فایل طرح‌بندی جداگانه باید شامل موارد زیر باشد:

• طرح‌بندی واقعی ویجت.
• یک 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_previe"
    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>

برای ارائه موارد لیست جعلی، می‌توانید طرح‌بندی را چندین بار وارد کنید، اما این باعث می‌شود که هر مورد لیست یکسان باشد. برای ارائه موارد لیست منحصر به فرد، این مراحل را دنبال کنید:

1. مجموعه‌ای از ویژگی‌ها را برای مقادیر متن ایجاد کنید:

   <resources>
       <attr name="widgetTitle" format="string" />
       <attr name="widgetContent" format="string" />
   </resources>
   

2. برای تنظیم متن از این ویژگی‌ها استفاده کنید:

   <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>
   

3. به تعداد مورد نیاز برای پیش‌نمایش، سبک ایجاد کنید. مقادیر را در هر سبک دوباره تعریف کنید:

   <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>
   

4. استایل‌ها را روی آیتم‌های تقلبی در طرح پیش‌نمایش اعمال کنید:

   <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>