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

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

Если вы хотите, чтобы пользователи могли настраивать параметры вашего виджета, создайте 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.

Параметры настройки виджета

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

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

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

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

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

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

Рисунок 1. Кнопка «Перенастройка виджета».

Примечание. Флаг reconfigurable был представлен в Android 9 (уровень API 28), но он не получил широкой поддержки до Android 12.

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

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

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

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