Разрешить пользователям настраивать виджеты приложений

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

Если вы хотите, чтобы пользователи могли настраивать виджет, создайте для него конфигурацию Activity. Это действие автоматически запускается хостом виджета приложения при создании виджета или позже, в зависимости от указанных вами параметров конфигурации.

Объявите действие конфигурации

Объявите действие по настройке как обычное действие в файле манифеста Android. Хост виджета приложения запускает его с помощью действия ACTION_APPWIDGET_CONFIGURE, поэтому действие должно принимать это намерение. Пример:

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

Объявите действие в файле AppWidgetProviderInfo.xml с атрибутом android:configure. Подробнее о декларировании этого файла… Ниже приведен пример объявления действия конфигурации.

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

Действие объявляется с полным пространством имен, поскольку средство запуска ссылается на него за пределами пакета.

Это все, что нужно для начала настройки. Далее вам нужно реализовать само действие.

Реализуйте действие конфигурации

При реализации действия важно помнить о двух моментах:

• Хост виджета приложения вызывает операцию настройки, которая всегда должна возвращать результат. Результат должен включать идентификатор виджета, переданный интентом, который запустил действие, сохраненное в дополнительных данных интента как EXTRA_APPWIDGET_ID.
  • Система не отправляет широковещательное сообщение ACTION_APPWIDGET_UPDATE при запуске действия конфигурации, а значит, не вызывает обновления виджета при его создании. При первом создании виджета действие конфигурации должно запросить обновление у GlanceAppWidget. Однако в последующих циклах обновления запускаются автоматически.

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

Обновление виджета из действия конфигурации

Если виджет использует операцию настройки, то после ее завершения он должен обновиться. Для этого запустите обновление вручную непосредственно из экземпляра GlanceAppWidget.

Ниже приведено краткое описание процедуры правильного обновления виджета и закрытия действия конфигурации:

1. Получите идентификатор виджета приложения из намерения, которое запустило действие:

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

2. Задайте для результата действия значение RESULT_CANCELED.

   Таким образом, если пользователь выйдет из действия до его завершения, система уведомит хост виджета приложения о том, что настройка отменена, и хост не добавит виджет:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

3. Настройте виджет в соответствии с предпочтениями пользователя, например, записав выбранные параметры в постоянное хранилище данных или локальную базу данных.

4. После завершения настройки получите GlanceId, соответствующий идентификатору виджета платформы:

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. Обновите контент виджета, вызвав функцию приостановки update в экземпляре GlanceAppWidget:

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. Создайте намерение возврата, задайте его с результатом действия и завершите действие:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

Варианты конфигурации виджета

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

Примечание. Эти параметры доступны только в Android 12 (уровень API 31) и более поздних версиях. Вы можете указать их для предыдущих версий Android, но система будет игнорировать их и следовать режиму работы по умолчанию.

Разрешить пользователям изменять настройки размещенных виджетов

Чтобы пользователи могли изменять настройки существующих виджетов, укажите флаг reconfigurable в атрибуте widgetFeatures элемента appwidget-provider. Пример:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

Чтобы изменить настройки виджета, пользователю нужно нажать на него и удерживать, а затем нажать кнопку Изменить настройки (обозначена цифрой 1 на рисунке 1).

Рисунок 1. Кнопка Настроить заново.

Использовать конфигурацию виджета по умолчанию

Чтобы сделать виджет удобнее, вы можете разрешить пользователям пропускать этап начальной настройки. Для этого укажите в поле widgetFeatures флаги configuration_optional и reconfigurable. Это позволяет не запускать операцию настройки после того, как пользователь добавит виджет. Как упоминалось ранее, пользователь по-прежнему может перенастроить виджет позже. Например, виджет часов может пропустить начальную настройку и по умолчанию показывать часовой пояс устройства.

Вот пример того, как пометить действие по настройке как необязательное и допускающее повторную настройку:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>