Созданные предварительные просмотры виджетов позволяют создавать динамические, персонализированные предварительные просмотры ваших виджетов, которые точно отражают то, как они будут выглядеть на главном экране пользователя. Они предоставляются через API push-уведомлений, что означает, что ваше приложение предоставляет предварительный просмотр в любой момент своего жизненного цикла без получения явного запроса от хоста виджета.
В этом руководстве описано, как отображать предварительный просмотр для виджетов на основе Glance. Если ваш виджет реализован с использованием RemoteViews , см. раздел «Добавление предварительного просмотра в средство выбора виджетов» .
Чтобы улучшить работу виджета Glance в вашем приложении, предоставьте сгенерированный предварительный просмотр виджета с помощью GlanceAppWidget.providePreview на устройствах Android 15 и более поздних версий, а также укажите previewImage для более ранних версий и в качестве запасного варианта на Android 15+, если сгенерированный предварительный просмотр недоступен.
Для получения дополнительной информации см. раздел «Расширьте возможности своего приложения с помощью обновлений в реальном времени и виджетов на YouTube».
Настройте ваше приложение для предварительного просмотра сгенерированных виджетов.
Чтобы отображать сгенерированные предварительные просмотры виджетов на устройствах Android 15 или более поздних версий, сначала установите значение compileSdk равным 35 или более поздней версии в файле build.gradle модуля, чтобы иметь возможность предоставлять RemoteViews для выбора виджетов.
Затем приложения могут использовать setWidgetPreview в GlanceAppWidgetManager . Чтобы предотвратить злоупотребления и снизить риски для работоспособности системы, 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 все необходимые размеры макета для отображения предварительного просмотра, что гарантирует корректное отображение всех элементов.
Оптимизируйте виджет под конкретные форм-факторы. Укажите один или два размера, начиная с минимального и следуя контрольным точкам вашего виджета. Укажите как минимум одно previewImage для обратной совместимости . Соответствующие минимальные значения DP для разных размеров сетки можно найти в руководстве по проектированию виджетов .
Обратная совместимость с предварительным просмотром виджетов.
Чтобы на устройствах с версиями Android ниже 15 в средствах выбора виджетов отображался предварительный просмотр вашего виджета, или в качестве резервного варианта для сгенерированного предварительного просмотра на устройствах Android 15 и выше, укажите атрибут previewImage .
Если вы измените внешний вид виджета, обновите изображение предварительного просмотра.