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

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

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

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

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

 android:name=".ExampleAppWidgetConfigurationActivity">
    
         android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>

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

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

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

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

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

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

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

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

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

Когда виджет использует конфигурационную активность, то ответственность за обновление виджета после завершения конфигурации лежит на активности. Вы можете сделать это, запросив обновление напрямую из AppWidgetManager .

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

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

    Котлин 

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

    Ява 

    Intent intent = getIntent();
Bundle extras = intent.getExtras();
int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
if (extras != null) {
    appWidgetId = extras.getInt(
            AppWidgetManager.EXTRA_APPWIDGET_ID,
            AppWidgetManager.INVALID_APPWIDGET_ID);
}

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

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

    Котлин 

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

    Ява 

    int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
setResult(Activity.RESULT_CANCELED, resultValue);

  3. Настройте виджет в соответствии с предпочтениями пользователя.

  4. После завершения настройки получите экземпляр AppWidgetManager , вызвав getInstance(Context) :

    Котлин 

    val appWidgetManager = AppWidgetManager.getInstance(context)

    Ява 

    AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

  5. Обновите виджет с помощью макета RemoteViews , вызвав updateAppWidget(int,RemoteViews) :

    Котлин 

    val views = RemoteViews(context.packageName, R.layout.example_appwidget)
appWidgetManager.updateAppWidget(appWidgetId, views)

    Ява 

    RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
appWidgetManager.updateAppWidget(appWidgetId, views);

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

    Котлин 

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

    Ява 

    Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
setResult(RESULT_OK, resultValue);
finish();

В качестве примера см. пример класса ListWidgetConfigureActivity.kt на GitHub.

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

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

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

Чтобы разрешить пользователям перенастраивать существующие виджеты, укажите флаг reconfigurable в атрибуте widgetFeatures appwidget-provider . Для получения дополнительной информации см. руководство по объявлению файла AppWidgetProviderInfo.xml . Например: 

    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">

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

Кнопка появляется в правом нижнем углу
Рисунок 1. Кнопка перенастройки виджета.

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

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

Вот пример того, как обозначить вашу конфигурационную активность как реконфигурируемую и необязательную: 

    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">