Widżety aplikacji można konfigurować. Na przykład widżet zegara może umożliwiać użytkownikom skonfigurowanie wyświetlanej strefy czasowej.
Jeśli chcesz zezwolić użytkownikom na konfigurowanie ustawień widżetu, utwórz konfigurację widżetu Activity
. Ta aktywność jest automatycznie uruchamiana przez hosta widżetu aplikacji podczas jego tworzenia lub później, w zależności od wybranych opcji konfiguracji.
Zadeklaruj aktywność związaną z konfiguracją
Zadeklaruj aktywność związaną z konfiguracją jako normalną aktywność w pliku manifestu Androida. Host widżetu aplikacji uruchamia go z działaniem ACTION_APPWIDGET_CONFIGURE
, więc aktywność musi zaakceptować tę 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
. Dowiedz się więcej o deklarowaniu tego pliku. Oto przykład zadeklarowania działania konfiguracyjnego:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
...
android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
... >
</appwidget-provider>
Aktywność jest deklarowana za pomocą w pełni kwalifikowanej przestrzeni nazw, ponieważ program uruchamiający odwołuje się do niej spoza zakresu pakietu.
To wszystko, czego potrzebujesz, aby rozpocząć aktywność związaną z konfiguracją. Następnie trzeba zaimplementować rzeczywiste działanie.
Zaimplementuj aktywność związaną z konfiguracją
Podczas implementowania działania należy pamiętać o 2 ważnych kwestiach:
- Host widżetu aplikacji wywołuje aktywność związaną z konfiguracją, która zawsze musi zwracać wynik. Wynik musi zawierać identyfikator widżetu aplikacji przekazany przez intencję uruchomioną aktywność – zapisany w dodatkowych rozszerzeniach intencji jako
EXTRA_APPWIDGET_ID
. - System nie wysyła transmisji
ACTION_APPWIDGET_UPDATE
po uruchomieniu działania związanego z konfiguracją, co oznacza, że nie wywołuje metodyonUpdate()
po utworzeniu widżetu. To działanie związane z konfiguracją odpowiada za żądanie aktualizacji zAppWidgetManager
podczas tworzenia widżetu po raz pierwszy. ParametronUpdate()
jest jednak wywoływany przy kolejnych aktualizacjach – jest pomijany tylko za pierwszym razem.
Przykładowe zwracanie wyniku z konfiguracji i aktualizowanie widżetu znajdziesz we fragmentach kodu w następnej sekcji.
Zaktualizuj widżet na podstawie aktywności związanej z konfiguracją
Gdy widżet używa działania związanego z konfiguracją, odpowiada ono za aktualizację widżetu po zakończeniu konfiguracji. Aby to zrobić, poproś o aktualizację bezpośrednio na stronie AppWidgetManager
.
Oto podsumowanie procedury prawidłowego aktualizowania widżetu i zamykania aktywności konfiguracyjnej:
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); }
Ustaw wynik aktywności na
RESULT_CANCELED
.Dzięki temu, jeśli użytkownik wycofa działanie, zanim dotrze do końca, 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);
Skonfiguruj widżet zgodnie z preferencjami użytkownika.
Po zakończeniu konfiguracji pobierz instancję
AppWidgetManager
, wywołując funkcjęgetInstance(Context)
:Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
Zaktualizuj widżet za pomocą układu
RemoteViews
, wywołując metodę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);
Utwórz intencję zwrotu, ustaw ją za pomocą wyniku działania 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 przykładowej klasie ListWidgetConfigureActivity.kt
na GitHubie.
Opcje konfiguracji widżetu
Domyślnie host widżetu aplikacji uruchamia aktywność związaną z konfiguracją tylko raz, natychmiast po dodaniu przez użytkownika widżetu do ekranu głównego. Możesz jednak określić opcje, które umożliwią użytkownikom ponowne konfigurowanie istniejących widżetów lub pominięcie początkowej konfiguracji widżetów przez ustawienie domyślnej konfiguracji widżetu.
Pozwól użytkownikom na ponowne skonfigurowanie 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 deklarowania pliku AppWidgetProviderInfo.xml
. Na przykład:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable">
</appwidget-provider>
Użytkownicy mogą zmienić konfigurację widżetu, naciskając i przytrzymując widżet, a następnie klikając przycisk Skonfiguruj ponownie, który jest oznaczony etykietą 1 na ilustracji 1.
Użyj domyślnej konfiguracji widżetu
Żeby zapewnić większą płynność działania widżetów, możesz zezwolić użytkownikom na pomijanie początkowego kroku konfiguracji. Aby to zrobić, w polu widgetFeatures
podaj flagi configuration_optional
i reconfigurable
. Pomija to uruchamianie aktywności konfiguracyjnej po dodaniu widżetu przez użytkownika. Jak wspomnieliśmy wcześniej, użytkownik nadal może później ponownie skonfigurować widżet. Widżet zegara może na przykład pominąć konfigurację początkową i domyślnie wyświetlać strefę czasową urządzenia.
Oto przykład oznaczenia aktywności konfiguracyjnej jako opcjonalnych i możliwych do ponownego skonfigurowania:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>