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

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

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

برای کسب اطلاعات بیشتر، غنی کردن برنامه با به‌روزرسانی‌های زنده و ابزارک‌ها در 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 (سطح میانای برنامه‌سازی کاربردی ۳۰) یا پایین‌تر پیش‌نمایش‌های ابزارک شما را نشان دهند، یا به‌عنوان جایگزینی برای پیش‌نمایش‌های مقیاس‌پذیر، ویژگی 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>