Создайте хост виджетов

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

Эта страница фокусируется на обязанностях, связанных с реализацией пользовательского AppWidgetHost . Для конкретного примера реализации AppWidgetHost смотрите исходный код для домашнего экрана Android LauncherAppWidgetHost .

Ниже представлен обзор ключевых классов и концепций, используемых при реализации пользовательского AppWidgetHost :

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

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

  • App widget host view : представьте 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.componentName)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

Ява 

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

Хост должен проверить, нуждается ли виджет, который добавляет пользователь, в настройке. Для получения дополнительной информации см. Разрешить пользователям настраивать виджеты приложений .

Обязанности хозяина

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

Независимо от целевой версии Android все хосты имеют следующие обязанности:

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

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

  • Виджеты указывают ширину и высоту по умолчанию в метаданных AppWidgetProviderInfo . Эти значения определяются в ячейках — начиная с Android 12, если указаны targetCellWidth и targetCellHeight — или dps, если указаны только minWidth и minHeight . См. Атрибуты размера виджета .

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

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

Определите свой подход на основе целевой версии Android.

Андроид 12

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

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

Android 12 также вводит атрибуты maxResizeWidth и maxResizeHeight в dps. Мы рекомендуем, чтобы виджет, который использует хотя бы один из этих атрибутов, не превышал размер, указанный атрибутами.

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

  • См. справочную документацию Glance .