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 wybranie strefy czasowej.

Jeśli chcesz, aby użytkownicy mogli konfigurować ustawienia widżetu, utwórz jego konfigurację Activity. Ta aktywność jest uruchamiana automatycznie przez hosta widżetu aplikacji albo w momencie utworzenia widżetu, albo później, w zależności od określonych przez Ciebie opcji konfiguracji.

Oświadczenie o działalności związanej z konfiguracją

W pliku manifestu Androida zadeklaruj aktywność konfiguracji jako zwykłą aktywność. Gospodarz widżetu aplikacji uruchamia go za pomocą działania ACTION_APPWIDGET_CONFIGURE, więc aktywność musi akceptować ten zamiar. 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 deklarowania aktywności konfiguracji:

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

Aktywność jest zadeklarowana w pełnej nazwie przestrzeni nazw, ponieważ program uruchamiający odwołuje się do niej spoza zakresu pakietu.

To wszystko, czego potrzebujesz, aby rozpocząć konfigurację. Następnie musisz zaimplementować właściwą aktywność.

Wdrażanie aktywności konfiguracji

Podczas wdrażania tej aktywności należy pamiętać o 2 ważnych kwestiach:

  • Host widżetu aplikacji wywołuje aktywność konfiguracji, a ta aktywność musi zawsze zwracać wynik. Wynik musi zawierać identyfikator widżetu aplikacji przekazany przez intencję, która uruchomiła działanie. Identyfikator ten jest zapisany w dodatkowych danych intencji jako EXTRA_APPWIDGET_ID.
  • System nie wysyła transmisji ACTION_APPWIDGET_UPDATE, gdy uruchamiana jest aktywność konfiguracji, co oznacza, że nie wywołuje metody onUpdate() podczas tworzenia widgeta. Podczas tworzenia widżetu po raz pierwszy aktywność konfiguracyjna musi poprosić o aktualizację AppWidgetManager. Jednak funkcja onUpdate() jest wywoływana w przypadku kolejnych aktualizacji – pomija się ją tylko przy pierwszym wywołaniu.

Przykłady kodu, który zwraca wynik z konfiguracji i aktualizuje widżet, znajdziesz w sekcji poniżej.

Aktualizowanie widżetu z poziomu aktywności konfiguracji

Gdy widżet korzysta z działania konfiguracyjnego, to właśnie ono odpowiada za jego zaktualizowanie po zakończeniu konfiguracji. Możesz to zrobić, prosząc o aktualizację bezpośrednio w AppWidgetManager.

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

  1. Pobierz identyfikator widżetu aplikacji z intencji, która uruchomiła działanie:

    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.

    W ten sposób, jeśli użytkownik wycofa się z działania przed jego zakończeniem, system powiadomi hosta widżetu aplikacji, że konfiguracja została anulowana, i 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 wystąpienie interfejsu AppWidgetManager, wywołując 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 funkcję 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ę powrotu, ustaw ją z wynikiem działania i zakończ działanie:

    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ładem jest klasa ListWidgetConfigureActivity.kt na GitHubie.

Opcje konfiguracji widżetu

Domyślnie host widżetu aplikacji uruchamia aktywność konfiguracji tylko raz, bezpośrednio po dodaniu widżetu do ekranu głównego. Możesz jednak określić opcje, które pozwolą użytkownikom na zmianę konfiguracji dotychczasowych widżetów lub pominięcie początkowej konfiguracji widżetu przez podanie domyślnej konfiguracji widżetu.

Zezwalanie użytkownikom na zmianę konfiguracji umieszczonych widżetów

Aby umożliwić użytkownikom zmianę konfiguracji dotychczasowych widżetów, określ flagę reconfigurable w atrybucie widgetFeatures w elementach appwidget-provider. Więcej informacji znajdziesz w przewodniku na temat deklarowania pliku AppWidgetProviderInfo.xml. Przykład:

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

Użytkownicy mogą zmienić konfigurację widżetu, dotykając go i przytrzymując, a następnie klikając przycisk Zmień konfigurację (1 na rysunku 1).

przycisk pojawi się w prawym dolnym rogu;
Rysunek 1. Przycisk Skonfiguruj ponownie widżetu.

Używanie domyślnej konfiguracji widgetu

Możesz zapewnić płynniejsze korzystanie z widżetu, pozwalając użytkownikom pominąć początkowy krok konfiguracji. Aby to zrobić, w polu widgetFeatures określ flagi configuration_optional i reconfigurable. Dzięki temu nie trzeba uruchamiać czynności konfiguracyjnej po dodaniu widżetu przez użytkownika. Jak wspomnieliśmy wcześniej, użytkownik może później ponownie skonfigurować widget. Na przykład widżet zegara może pominąć początkową konfigurację i domyślnie wyświetlać strefę czasową urządzenia.

Oto przykład oznaczenia aktywności konfiguracyjnej jako konfigurowalnej i opcjonalnej:

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