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 skonfigurować wyświetlaną strefę czasową.

Jeśli chcesz pozwolić użytkownikom na konfigurowanie ustawień widżetu, utwórz widżet konfiguracji Activity. To działanie jest jest automatycznie uruchamiany przez hosta widżetu aplikacji podczas jego tworzenia lub później, w zależności od opcji konfiguracji określić.

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 ACTION_APPWIDGET_CONFIGURE działanie, więc 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ą parametru android:configure. Zobacz więcej informacji: zadeklarowanie tego pliku. Oto przykład: Jak zadeklarować aktywność związaną 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 w pełni kwalifikowaną przestrzenią nazw, ponieważ program uruchamiający odwołuje się do niego spoza zakresu pakietu.

To wszystko, czego potrzebujesz, aby rozpocząć aktywność związaną z konfiguracją. Następnie musisz realizowanie działania.

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ą oraz konfigurację działanie musi zawsze zwracać wynik. Wynik musi zawierać widżet aplikacji Identyfikator przekazywany przez intencję, która uruchomiła aktywność – zapisany w intencji. dodatkowe EXTRA_APPWIDGET_ID
  • System nie wysyła ACTION_APPWIDGET_UPDATE jest przesyłana po uruchomieniu działania konfiguracji, co oznacza, że nie jest wywołuje metodę onUpdate() podczas tworzenia widżetu. Działanie związane z konfiguracją odpowiada za wysyłanie próśb o aktualizację z urządzenia AppWidgetManager podczas tworzenia widżetu po raz pierwszy. Pamiętaj jednak: Metoda onUpdate() jest wywoływana przy kolejnych aktualizacjach – jest pomijana tylko za pierwszym razem.

We fragmentach kodu poniżej znajdziesz przykład zwracania i zaktualizować widżet.

Zaktualizuj widżet na podstawie aktywności związanej z konfiguracją

Gdy widżet używa działania konfiguracyjnego, obowiązkiem działanie aktualizacji widżetu po zakończeniu konfiguracji. Możesz to zrobić możesz poprosić o aktualizację bezpośrednio do AppWidgetManager

Oto podsumowanie procedury prawidłowej aktualizacji widżetu i zamknięcia aktywność związana z konfiguracją:

  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 dotarciem do końca, system powiadomi hosta widżetu aplikacji, że konfiguracja została anulowana, host nie dodaje 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 pobierz instancję AppWidgetManager, dzwoniąc pod numer getInstance(Context):

    Kotlin

    val appWidgetManager = AppWidgetManager.getInstance(context)

    Java

    AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

  5. Dodaj do widżetu Układ RemoteViews przez wywołanie 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. utworzyć intencję zwrotu, ustawić ją za pomocą wyniku aktywności; 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();

Zobacz ListWidgetConfigureActivity.kt znajdziesz 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. Musisz jednak mogą określać opcje umożliwiające użytkownikom ponowne konfigurowanie istniejących widżetów lub możesz pominąć początkową konfigurację widżetu, podając domyślną konfigurację.

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 reconfigurable flagę w widgetFeatures appwidget-provider. Zapoznaj się z przewodnikiem deklarowania AppWidgetProviderInfo.xml plik, aby uzyskać więcej i informacjami o nich. Na przykład:

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

Użytkownicy mogą ponownie skonfigurować swój widżet, dotykając ikony i przytrzymując widżet i klikając znajduje się przycisk Skonfiguruj ponownie. 1 na ilustracji 1.

Przycisk wyświetla się w prawym dolnym rogu
Rysunek 1. Przycisk Ponownie skonfiguruj widżet.
.

Użyj domyślnej konfiguracji widżetu

Widżet może być bardziej płynny, pozwalając użytkownikom na pomijanie początkowym etapie konfiguracji. Aby to zrobić, podaj zarówno parametr configuration_optional i reconfigurable w polu widgetFeatures. Pomija to uruchamiania aktywności konfiguracyjnej po dodaniu widżetu przez użytkownika. Jak wspomniano użytkownik może nadal ponownie skonfigurować widżet. później. Widżet zegara może na przykład pominąć konfigurację początkową i domyślnie pokazuje strefę czasową urządzenia.

Oto przykład oznaczenia aktywności konfiguracyjnej jako obu tych elementów opcjonalnych i możliwych do ponownego skonfigurowania.

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