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

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

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

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

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

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

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

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

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

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