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

این صفحه شامل جزئیاتی برای بهبودهای اختیاری ویجت است که از 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>

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

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

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

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

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

<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 مراجعه کنید.

تجربه انتخابگر ویجت برنامه خود را بهبود بخشید

Android 12 به شما امکان می دهد با افزودن پیش نمایش ویجت پویا و توضیحات ویجت، تجربه انتخابگر ویجت را برای برنامه خود بهبود بخشید.

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

با شروع در اندروید 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>

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

• تنظیم android:text="@string/my_widget_item_fake_1" برای عناصر TextView .

• تنظیم یک تصویر یا نماد پیش‌فرض یا مکان‌نما، مانند android:src="@drawable/my_widget_icon" ، برای اجزای ImageView .

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

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

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

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

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

توضیحاتی برای ویجت خود اضافه کنید

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

با استفاده از ویژگی 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);