این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

ویجت خود را تقویت کنید

این صفحه شامل جزئیاتی برای بهبودهای اختیاری ویجت است که از Android 12 در دسترس هستند (سطح API 31). این ویژگی ها اختیاری هستند، اما برای پیاده سازی و بهبود تجربه ویجت کاربران شما ساده هستند.

از رنگ های پویا استفاده کنید

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

دو راه برای دستیابی به رنگ های پویا وجود دارد:

از تم پیش‌فرض سیستم ( @android:style/Theme.DeviceDefault.DayNight ) در طرح‌بندی اصلی استفاده کنید.
از طرح زمینه Material 3 ( Theme.Material3.DynamicColors.DayNight ) از کتابخانه Material Components برای Android استفاده کنید که در Material Components برای Android نسخه 1.6.0 موجود است.

هنگامی که موضوع در چیدمان ریشه تنظیم شد، می توانید از ویژگی های رنگ رایج در ریشه یا هر یک از فرزندان آن برای انتخاب رنگ های پویا استفاده کنید.

چند نمونه از ویژگی های رنگی که می توانید استفاده کنید به شرح زیر است:

?attr/primary
?attr/primaryContainer
?attr/onPrimary
?attr/onPrimaryContainer

در مثال زیر با استفاده از تم Material 3، رنگ تم دستگاه "بنفش" است. رنگ تاکیدی و پس‌زمینه ویجت برای حالت‌های روشن و تاریک مطابقت دارد، همانطور که در شکل‌های 1 و 2 نشان داده شده است.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="?attr/colorPrimaryContainer"
  android:theme="@style/Theme.Material3.DynamicColors.DayNight">

  <ImageView
    ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />

    <!-- Other widget content. -->

</LinearLayout>

ویجت در تم حالت روشن — **شکل 1.** ویجت در موضوع روشن.

ویجت ها در تم حالت تاریک — **شکل 2.** ویجت در تم تیره.

سازگاری با عقب برای رنگ های پویا

رنگ‌های پویا فقط در دستگاه‌های دارای اندروید ۱۲ یا بالاتر در دسترس هستند. برای ارائه یک طرح زمینه سفارشی برای نسخه‌های پایین‌تر، با استفاده از ویژگی‌های تم پیش‌فرض، یک تم پیش‌فرض با رنگ‌های سفارشی خود و یک واجد شرایط جدید ( values-v31 ) ایجاد کنید.

در اینجا یک مثال با استفاده از موضوع Material 3 آورده شده است:

`/values/styles.xml`

<resources>
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    <!-- Override default colorBackground attribute with custom color. -->
    <item name="android:colorBackground">@color/my_background_color</item>

    <!-- Add other colors/attributes. -->

  </style>
</resources>

`/values-v31/styles.xml`

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

`/layout/my_widget_layout.xml`

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

پشتیبانی صوتی را فعال کنید

App Actions به Google Assistant اجازه می‌دهد ویجت‌ها را در پاسخ به دستورات صوتی کاربر نشان دهد. با پیکربندی ویجت خود برای پاسخ به مقاصد داخلی (BII) ، برنامه شما می‌تواند به طور فعال ویجت‌ها را روی سطوح دستیار مانند Android و Android Auto نمایش دهد. کاربران این گزینه را دارند که ویجت‌های نمایش داده شده توسط Assistant را به لانچر خود پین کنند ، که این امر باعث تشویق در تعامل در آینده می‌شود.

برای مثال، می‌توانید ویجت خلاصه تمرین را برای برنامه تمرین خود پیکربندی کنید تا دستورات صوتی کاربر را که GET_EXERCISE_OBSERVATION BII را راه‌اندازی می‌کنند، انجام دهد. وقتی کاربران این BII را فعال می‌کنند، «دستیار» با درخواست‌هایی مانند «Hey Google، چند مایل در این هفته در ExampleApp دویدم؟» به طور فعال ویجت شما را نمایش می‌دهد؟

ده‌ها BII وجود دارد که چندین دسته از تعاملات کاربر را پوشش می‌دهد و تقریباً به هر برنامه اندرویدی اجازه می‌دهد ویجت‌های خود را برای صدا ارتقا دهد. برای شروع، به ادغام اقدامات برنامه با ویجت های Android مراجعه کنید.

اندروید 12 به شما امکان می دهد پیش نمایش ویجت های مقیاس شده و توضیحات ویجت را اضافه کنید. Android 15 به شما امکان می‌دهد با پیش‌نمایش‌های ویجت تولید شده، تجربه انتخابگر ویجت را برای برنامه خود بهبود بخشید.

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

