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 zezwolić użytkownikom na konfigurowanie ustawień widżetu, utwórz konfigurację widżetu Activity. Ta aktywność jest uruchamiana automatycznie przez hosta widżetu aplikacji w momencie utworzenia widżetu lub później, w zależności od określonych przez Ciebie opcji konfiguracji.

Deklarowanie aktywności związanej z konfiguracją

Zadeklaruj aktywność konfiguracji jako zwykłą aktywność w pliku manifestu Androida. Host widżetu aplikacji uruchamia go za pomocą działania ACTION_APPWIDGET_CONFIGURE, więc aktywność musi akceptować ten zamiar. 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 związanej z konfiguracją:

<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ą przestrzenią nazw, ponieważ program uruchamiający odwołuje się do niej spoza zakresu pakietu.

To wszystko, czego potrzebujesz, aby rozpocząć konfigurację. Następnie musisz wdrożyć rzeczywistą aktywność.

Wdrażanie aktywności konfiguracji

Podczas wdrażania aktywności pamiętaj 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 działanie – zapisany w dodatkach intencji jako EXTRA_APPWIDGET_ID.
  • System nie wysyła transmisji ACTION_APPWIDGET_UPDATE po uruchomieniu aktywności konfiguracji, co oznacza, że nie wywołuje metody onUpdate() podczas tworzenia widżetu. To działanie konfiguracji odpowiada za wysłanie do AppWidgetManager prośby o aktualizację podczas pierwszego tworzenia widżetu. Jednak w przypadku kolejnych aktualizacji wywoływana jest funkcja onUpdate() – jest ona pomijana tylko za pierwszym razem.

Przykłady fragmentów kodu pokazujące, jak zwrócić wynik z konfiguracji i zaktualizować widżet, znajdziesz w sekcji poniżej.

Aktualizowanie widżetu z poziomu aktywności konfiguracji

Gdy widżet korzysta z aktywności konfiguracji, to ona odpowiada za aktualizowanie widżetu po zakończeniu konfiguracji. Możesz to zrobić, prosząc o aktualizację bezpośrednio w AppWidgetManager.

Oto podsumowanie procedury prawidłowej aktualizacji widżetu i zamknięcia 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 się 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ę zwrotu, ustaw ją za pomocą wyniku 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ład znajdziesz w ListWidgetConfigureActivity.kt przykładowej klasie w GitHubie.

Opcje konfiguracji widżetu

Domyślnie host widżetu aplikacji uruchamia działanie konfiguracyjne tylko raz, bezpośrednio po dodaniu widżetu do ekranu głównego przez użytkownika. Możesz jednak określić opcje, które pozwolą użytkownikom ponownie skonfigurować istniejące widżety lub pominąć wstępną konfigurację widżetu, podając domyślną konfigurację widżetu.

Umożliwianie użytkownikom ponownej konfiguracji umieszczonych widżetów

Aby umożliwić użytkownikom ponowne konfigurowanie istniejących widżetów, w atrybucie widgetFeatures elementu appwidget-provider określ flagę reconfigurable. Więcej informacji znajdziesz w przewodniku na temat deklarowania pliku.AppWidgetProviderInfo.xml 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, który na ilustracji 1 jest oznaczony numerem 1.

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

Użyj domyślnej konfiguracji widżetu

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

Oto przykład, jak oznaczyć aktywność związaną z konfiguracją jako rekonfigurowalną i opcjonalną:

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