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 wybranie strefy czasowej.

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. . Gospodarz 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. Dowiedz się więcej 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 zadeklarowana w pełnej nazwie 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 zaimplementuj 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ą oraz konfigurację działanie musi zawsze zwracać wynik. Wynik musi zawierać identyfikator widżetu aplikacji przekazany przez intencję, która uruchomiła działanie. Identyfikator ten jest zapisany w dodatkowych danych intencji jako 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. Jednak funkcja onUpdate() jest wywoływana w przypadku kolejnych aktualizacji – pomija się ją tylko przy pierwszym wywołaniu.

We fragmentach kodu w następnej sekcji znajdziesz przykład zwracania i zaktualizować widżet.

Aktualizowanie widżetu z poziomu aktywności konfiguracji

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 powiadamia hosta widżetu aplikacji o anulowaniu konfiguracji, 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ę usługi AppWidgetManager, wywołując funkcję 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 funkcję 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ę powrotu, ustaw ją z wynikiem 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ładem jest klasa ListWidgetConfigureActivity.kt na GitHubie.

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. Możesz jednak określić opcje, które pozwolą użytkownikom na zmianę konfiguracji dotychczasowych widżetów lub pominięcie początkowej konfiguracji widżetu przez podanie domyślnej konfiguracji widżetu.

Pozwól użytkownikom na zmianę konfiguracji umieszczonych widżetów

Aby umożliwić użytkownikom zmianę konfiguracji dotychczasowych widżetów, określ flagę reconfigurable w atrybucie widgetFeatures elementu appwidget-provider. 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ć 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 pojawia się w prawym dolnym rogu
Rysunek 1. Przycisk Ponownie skonfiguruj widżet.

Używanie domyślnej konfiguracji widgetu

Widżet może być bardziej płynny, pozwalając użytkownikom na pomijanie początkowym etapie konfiguracji. Aby to zrobić, w polu widgetFeatures określ flagi configuration_optional i reconfigurable. Pomija to uruchamiania aktywności konfiguracyjnej po dodaniu widżetu przez użytkownika. Jak wspomnieliśmy wcześniej, użytkownik może później ponownie skonfigurować widget. 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 opcjonalnych i możliwych do ponownego skonfigurowania.

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