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