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 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.

Deklarowanie aktywności konfiguracji

Zadeklaruj aktywność konfiguracji jako zwykłą aktywność w pliku manifestu Androida. Host widżetu aplikacji uruchamia ją za pomocą ACTION_APPWIDGET_CONFIGURE działania, 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 intencji jako EXTRA_APPWIDGET_ID.
  • Gdy uruchamiana jest aktywność konfiguracji, system nie wysyła transmisji ACTION_APPWIDGET_UPDATE broadcast , co oznacza, że początkowo nie wywołuje aktualizacji widżetu, gdy jest on tworzony. Aktywność konfiguracji jest odpowiedzialna za żądanie aktualizacji z GlanceAppWidget podczas pierwszego tworzenia widżetu. Jednak w kolejnych cyklach aktualizacje są wyzwalane automatycznie.

Przykłady zwracania wyniku z konfiguracji i aktualizowania widżetu Glance 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ć, wywołując ręczną aktualizację bezpośrednio z instancji GlanceAppWidget.

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ść:

   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 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:

   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ę zwrotną, ustaw ją z wynikiem 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ść konfiguracji 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 ponowną konfigurację istniejących widżetów, określ reconfigurable flagę w atrybucie widgetFeatures elementu appwidget-provider. Na przykład:

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

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

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 ponownej konfiguracji i opcjonalną:

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