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

Zaprojektuj widżet tak, aby użytkownicy mogli konfigurować określone cechy. 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 konfigurację widżetu Activity. Ta aktywność jest uruchamiana automatycznie przez hosta widżetu aplikacji podczas tworzenia widżetu lub później, w zależności od określonych 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. 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 deklaracji 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ą i jednoznaczną 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 związanej z konfiguracją

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 aktywność zapisaną w dodatkach intencji jako EXTRA_APPWIDGET_ID.
  • System nie wysyła transmisji ACTION_APPWIDGET_UPDATE, gdy uruchamiana jest aktywność konfiguracji, co oznacza, że nie wywołuje początkowo aktualizacji widżetu podczas jego tworzenia. Za poproszenie o aktualizację z GlanceAppWidget podczas pierwszego tworzenia widżetu odpowiada działanie konfiguracji. W przypadku kolejnych cykli aktualizacje są jednak uruchamiane automatycznie.

W sekcji poniżej znajdziesz przykłady fragmentów kodu, które pokazują, jak zwrócić wynik z konfiguracji i zaktualizować widżet Glance.

Aktualizowanie widżetu z poziomu aktywności konfiguracji

Gdy widżet korzysta z aktywności konfiguracji, to aktywność jest odpowiedzialna za aktualizowanie widżetu po zakończeniu konfiguracji. Możesz to zrobić, wywołując ręczną aktualizację bezpośrednio z GlanceAppWidget.

Oto podsumowanie procedury prawidłowej aktualizacji widżetu i zamknięcia działania związanego z konfiguracją:

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

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_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:

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

3. Skonfiguruj widżet zgodnie z preferencjami użytkownika, np. zapisując wybrane opcje w trwałym magazynie danych lub lokalnej bazie danych.

4. Po zakończeniu konfiguracji pobierz GlanceId odpowiadający identyfikatorowi widżetu platformy:

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. Zaktualizuj zawartość widżetu, wywołując funkcję zawieszenia update w instancji GlanceAppWidget:

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

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

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

Opcje konfiguracji widżetu

Domyślnie host widżetu aplikacji uruchamia aktywność konfiguracyjną 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żytkownikowi ponownie skonfigurować istniejące widżety lub pominąć początkową 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. 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 oznaczony jest numerem 1.

Użyj domyślnej konfiguracji widżetu

Możesz zapewnić użytkownikom płynniejsze 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 trzeba uruchamiać aktywności konfiguracji. 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>