Улучшите свой виджет

На этой странице представлена ​​информация о дополнительных улучшениях виджетов, доступных начиная с Android 12 (уровень API 31). Эти функции не являются обязательными, но их легко реализовать и улучшить работу с виджетами для ваших пользователей.

Используйте динамические цвета

Начиная с Android 12, виджет может использовать цвета темы устройства для кнопок, фона и других компонентов. Это обеспечивает более плавные переходы и согласованность между различными виджетами.

Есть два способа добиться динамических цветов:

• Используйте тему системы по умолчанию ( @android:style/Theme.DeviceDefault.DayNight ) в корневом макете.

• Используйте тему Material 3 ( Theme.Material3.DynamicColors.DayNight ) из библиотеки Material Components для Android , доступной начиная с Material Components для Android v1.6.0 .

После того как тема установлена ​​в корневом макете, вы можете использовать общие атрибуты цвета в корне или любом из его дочерних элементов, чтобы подобрать динамические цвета.

Ниже приведены некоторые примеры атрибутов цвета, которые вы можете использовать:

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

В следующем примере с использованием темы «Материал 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. Виджет в темной теме.

Совет: Мы рекомендуем использовать тему Material 3 , чтобы следовать рекомендациям Material Design для обеспечения согласованности между устройствами и обратной совместимости.

Обратная совместимость для динамических цветов

Динамические цвета доступны только на устройствах под управлением Android 12 или более поздней версии. Чтобы предоставить собственную тему для более ранних версий, создайте тему по умолчанию со своими собственными цветами и новым квалификатором ( 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>

Примечание. Подробное руководство по работе с различными стилями, цветами, атрибутами и темами см. в разделе «Стили и темы».

Включить голосовую поддержку

Действия приложения позволяют Google Assistant отображать виджеты в ответ на соответствующие голосовые команды пользователя. Настроив виджет так, чтобы он реагировал на встроенные намерения (BII) , ваше приложение может активно отображать виджеты на поверхностях Ассистента, таких как Android и Android Auto. Пользователи имеют возможность закреплять виджеты , отображаемые Ассистентом, на своей панели запуска, поощряя дальнейшее взаимодействие.

Например, вы можете настроить виджет сводки тренировок для своего приложения для тренировок так, чтобы он выполнял голосовые команды пользователя, которые запускают GET_EXERCISE_OBSERVATION BII. Ассистент заранее отображает ваш виджет, когда пользователи запускают этот BII, отправляя запросы типа «Эй, Google, сколько миль я пробежал на этой неделе в приложении exampleApp?»

Существуют десятки BII, охватывающих несколько категорий взаимодействия с пользователем, что позволяет практически любому Android-приложению улучшить свои виджеты для голосовой связи. Чтобы начать, см. раздел Интеграция действий приложения с виджетами Android .

Улучшите возможности выбора виджетов вашего приложения.

Android 12 позволяет улучшить возможности выбора виджетов для вашего приложения, добавив динамические предварительный просмотр и описания виджетов.

Добавьте масштабируемые предварительные просмотры виджетов в средство выбора виджетов.

Начиная с Android 12, предварительный просмотр виджета, отображаемый в средстве выбора виджетов, является масштабируемым. Вы предоставляете его как макет XML с размером виджета по умолчанию. Раньше предварительный просмотр виджета представлял собой статический ресурс, который можно было рисовать, что в некоторых случаях приводило к тому, что предварительный просмотр неточно отражал внешний вид виджетов при их добавлении на главный экран.

Чтобы реализовать масштабируемый предварительный просмотр виджетов, используйте previewLayout элемента appwidget-provider чтобы вместо этого предоставить макет XML:

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

Мы рекомендуем использовать тот же макет, что и сам виджет, с реалистичными значениями по умолчанию или тестовыми значениями. Большинство приложений используют одни и те же previewLayout и initialLayout . Рекомендации по созданию точных макетов предварительного просмотра см. в следующем разделе на этой странице.

Мы рекомендуем указать оба атрибута previewLayout и previewImage , чтобы ваше приложение могло вернуться к использованию previewImage , если устройство пользователя не поддерживает previewLayout . Атрибут previewLayout имеет приоритет над атрибутом previewImage .

Рекомендуемые подходы для создания точных превью

Чтобы реализовать масштабируемый предварительный просмотр виджетов, используйте previewLayout элемента appwidget-provider чтобы предоставить макет XML:

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

Рисунок 3. Предварительный просмотр виджета, который по умолчанию отображается в области 3x3, но может поместиться в область 3x1 из-за его XML-макета.

Чтобы отобразить точный предварительный просмотр, вы можете напрямую предоставить фактический макет виджета со значениями по умолчанию, выполнив следующие шаги:

• Настройка 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 .

Если вы измените внешний вид виджета, обновите изображение предварительного просмотра.

Добавьте описание для вашего виджета

Начиная с Android 12, предоставьте описание средства выбора виджета, которое будет отображаться для вашего виджета.

Рисунок 4. Пример средства выбора виджета, показывающий виджет и его описание.

Предоставьте описание виджета, используя атрибут description тега <appwidget-provider> элемент:

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

Примечание: будьте краткими. Ограничения на количество символов нет, но представление и доступное пространство для описания могут различаться в зависимости от устройства.

Вы можете использовать descriptionRes в предыдущих версиях Android, но он игнорируется средством выбора виджета.

Включить более плавные переходы

Начиная с Android 12, средства запуска обеспечивают более плавный переход, когда пользователь запускает ваше приложение из виджета.

Чтобы включить этот улучшенный переход, используйте @android:id/background или android.R.id.background для идентификации элемента фона:

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

Предупреждение: избегайте использования трансляционных батутов . Начиная с Android 12, приложение по-прежнему может запускать действие от широковещательного приемника или службы, если оно инициируется с помощью PendingIntent щелчка виджета. Однако новая анимация приложений не используется для приложений, запускаемых с широковещательного приемника или службы, что приводит к ухудшению пользовательского опыта.

Ваше приложение может использовать @android:id/background в предыдущих версиях Android без каких-либо нарушений, но это игнорируется.

Используйте модификацию RemoteViews во время выполнения.

Начиная с Android 12, вы можете воспользоваться несколькими методами RemoteViews , которые позволяют изменять атрибуты RemoteViews во время выполнения. Полный список добавленных методов см. в справочнике по API RemoteViews .

В следующем примере кода показано, как использовать некоторые из этих методов.

Котлин

// 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);