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

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

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

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

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

برای نمایش پیش‌نمایش‌های ویجت تولید شده در دستگاه Android 15 یا بالاتر، ابتدا مقدار compileSdk را روی 35 یا بالاتر در فایل 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 در فایل اطلاعات ارائه‌دهنده ابزارک برنامه تعریف می‌شود.

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

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

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

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

می توانید بدون نگاه از RemoteViews استفاده کنید. مثال زیر یک منبع طرح بندی ویجت XML را بارگیری می کند و آن را به عنوان پیش نمایش تنظیم می کند. تنظیم ساخت compileSdk 35 یا بالاتر برای setWidgetPreview لازم است تا به عنوان یک روش در این قطعه نمایش داده شود.

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

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

با شروع در اندروید 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 (سطح API 30) یا پایین‌تر، پیش‌نمایش‌های ویجت شما را نشان دهند، یا به‌عنوان جایگزینی برای پیش‌نمایش‌های تولید شده، ویژگی previewImage را مشخص کنید.

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

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

شکل 1: یک پیش نمایش ویجت که هیچ مورد لیستی را نمایش نمی دهد.

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

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

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

  • طرح ویجت واقعی
  • نمای مجموعه جایگیر با موارد جعلی. برای مثال، می‌توانید با ارائه یک حفره‌دار 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>
قبلی
با Glance یک ویجت برنامه ایجاد کنید
بعدی
با Glance خطاها را مدیریت کنید