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 strefy czasowej, która ma być wyświetlana.

Jeśli chcesz umożliwić użytkownikom konfigurowanie ustawień widżetu, utwórz widżet konfiguracji Activity. Ta aktywność jest automatycznie uruchamiana przez hosta widżetu aplikacji, gdy widżet jest tworzony lub później, w zależności od określonych opcji konfiguracji you specify.

Deklarowanie aktywności konfiguracji

Zadeklaruj aktywność konfiguracji jako zwykłą aktywność w pliku manifestu Androida. Host widżetu aplikacji uruchamia ją za pomocą działania ACTION_APPWIDGET_CONFIGURE, więc aktywność musi akceptować ten 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. Więcej informacji 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 deklarowana z pełną i jednoznaczną przestrzenią nazw, ponieważ program uruchamiający odwołuje się do niej spoza zakresu pakietu.

To wszystko, czego potrzebujesz, aby rozpocząć aktywność konfiguracji. Następnie musisz zaimplementować rzeczywistą aktywność.

Implementowanie aktywności konfiguracji

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

  • Host widżetu aplikacji wywołuje aktywność konfiguracji, która zawsze musi zwracać wynik. Wynik musi zawierać identyfikator widżetu aplikacji przekazany przez intencję, która uruchomiła aktywność – zapisany w dodatkach do intencji jako EXTRA_APPWIDGET_ID.
  • Gdy uruchamiana jest aktywność konfiguracji, system nie wysyła transmisji ACTION_APPWIDGET_UPDATE , co oznacza, że podczas tworzenia widżetu nie wywołuje metody onUpdate(). Aktywność konfiguracji jest odpowiedzialna za wysłanie żądania aktualizacji do AppWidgetManager podczas pierwszego tworzenia widżetu. Jednak w przypadku kolejnych aktualizacji wywoływana jest metoda onUpdate() – jest ona pomijana tylko za pierwszym razem.

Przykłady zwracania wyniku z konfiguracji i aktualizowania widżetu znajdziesz we fragmentach kodu w następnej sekcji.

Aktualizowanie widżetu z poziomu aktywności konfiguracji

Gdy widżet korzysta z aktywności konfiguracji, to ona jest odpowiedzialna za aktualizowanie widżetu po zakończeniu konfiguracji. Możesz to zrobić wysyłając żądanie aktualizacji bezpośrednio do AppWidgetManager.

Oto podsumowanie procedury prawidłowego zaktualizowania widżetu i zamknięcia aktywności konfiguracji:

  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 wyjdzie z aktywności przed jej zakończeniem, 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 uzyskaj instancję 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 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ę zwrotną, ustaw ją z wynikiem aktywności 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 ListWidgetConfigureActivity.kt przykładowej klasie w 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 przez użytkownika. Możesz jednak określić opcje, które umożliwiają użytkownikom ponowne skonfigurowanie istniejących widżetów lub pominięcie początkowej konfiguracji widżetu przez podanie domyślnej konfiguracji widżetu.

Umożliwianie użytkownikom ponownego konfigurowania 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 po deklarowaniu pliku AppWidgetProviderInfo.xml dla więcej informacji. Na przykład:

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

Użytkownicy mogą ponownie skonfigurować widżet, dotykając go i przytrzymując, a następnie klikając przycisk Ponownie skonfiguruj oznaczony 1 na rysunku 1.

Przycisk pojawia się w prawym dolnym rogu
Rysunek 1. Przycisk Ponownie skonfiguruj widżetu.

Używanie domyślnej konfiguracji widżetu

Możesz zapewnić użytkownikom lepsze wrażenia z korzystania z widżetu, umożliwiając im pominięcie początkowego kroku konfiguracji. Aby to zrobić, określ flagi configuration_optional i reconfigurable w polu widgetFeatures. Spowoduje to pominięcie uruchomienia aktywności konfiguracji po dodaniu widżetu przez użytkownika. Jak wspomnieliśmy wcześniej, użytkownik może później ponownie skonfigurować widżet. Na przykład widżet zegara może pominąć początkową konfigurację i domyślnie wyświetlać strefę czasową urządzenia.

Oto przykład, jak oznaczyć aktywność konfiguracji jako możliwą do ponownego skonfigurowania i opcjonalną:

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