افزودن پیش‌نمایش به انتخابگر ابزاره

برای بهبود تجربه انتخابگر ابزاره برنامه‌تان، پیش‌نمایش ابزاره تولیدشده‌ای در دستگاه‌های Android 15 و نسخه‌های جدیدتر، پیش‌نمایش ابزاره مقیاس‌بندی‌شده‌ای (با مشخص کردن previewLayout) برای دستگاه‌های Android 12 تا Android 14، و previewImage برای نسخه‌های قدیمی‌تر ارائه دهید.

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

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

افزودن پیش‌نمایش‌های تولیدشده

برای نمایش «پیش‌نمایش‌های ابزاره تولیدشده» در دستگاه‌های دارای Android 15 یا جدیدتر، ابتدا مقدار compileSdk را در فایل واحد build.gradle روی ۳۵ یا جدیدتر تنظیم کنید تا بتوانید RemoteViews را به انتخابگر ابزاره ارائه دهید.

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

هیچ فراخوانی برگشتی از سیستم برای ارائه پیش‌نمایش وجود ندارد، بنابراین برنامه شما باید تصمیم بگیرد که چه زمانی 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)
)
AppWidgetSnippets.kt

افزودن پیش‌نمایش‌های ابزاره مقیاس‌پذیر

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

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

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

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

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

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

برای اینکه به انتخاب‌کننده‌های ابزارک در Android 11 (سطح میانای برنامه‌سازی کاربردی 30) یا پایین‌تر اجازه دهید پیش‌نمایش‌های ابزارکتان را نشان دهند، یا به‌عنوان جایگزین برای پیش‌نمایش‌های مقیاس‌پذیر، مشخصه previewImage را مشخص کنید.

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

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

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

شکل ۱: پیش‌نمایش ابزاره‌ای که هیچ موردی را در فهرست نمایش نمی‌دهد.

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

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

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

• چیدمان واقعی ابزاره.
• نمای مجموعه جای‌بان با موارد جعلی. برای مثال، می‌توانید با ارائه جای‌بان 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>

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

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>