Сгенерированные превью виджетов позволяют создавать динамические, персонализированные превью для ваших виджетов, которые точно отражают их внешний вид на главном экране пользователя. Они предоставляются через 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, выполните следующие действия:
Переопределите функцию
GlanceAppWidget.providePreview, чтобы предоставить компонуемое содержимое для предварительного просмотра. Как и в случае сprovideGlance, загрузите данные приложения и передайте их компонуемому содержимому виджета, чтобы гарантировать корректность отображения данных в предварительном просмотре. В отличие отprovideGlance, это единая композиция без перекомпоновки или эффектов.Вызовите
GlanceAppWidgetManager.setWidgetPreviewsдля создания и публикации предварительного просмотра.
Система не предоставляет функцию обратного вызова для предварительного просмотра, поэтому ваше приложение должно самостоятельно решить, когда вызывать setWidgetPreviews . Стратегия обновления зависит от варианта использования вашего виджета:
- Если виджет содержит статическую информацию или представляет собой быстрое действие, включите предварительный просмотр при первом запуске приложения.
- Вы можете включить предварительный просмотр, как только в вашем приложении появятся данные, например, после входа пользователя в систему или первоначальной настройки.
- Вы можете настроить периодическую задачу для обновления предпросмотров с выбранной частотой.
Устранение неполадок с созданными предварительными просмотрами
Распространенная проблема заключается в том, что после создания предварительного просмотра изображения, значки или другие компонуемые элементы могут отсутствовать в изображении предварительного просмотра относительно размера области перетаскивания виджета. Этот размер определяется параметрами targetCellWidth и targetCellHeight если они указаны, или параметрами minWidth и minHeight в файле информации поставщика виджета приложения .
Это происходит потому, что Android по умолчанию отображает только компонуемые элементы при минимальном размере виджета. Другими словами, Android по умолчанию устанавливает для previewSizeMode значение SizeMode.Single . Для определения компонуемых элементов, которые нужно отобразить, используются значения android:minHeight и android:minWidth в XML-файле поставщика виджета приложения .
Чтобы исправить это, переопределите previewSizeMode в GlanceAppWidget и установите для него значение SizeMode.Responsive , указав набор значений DpSize . Это сообщит Android все размеры макета, необходимые для отображения в режиме предварительного просмотра, что гарантирует корректное отображение всех элементов.
Оптимизируйте под конкретные форм-факторы. Предоставьте 1 или 2 размера, начиная с минимального и следуя контрольным точкам вашего виджета. Укажите как минимум одно изображение для обратной совместимости . Соответствующие минимальные значения DP для различных размеров сетки можно найти в руководстве по дизайну виджетов .
Создать обновленный предварительный просмотр без Jetpack Glance
Вы можете использовать RemoteViews без Glance. В следующем примере загружается XML-ресурс макета виджета и устанавливается в качестве предварительного просмотра. Для отображения метода setWidgetPreview в этом фрагменте требуется версия сборки compileSdk 35 или выше.
AppWidgetManager.getInstance(appContext).setWidgetPreview(
ComponentName(
appContext,
ExampleAppWidgetReceiver::class.java
),
AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
RemoteViews("com.example", R.layout.widget_preview)
)
Добавить масштабируемые предварительные просмотры виджетов в средство выбора виджетов
Начиная с 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 .
Обратная совместимость с предпросмотром виджетов
Чтобы разрешить средствам выбора виджетов на Android 11 (уровень API 30) или ниже показывать предварительные просмотры вашего виджета или в качестве резервного варианта для сгенерированных предварительных просмотров, укажите атрибут previewImage .
Если вы изменили внешний вид виджета, обновите изображение предварительного просмотра.
Создавайте точные предварительные просмотры, включающие динамические элементы
В этом разделе описывается рекомендуемый подход к отображению нескольких элементов в предварительном просмотре виджета для виджета с коллекционным представлением , то есть виджета, использующего ListView , GridView или StackView . Это не относится к сгенерированным предварительным просмотрам виджетов.
Если ваш виджет использует одно из этих представлений, создание масштабируемого предварительного просмотра путём непосредственного предоставления макета виджета ухудшает восприятие, когда в предварительном просмотре виджета не отображаются элементы. Это происходит, поскольку данные представления коллекции динамически задаются во время выполнения и выглядят примерно так, как показано на рисунке 1.
Для корректного отображения предпросмотров виджетов с коллекцией в окне выбора виджетов рекомендуем создать отдельный файл макета, предназначенный только для предпросмотра. Этот файл должен включать в себя следующее:
- Фактический макет виджета.
- Представление-заполнитель коллекции с поддельными элементами. Например, вы можете имитировать
ListView, предоставив плейсхолдерLinearLayoutс несколькими поддельными элементами списка.
Чтобы проиллюстрировать пример для 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>
Чтобы создать поддельные элементы списка, можно включить макет несколько раз, но это приведёт к тому, что все элементы списка будут идентичны. Чтобы создать уникальные элементы списка, выполните следующие действия:
Создайте набор атрибутов для текстовых значений:
<resources> <attr name="widgetTitle" format="string" /> <attr name="widgetContent" format="string" /> </resources>Используйте эти атрибуты для задания текста:
<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>Создайте необходимое количество стилей для предварительного просмотра. Переопределите значения в каждом стиле:
<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>Примените стили к поддельным элементам в макете предварительного просмотра:
<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>