Как создать хост виджета

На главный экран большинства устройств Android можно добавлять виджеты приложений (или просто виджеты) для быстрого доступа к контенту. Если вы создаете замену главного экрана или похожее приложение, то можете разрешить пользователям встраивать виджеты, реализовав AppWidgetHost. Большинству приложений это не требуется, но если вы создаете собственный хост, важно понимать, какие договорные обязательства он на себя принимает.

В этой статье рассматриваются обязанности, связанные с реализацией пользовательского AppWidgetHost. Пример реализации AppWidgetHost можно найти в исходном коде главного экрана Android LauncherAppWidgetHost.

Ниже приведены основные классы и концепции, которые используются при реализации собственного класса AppWidgetHost.

  • Хост виджетов приложений. AppWidgetHost обеспечивает взаимодействие с сервисом AppWidget для приложений, в интерфейс которых встроены виджеты. У каждого элемента AppWidgetHost должен быть уникальный идентификатор в пределах пакета хоста. Этот идентификатор сохраняется при любом использовании хоста. Обычно это значение, которое вы задаете в коде приложения.

  • Идентификатор виджета приложения. Каждому экземпляру виджета при привязке назначается уникальный идентификатор. Подробнее об этом рассказывается в разделе bindAppWidgetIdIfAllowed() и в разделе Связывание виджетов ниже. Хост получает уникальный идентификатор с помощью allocateAppWidgetId(). Этот идентификатор сохраняется в течение всего времени существования виджета, пока он не будет удален с хоста. Любое состояние, зависящее от хоста, например размер и местоположение виджета, должно сохраняться пакетом хостинга и связываться с идентификатором виджета приложения.

  • Представление хоста виджета приложения. AppWidgetHostView – это рамка, в которую помещается виджет, когда его нужно показать. Виджет связывается с AppWidgetHostView каждый раз, когда он разворачивается хостом.

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

  • Набор параметров. AppWidgetHost использует набор параметров, чтобы передавать AppWidgetProvider информацию о том, как показывается виджет, например список диапазонов размеров, и о том, где он находится – на заблокированном или главном экране. Эта информация позволяет AppWidgetProvider настраивать содержимое и внешний вид виджета в зависимости от того, как и где он отображается. Чтобы изменить пакет виджета, используйте updateAppWidgetOptions() и updateAppWidgetSize(). Оба метода активируют обратный вызов onAppWidgetOptionsChanged() для AppWidgetProvider.

Привязка виджетов

Когда пользователь добавляет виджет в хост, происходит процесс, называемый связыванием. Привязка – это связывание определенного идентификатора виджета приложения с конкретным хостом и определенным объектом AppWidgetProvider.

API привязки также позволяют хосту предоставлять собственный интерфейс для привязки. Чтобы использовать этот процесс, в манифесте хоста необходимо объявить разрешение BIND_APPWIDGET:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

Но это только первый шаг. При запуске пользователь должен явно предоставить приложению разрешение на добавление виджета на хост. Чтобы проверить, есть ли у приложения разрешение на добавление виджета, используйте метод bindAppWidgetIdIfAllowed(). Если bindAppWidgetIdIfAllowed() возвращает false, приложение должно показать диалоговое окно с запросом разрешения: "Разрешить" для текущего добавления виджета или "Разрешать всегда" для всех будущих добавлений.

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

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.provider)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

Хост должен проверить, требуется ли настройка виджета, который добавляет пользователь. Подробнее о том, как разрешить пользователям настраивать виджеты приложений…

Обязанности организатора

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

Все организаторы могут:

  • При добавлении виджета назначьте ему идентификатор, как описано выше. Когда виджет удаляется из хоста, вызовите deleteAppWidgetId(), чтобы освободить идентификатор виджета.

  • При добавлении виджета проверьте, нужно ли запускать действие по настройке. Обычно хосту необходимо запустить действие конфигурации виджета, если оно существует и не помечено как необязательное путем указания флагов configuration_optional и reconfigurable. Подробную информацию можно найти в разделе Обновление виджета из действия конфигурации. Это необходимо для работы многих виджетов.

  • Ширина и высота виджета по умолчанию указываются в метаданных AppWidgetProviderInfo. Эти значения задаются в ячейках (начиная с Android 12, если указаны targetCellWidth и targetCellHeight) или в dp (если указаны только minWidth и minHeight). Подробнее об атрибутах размера виджета…

    Убедитесь, что размер виджета не меньше указанного. Например, многие хосты выравнивают значки и виджеты по сетке. В этом случае хост по умолчанию добавляет виджет, используя минимальное количество ячеек, которое удовлетворяет ограничениям minWidth и minHeight.

Советы по подходу

Помимо требований, перечисленных в предыдущем разделе, учитывайте следующие рекомендации:

Набор параметров может содержать List<SizeF> со списком возможных размеров в dp, которые может принимать экземпляр виджета. Количество размеров зависит от реализации хоста. Обычно хосты предоставляют два размера для телефонов (книжная и альбомная ориентация) и четыре размера для складных устройств.

AppWidgetProvider может передавать в RemoteViews не более MAX_INIT_VIEW_COUNT (16) разных значений RemoteViews. Поскольку объекты AppWidgetProvider сопоставляют объект RemoteViews с каждым размером в List<SizeF>, не указывайте более MAX_INIT_VIEW_COUNT размеров.

Если в виджете указаны атрибуты maxResizeWidth и maxResizeHeight в dp, рекомендуем, чтобы виджет, использующий хотя бы один из этих атрибутов, не превышал размер, указанный в атрибутах.

Дополнительные ресурсы

  • Ознакомьтесь со справочной документацией по Glance.