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

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

Если вы хотите, чтобы пользователи могли настраивать параметры вашего виджета, создайте Activity для конфигурации виджета. Эта 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. Создайте Intent возврата, задайте в нем результат действия и завершите действие:

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

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

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

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

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

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

Пользователи могут изменить настройки своего виджета, коснувшись и удерживая виджет, а затем нажав кнопку « Изменить настройки» , обозначенную цифрой 1 на рисунке 1.

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

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

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

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