Сгенерированные предпросмотры позволяют создавать динамические персонализированные предпросмотры виджетов, которые точно отражают, как они будут выглядеть на главном экране пользователя. Они предоставляются через push API, то есть ваше приложение предоставляет предварительный просмотр в любой момент своего жизненного цикла без получения явного запроса от хоста виджета.
В этом руководстве рассказывается, как создавать предварительные версии виджетов на основе Glance. Если виджет реализован с помощью RemoteViews, прочитайте статью Как добавить предпросмотр в средство выбора виджетов.
Чтобы улучшить работу виджетов Glance в меню выбора виджетов, предоставьте сгенерированный предпросмотр виджета с помощью GlanceAppWidget.providePreview на устройствах с Android 15 и более поздними версиями и укажите previewImage для более ранних версий, а также в качестве резервного варианта на Android 15+, если сгенерированный предпросмотр недоступен.
Дополнительную информацию можно найти в видео Добавьте в приложение виджеты и обновления в реальном времени на YouTube.
Как настроить приложение для предварительного просмотра сгенерированных виджетов
Чтобы показывать сгенерированные предпросмотры виджетов на устройствах с Android 15 или более поздней версии, сначала задайте для compileSdk значение 35 или выше в файле модуля build.gradle. Это позволит включить сгенерированные предпросмотры в окне выбора виджетов.
После этого приложения смогут использовать setWidgetPreview в GlanceAppWidgetManager. Чтобы предотвратить злоупотребления и снизить нагрузку на систему, в setWidgetPreview ограничена частота запросов. По умолчанию лимит составляет примерно два вызова в час.
Как создать обновленный предпросмотр с помощью Jetpack Glance
Для виджетов, созданных с помощью Jetpack Glance, выполните следующие действия:
Переопределите функцию
GlanceAppWidget.providePreview, чтобы предоставить composable-контент для предварительного просмотра. Как и вprovideGlance, загрузите данные приложения и передайте их в composable-функцию контента виджета, чтобы в предварительной версии показывались точные данные. В отличие отprovideGlance, это одна композиция без рекомпозиции и эффектов.Вызовите
GlanceAppWidgetManager.setWidgetPreviews, чтобы создать и опубликовать предварительную версию.
Система не предоставляет обратный вызов для предварительного просмотра, поэтому ваше приложение должно самостоятельно решать, когда вызывать setWidgetPreviews. Стратегия обновления зависит от варианта использования вашего виджета:
- Если виджет содержит статическую информацию или выполняет быстрое действие, настройте предварительный просмотр при первом запуске приложения.
- Вы можете настроить предварительный просмотр, как только в приложении появятся данные, например после входа пользователя или первоначальной настройки.
- Вы можете настроить периодическую задачу, чтобы обновлять предварительные версии с выбранной частотой.
Устранение неполадок с созданными предварительными версиями
Распространенная проблема заключается в том, что после создания предварительного просмотра изображения, значки или другие составные элементы могут отсутствовать на изображении предварительного просмотра по сравнению с размером виджета. Размер виджета определяется атрибутами targetCellWidth и targetCellHeight (если они заданы) или minWidth и minHeight в файле с информацией о поставщике виджета.
Это происходит потому, что Android по умолчанию отображает только те composable-функции, которые видны при минимальном размере виджета. Другими словами, Android по умолчанию устанавливает для previewSizeMode значение SizeMode.Single. Для определения того, какие composable-функции нужно отрисовать, используются атрибуты android:minHeight и android:minWidth в XML-файле с информацией о поставщике виджетов приложения.
Чтобы исправить это, переопределите previewSizeMode в GlanceAppWidget и задайте значение SizeMode.Responsive, указав набор значений DpSize. Это сообщает Android все размеры макета, которые необходимо отобразить для предварительного просмотра, что обеспечивает правильное отображение всех элементов.
Оптимизируйте рекламу для определенных типов устройств. Укажите один или два размера, начиная с минимального и следуя контрольным точкам виджета. Укажите хотя бы один previewImage, чтобы поддерживать более ранние версии Android. Подходящие минимальные значения DP для разных размеров сетки можно найти в руководстве по дизайну виджетов.
Поддержка более ранних версий Android
Чтобы показывать предварительные версии виджетов на устройствах с Android 14 и более ранними версиями или когда сгенерированная предварительная версия недоступна на Android 15 и более поздних версиях, укажите атрибут previewImage.
Если вы измените внешний вид виджета, обновите изображение для предварительного просмотра.