برنامه‌ها باید مقدار compileSdk را روی 35 یا بالاتر در فایل build.gradle ماژول تنظیم کنند تا بتوانند RemoteViews به انتخابگر ویجت در دستگاه‌های Android 15 یا بالاتر ارائه کنند. این بدان معناست که برنامه‌ها می‌توانند محتوای موجود در انتخابگر را به‌روزرسانی کنند تا نمایانگر آنچه کاربر می‌بیند بیشتر باشد.

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

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

Glance.compose یک ترکیب را اجرا می‌کند، بنابراین هیچ توابع تعلیق، جریان یا فراخوانی همگام‌سازی مشابهی در بدنه ترکیب‌بندی شما استفاده نمی‌شود. در عوض، باید از داده های ثابت استفاده کنید.

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

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    ExampleAppWidget().compose(
        context = appContext
    ),
)
AppWidgetSnippets.kt

پیش نمایش به روز شده را بدون 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 اولویت دارد.

روش های پیشنهادی برای ساخت پیش نمایش های دقیق

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

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

تصویری که پیش نمایش ویجت را نشان می دهد — **شکل 3.** یک پیش نمایش ویجت که به طور پیش فرض در یک ناحیه 3x3 ظاهر می شود اما به دلیل طرح XML می تواند در یک ناحیه 3x1 قرار گیرد.

برای نمایش یک پیش‌نمایش دقیق، می‌توانید با انجام مراحل زیر مستقیماً طرح‌بندی واقعی ویجت را با مقادیر پیش‌فرض ارائه کنید:

تنظیم android:text="@string/my_widget_item_fake_1" برای عناصر TextView .
توجه: مقادیر تنظیم شده با استفاده از برچسب tools ، مانند tools:text="@string/my_wdiget_item_fake_1" ، در پیش نمایش نشان داده نمی شوند.
تنظیم یک تصویر یا نماد پیش‌فرض یا مکان‌نما، مانند android:src="@drawable/my_widget_icon" ، برای اجزای ImageView .

بدون مقادیر پیش‌فرض، پیش‌نمایش ممکن است مقادیر نادرست یا خالی را نشان دهد. یکی از مزایای مهم این رویکرد این است که می توانید محتوای پیش نمایش محلی را ارائه دهید.

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

سازگاری به عقب با پیش نمایش ویجت های مقیاس پذیر

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

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

هنگامی که ویجت ها در انتخابگر ویجت نمایش داده می شوند، باید یک نام منحصر به فرد داشته باشند.

نام ابزارک ها از ویژگی label عنصر receiver ویجت در فایل AndroidManifest.xml بارگیری می شود.

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

با شروع اندروید 12، توضیحاتی را برای انتخابگر ویجت ارائه دهید تا برای ویجت شما نمایش داده شود.

تصویری که انتخابگر ویجت را نشان می دهد که ویجت و توضیحات آن را نشان می دهد — **شکل 4.** نمونه انتخابگر ویجت که ویجت و توضیحات آن را نشان می دهد.

با استفاده از ویژگی description <appwidget-provider> عنصر:

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

می‌توانید از ویژگی descriptionRes در نسخه‌های قبلی اندروید استفاده کنید، اما توسط انتخابگر ویجت نادیده گرفته می‌شود.

انتقال نرم‌تر را فعال کنید

با شروع اندروید 12، زمانی که کاربر برنامه شما را از ویجت راه اندازی می کند، لانچرها انتقال نرم تری را ارائه می دهند.

برای فعال کردن این انتقال بهبودیافته، از @android:id/background یا android.R.id.background برای شناسایی عنصر پس‌زمینه خود استفاده کنید:

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

برنامه شما می‌تواند از @android:id/background در نسخه‌های قبلی اندروید بدون شکستگی استفاده کند، اما نادیده گرفته می‌شود.

از اصلاح زمان اجرا RemoteViews استفاده کنید

با شروع اندروید 12، می‌توانید از چندین روش RemoteViews استفاده کنید که امکان اصلاح زمان اجرا ویژگی‌های RemoteViews را فراهم می‌کند. برای لیست کامل روش های اضافه شده به مرجع RemoteViews API مراجعه کنید.

مثال کد زیر نحوه استفاده از تعدادی از این روش ها را نشان می دهد.

کاتلین

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList())

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)

جاوا

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList());

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);