Zezwalaj użytkownikom na konfigurowanie widżetów aplikacji

Widżety aplikacji można konfigurować. Na przykład widżet zegara może umożliwiać użytkownikom skonfigurowanie wyświetlanej strefy czasowej.

Jeśli chcesz zezwolić użytkownikom na konfigurowanie ustawień widżetu, utwórz konfigurację widżetu Activity. Ta aktywność jest automatycznie uruchamiana przez hosta widżetu aplikacji podczas jego tworzenia lub później, w zależności od wybranych opcji konfiguracji.

Zadeklaruj aktywność związaną z konfiguracją

Zadeklaruj aktywność związaną z konfiguracją jako normalną aktywność w pliku manifestu Androida. Host widżetu aplikacji uruchamia go z działaniem ACTION_APPWIDGET_CONFIGURE, więc aktywność musi zaakceptować tę intencję. Na przykład:

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

Zadeklaruj aktywność w pliku AppWidgetProviderInfo.xml za pomocą atrybutu android:configure. Dowiedz się więcej o deklarowaniu tego pliku. Oto przykład zadeklarowania działania konfiguracyjnego:

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

Aktywność jest deklarowana za pomocą w pełni kwalifikowanej przestrzeni nazw, ponieważ program uruchamiający odwołuje się do niej spoza zakresu pakietu.

To wszystko, czego potrzebujesz, aby rozpocząć aktywność związaną z konfiguracją. Następnie trzeba zaimplementować rzeczywiste działanie.

Zaimplementuj aktywność związaną z konfiguracją

Podczas implementowania działania należy pamiętać o 2 ważnych kwestiach:

  • Host widżetu aplikacji wywołuje aktywność związaną z konfiguracją, która zawsze musi zwracać wynik. Wynik musi zawierać identyfikator widżetu aplikacji przekazany przez intencję uruchomioną aktywność – zapisany w dodatkowych rozszerzeniach intencji jako EXTRA_APPWIDGET_ID.
  • System nie wysyła transmisji ACTION_APPWIDGET_UPDATE po uruchomieniu działania związanego z konfiguracją, co oznacza, że nie wywołuje metody onUpdate() po utworzeniu widżetu. To działanie związane z konfiguracją odpowiada za żądanie aktualizacji z AppWidgetManager podczas tworzenia widżetu po raz pierwszy. Parametr onUpdate() jest jednak wywoływany przy kolejnych aktualizacjach – jest pomijany tylko za pierwszym razem.

Przykładowe zwracanie wyniku z konfiguracji i aktualizowanie widżetu znajdziesz we fragmentach kodu w następnej sekcji.

Zaktualizuj widżet na podstawie aktywności związanej z konfiguracją

Gdy widżet używa działania związanego z konfiguracją, odpowiada ono za aktualizację widżetu po zakończeniu konfiguracji. Aby to zrobić, poproś o aktualizację bezpośrednio na stronie AppWidgetManager.

Oto podsumowanie procedury prawidłowego aktualizowania widżetu i zamykania aktywności konfiguracyjnej:

  1. Pobierz identyfikator widżetu aplikacji z intencji, która uruchomiła aktywność:

    Kotlin

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

    Java

    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. Ustaw wynik aktywności na RESULT_CANCELED.

    Dzięki temu, jeśli użytkownik wycofa działanie, zanim dotrze do końca, system powiadomi hosta widżetu aplikacji, że konfiguracja została anulowana, a host nie doda widżetu:

    Kotlin

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

    Java

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

  3. Skonfiguruj widżet zgodnie z preferencjami użytkownika.

  4. Po zakończeniu konfiguracji pobierz instancję AppWidgetManager, wywołując funkcję getInstance(Context):

    Kotlin

    val appWidgetManager = AppWidgetManager.getInstance(context)

    Java

    AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

  5. Zaktualizuj widżet za pomocą układu RemoteViews, wywołując metodę updateAppWidget(int,RemoteViews):

    Kotlin

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

    Java

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

  6. Utwórz intencję zwrotu, ustaw ją za pomocą wyniku działania i zakończ aktywność:

    Kotlin

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

    Java

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

Przykład znajdziesz w przykładowej klasie ListWidgetConfigureActivity.kt na GitHubie.

Opcje konfiguracji widżetu

Domyślnie host widżetu aplikacji uruchamia aktywność związaną z konfiguracją tylko raz, natychmiast po dodaniu przez użytkownika widżetu do ekranu głównego. Możesz jednak określić opcje, które umożliwią użytkownikom ponowne konfigurowanie istniejących widżetów lub pominięcie początkowej konfiguracji widżetów przez ustawienie domyślnej konfiguracji widżetu.

Pozwól użytkownikom na ponowne skonfigurowanie umieszczonych widżetów

Aby umożliwić użytkownikom ponowne konfigurowanie istniejących widżetów, określ flagę reconfigurable w atrybucie widgetFeatures appwidget-provider. Więcej informacji znajdziesz w przewodniku deklarowania pliku AppWidgetProviderInfo.xml. Na przykład:

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

Użytkownicy mogą zmienić konfigurację widżetu, naciskając i przytrzymując widżet, a następnie klikając przycisk Skonfiguruj ponownie, który jest oznaczony etykietą 1 na ilustracji 1.

Przycisk wyświetla się w prawym dolnym rogu
Rysunek 1. Przycisk Ponownie skonfiguruj widżet.

Użyj domyślnej konfiguracji widżetu

Żeby zapewnić większą płynność działania widżetów, możesz zezwolić użytkownikom na pomijanie początkowego kroku konfiguracji. Aby to zrobić, w polu widgetFeatures podaj flagi configuration_optional i reconfigurable. Pomija to uruchamianie aktywności konfiguracyjnej po dodaniu widżetu przez użytkownika. Jak wspomnieliśmy wcześniej, użytkownik nadal może później ponownie skonfigurować widżet. Widżet zegara może na przykład pominąć konfigurację początkową i domyślnie wyświetlać strefę czasową urządzenia.

Oto przykład oznaczenia aktywności konfiguracyjnej jako opcjonalnych i możliwych do ponownego skonfigurowania:

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