Tworzenie prostego widżetu

Widżety aplikacji to miniaturowe widoki aplikacji, które możesz umieścić w innych aplikacjach, np. na ekranie głównym, i otrzymywać okresowe aktualizacje. W interfejsie użytkownika takie widoki są nazywane widżetami, które można opublikować, korzystając z dostawcy widżetów aplikacji (lub dostawcy widżetów). Komponent aplikacji, który zawiera inne widżety, jest nazywany hostem widżetu aplikacji (lub hostem widżetu). Ilustracja 1 przedstawia widżet z przykładową muzyką:

W tym dokumencie opisujemy, jak opublikować widżet, korzystając z jego dostawcy. Szczegółowe informacje o tworzeniu własnych AppWidgetHost do hostowania widżetów aplikacji znajdziesz w artykule Tworzenie hosta widżetów.

Aby dowiedzieć się, jak zaprojektować widżet, zobacz Omówienie widżetów aplikacji.

Komponenty widżetów

Aby utworzyć widżet, potrzebujesz następujących podstawowych komponentów:

AppWidgetProviderInfo obiekt

Opisuje metadane widżetu, takie jak układ widżetu, częstotliwość aktualizacji i klasa AppWidgetProvider. Parametr AppWidgetProviderInfo jest zdefiniowany w pliku XML, zgodnie z opisem w tym dokumencie.

AppWidgetProvider zajęcia

Określa podstawowe metody, które umożliwiają programowy interfejs za pomocą widżetu. Dzięki niemu możesz odbierać komunikaty o aktualizacjach, włączeniu, wyłączeniu lub usunięciu widżetu. Zadeklarujesz AppWidgetProvider w manifestu, a następniewdrożysz go zgodnie z opisem w tym dokumencie.

Wyświetl układ

Określa początkowy układ widżetu. Układ jest zdefiniowany w pliku XML, jak opisano w tym dokumencie.

Rysunek 2 pokazuje, jak te komponenty wpasowują się w ogólny proces przetwarzania widżetów aplikacji.

Jeśli widżet wymaga konfiguracji użytkownika, zaimplementuj aktywność związaną z konfiguracją widżetu aplikacji. Ta aktywność pozwala użytkownikom modyfikować ustawienia widżetu, na przykład strefę czasową widżetu zegara.

• Począwszy od Androida 12 (poziom interfejsu API 31) możesz podać konfigurację domyślną i umożliwić użytkownikom ponowne skonfigurowanie widżetu. Więcej informacji znajdziesz w artykułach Używanie domyślnej konfiguracji widżetu i Zezwalanie użytkownikom na ponowne konfigurowanie umieszczonych widżetów.
• W Androidzie 11 (poziom interfejsu API 30) lub starszym ta aktywność jest uruchamiana za każdym razem, gdy użytkownik doda widżet do ekranu głównego.

Zalecamy też wprowadzenie tych ulepszeń: elastyczne układy widżetów, inne ulepszenia, widżety zaawansowane, widżety kolekcji oraz tworzenie hosta widżetów.

Zadeklarowanie pliku XML AppWidgetProviderInfo

Obiekt AppWidgetProviderInfo określa podstawowe cechy widżetu. Zdefiniuj obiekt AppWidgetProviderInfo w pliku zasobów XML za pomocą jednego elementu <appwidget-provider> i zapisz go w folderze res/xml/ projektu.

Widać to w tym przykładzie:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/example_loading_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

Atrybuty rozmiaru widżetu

Domyślny ekran główny umieszcza widżety w oknie na podstawie siatki komórek o określonej wysokości i szerokości. Większość ekranów głównych zezwala widżetom na przyjmowanie tylko rozmiarów, które są wielokrotnościami komórek siatki – na przykład dwie komórki w poziomie i trzy komórki w pionie.

Atrybuty rozmiaru widżetu pozwalają określić domyślny rozmiar widżetu oraz określić dolne i górne granice jego rozmiaru. W tym kontekście domyślny rozmiar widżetu to jego rozmiar przy pierwszym dodaniu do ekranu głównego.

W tabeli poniżej opisujemy atrybuty <appwidget-provider> odnoszące się do rozmiarów widżetów:

Przykład

Aby pokazać, jak atrybuty z poprzedniej tabeli wpływają na rozmiar widżetu, załóżmy, że:

• Komórka siatki ma szerokość 30 dp i wysokość 50 dp.
• Podana specyfikacja atrybutów:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

Od Androida 12:

Użyj atrybutów targetCellWidth i targetCellHeight jako domyślnego rozmiaru widżetu.

Domyślny rozmiar widżetu to 2 x 2. Rozmiar widżetu można zmniejszyć do 2 x 1 lub maksymalnie 4 x 3.

Android 11 i starsze wersje:

Użyj atrybutów minWidth i minHeight, aby obliczyć domyślny rozmiar widżetu.

Domyślna szerokość = Math.ceil(80 / 30) = 3

Wysokość domyślna = Math.ceil(80 / 50) = 2

Domyślny rozmiar widżetu to 3 x 2. Widżet można zmniejszyć do rozmiaru 2 x 1 lub do pełnego ekranu.

Dodatkowe atrybuty widżetu

W tej tabeli opisano atrybuty <appwidget-provider> odnoszące się do jakości innych niż rozmiary widżetów.

Użyj klasy AppWidgetProvider do obsługi komunikatów widżetów

Klasa AppWidgetProvider obsługuje transmisje widżetów i aktualizuje widżet w odpowiedzi na zdarzenia cyklu życia widżetu. W sekcjach poniżej opisano, jak zadeklarować AppWidgetProvider w pliku manifestu, a potem go wdrożyć.

Zadeklarowanie widżetu w pliku manifestu

Najpierw zadeklaruj klasę AppWidgetProvider w pliku AndroidManifest.xml aplikacji, jak w tym przykładzie:

<receiver android:name="ExampleAppWidgetProvider"
                 android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />
</receiver>

Element <receiver> wymaga atrybutu android:name, który określa AppWidgetProvider używany przez widżet. Komponentu nie można eksportować, chyba że do rozgłaszania AppWidgetProvider trzeba przesłać oddzielny proces, co zwykle nie jest konieczne.

Element <intent-filter> musi zawierać element <action> z atrybutem android:name. Ten atrybut określa, że AppWidgetProvider akceptuje transmisję ACTION_APPWIDGET_UPDATE. To jedyna transmisja, którą musisz wyraźnie zadeklarować. W razie potrzeby AppWidgetManager automatycznie wysyła wszystkie inne komunikaty widżetów do AppWidgetProvider.

Element <meta-data> określa zasób AppWidgetProviderInfo i wymaga tych atrybutów:

• android:name: określa nazwę metadanych. Używaj parametru android.appwidget.provider, aby wskazać dane jako deskryptor AppWidgetProviderInfo.
• android:resource: określa lokalizację zasobu AppWidgetProviderInfo.

Implementowanie klasy AppWidgetProvider

Klasa AppWidgetProvider rozszerza BroadcastReceiver jako klasę wygodną do obsługi komunikatów widżetów. Odbiera tylko transmisje zdarzeń odpowiednie dla widżetu, na przykład informacje o tym, kiedy widżet został zaktualizowany, usunięty, włączony i wyłączony. W przypadku wystąpienia takich transmisji wywoływane są następujące metody AppWidgetProvider:

onUpdate()

Wywołuje się to do aktualizowania widżetu w odstępach czasowych określonych przez atrybut updatePeriodMillis w AppWidgetProviderInfo. Więcej informacji znajdziesz w tabeli z opisem dodatkowych atrybutów widżetów na tej stronie.

Metoda ta jest również wywoływana, gdy użytkownik dodaje widżet, dzięki czemu wykonuje podstawową konfigurację, np. definiuje moduły obsługi zdarzeń dla obiektów View lub rozpoczyna zadania wczytywania danych, które mają być wyświetlane w widżecie. Jeśli jednak zadeklarujesz działanie związane z konfiguracją bez flagi configuration_optional, ta metoda nie będzie wywoływana, gdy użytkownik doda widżet, ale jest wywoływana przy kolejnych aktualizacjach. To działanie związane z konfiguracją odpowiada za wykonanie pierwszej aktualizacji po zakończeniu konfiguracji. Więcej informacji znajdziesz w artykule Umożliwianie użytkownikom konfigurowania widżetów aplikacji.

Najważniejsze wywołanie zwrotne to onUpdate(). Więcej informacji znajdziesz w sekcji Obsługiwanie zdarzeń za pomocą klasy onUpdate() na tej stronie.

onAppWidgetOptionsChanged()

Ta funkcja jest wywoływana przy pierwszym umieszczaniu widżetu i przy każdorazowej zmianie jego rozmiaru. Za pomocą tego wywołania zwrotnego możesz wyświetlać lub ukrywać treść na podstawie zakresów rozmiarów widżetu. Aby pobrać zakresy rozmiarów – a od Androida 12 – listę możliwych rozmiarów instancji widżetu – wywołaj metodę getAppWidgetOptions(), która zwraca Bundle o następującej wartości:

• OPTION_APPWIDGET_MIN_WIDTH: zawiera dolną granicę szerokości instancji widżetu (w jednostkach dp).
• OPTION_APPWIDGET_MIN_HEIGHT: zawiera dolną granicę wysokości instancji widżetu (w jednostkach dp).
• OPTION_APPWIDGET_MAX_WIDTH: zawiera górną granicę szerokości instancji widżetu (w jednostkach dp).
• OPTION_APPWIDGET_MAX_HEIGHT: zawiera górną granicę wysokości instancji widżetu (w jednostkach dp).
• OPTION_APPWIDGET_SIZES: zawiera listę możliwych rozmiarów (List<SizeF>) w jednostkach dp, które może przyjmować instancja widżetu. Wprowadzone w Androidzie 12.

onDeleted(Context, int[])

Ta funkcja jest wywoływana za każdym razem, gdy widżet jest usuwany z hosta widżetu.

onEnabled(Context)

Ta funkcja jest wywoływana, gdy wystąpienie widżetu jest tworzone po raz pierwszy. Jeśli na przykład użytkownik doda 2 wystąpienia widżetu, jest to wywoływane tylko za pierwszym razem. Jest to dobre rozwiązanie, jeśli chcesz otworzyć nową bazę danych lub wykonać inną konfigurację, która wystarczy przeprowadzić dla wszystkich instancji widżetu tylko raz.

onDisabled(Context)

Jest ona wywoływana, gdy ostatnie wystąpienie widżetu zostanie usunięte z hosta widżetu. W tym miejscu usuniesz całą pracę wykonaną w onEnabled(Context), na przykład usunięcie tymczasowej bazy danych.

onReceive(Context, Intent)

Jest ono wywoływane w przypadku każdej transmisji i przed każdą z poprzedzających ją metod wywołania zwrotnego. Zwykle nie musisz implementować tej metody, ponieważ domyślna implementacja AppWidgetProvider filtruje wszystkie komunikaty widżetów i wywołuje poprzednie metody odpowiednio.

Musisz zadeklarować implementację klasy AppWidgetProvider jako odbiornik za pomocą elementu <receiver> w AndroidManifest. Więcej informacji znajdziesz w sekcji Deklarowanie widżetu w pliku manifestu na tej stronie.

Obsługuj zdarzenia za pomocą klasy onUpdate()

Najważniejsze wywołanie zwrotne AppWidgetProvider to onUpdate(), ponieważ jest ono wywoływane przy dodawaniu każdego widżetu do hosta, chyba że użyjesz działania konfiguracyjnego bez flagi configuration_optional. Jeśli widżet akceptuje zdarzenia interakcji użytkownika, zarejestruj moduły obsługi zdarzeń w tym wywołaniu zwrotnym. Jeśli widżet nie tworzy plików tymczasowych ani baz danych albo nie wykonuje innych zadań, które wymagają wyczyszczenia, jedyną metodą wywołania zwrotnego, jaką musisz zdefiniować, może być onUpdate().

Jeśli np. chcesz mieć widżet z przyciskiem, który po kliknięciu uruchamia aktywność po kliknięciu, możesz użyć tej implementacji AppWidgetProvider:

class ExampleAppWidgetProvider : AppWidgetProvider() {

    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray
    ) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        appWidgetIds.forEach { appWidgetId ->
            // Create an Intent to launch ExampleActivity.
            val pendingIntent: PendingIntent = PendingIntent.getActivity(
                    /* context = */ context,
                    /* requestCode = */  0,
                    /* intent = */ Intent(context, ExampleActivity::class.java),
                    /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
            )

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            val views: RemoteViews = RemoteViews(
                    context.packageName,
                    R.layout.appwidget_provider_layout
            ).apply {
                setOnClickPendingIntent(R.id.button, pendingIntent)
            }

            // Tell the AppWidgetManager to perform an update on the current
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views)
        }
    }
}

public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        for (int i=0; i < appWidgetIds.length; i++) {
            int appWidgetId = appWidgetIds[i];
            // Create an Intent to launch ExampleActivity
            Intent intent = new Intent(context, ExampleActivity.class);
            PendingIntent pendingIntent = PendingIntent.getActivity(
                /* context = */ context,
                /* requestCode = */ 0,
                /* intent = */ intent,
                /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
            );

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget_layout);
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // Tell the AppWidgetManager to perform an update on the current app
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}

Ten AppWidgetProvider definiuje tylko metodę onUpdate(), wykorzystując ją do utworzenia PendingIntent, która uruchamia Activity i dołącza ją do przycisku widżetu za pomocą setOnClickPendingIntent(int, PendingIntent). Zawiera pętlę, która powoduje iterację każdego wpisu w usłudze appWidgetIds, czyli tablicę identyfikatorów identyfikujących każdy widżet utworzony przez tego dostawcę. Jeśli użytkownik utworzy więcej niż jedno wystąpienie widżetu, wszystkie zostaną zaktualizowane jednocześnie. Dla wszystkich instancji widżetu zarządzany jest jednak tylko 1 harmonogram updatePeriodMillis. Jeśli np. harmonogram aktualizacji jest zdefiniowany na 2 godziny, a godzinę po dodaniu widżetu z drugim wystąpieniem, zostaną one zaktualizowane w okresie zdefiniowanym przez pierwszy, a drugi okres aktualizacji zostanie zignorowany. Aktualizują się co 2 godziny, a nie co godzinę.

Więcej informacji znajdziesz w przykładowej klasie ExampleAppWidgetProvider.java.

Odbieranie intencji transmisji widżetu

AppWidgetProvider to zajęcia wygodne. Jeśli chcesz bezpośrednio otrzymywać komunikaty z widżetu, możesz zaimplementować własny element BroadcastReceiver lub zastąpić wywołanie zwrotne onReceive(Context,Intent). Oto intencje, na których musisz się skupić:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

Tworzenie układu widżetu

Musisz zdefiniować początkowy układ widżetu w pliku XML i zapisać go w katalogu res/layout/ projektu. Szczegółowe informacje znajdziesz w wytycznych dotyczących projektowania.

Tworzenie układu widżetu jest proste, jeśli znasz układy. Pamiętaj jednak, że układy widżetów są oparte na narzędziu RemoteViews, który nie obsługuje wszystkich rodzajów układów lub widżetów. Nie możesz używać niestandardowych widoków ani podklas widoków obsługiwanych przez RemoteViews.

RemoteViews obsługuje również ViewStub, czyli niewidoczny element View o zerowym rozmiarze, którego można używać do leniwego zwiększania zasobów układu w czasie działania.

Obsługa zachowania stanowego

Android 12 obsługuje zachowania stanowe za pomocą tych istniejących komponentów:

• CheckBox

• Switch

• RadioButton

Widżet pozostaje bezstanowy. Aplikacja musi przechowywać stan i rejestrować zdarzenia zmiany stanu.

Poniższy przykładowy kod pokazuje, jak wdrożyć te komponenty.

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
        R.id.my_checkbox,
        RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));

Udostępnij 2 układy: jeden jest kierowany na urządzenia z Androidem 12 lub nowszym (res/layout-v31), a drugi w domyślnym folderze res/layout.

Stosuj zaokrąglone rogi.

Android 12 wprowadza te parametry systemowe pozwalające ustawić promienie zaokrąglonych rogów widżetu:

• system_app_widget_background_radius: promień narożnika tła widżetu, który nigdy nie jest większy niż 28 dp.

• system_app_widget_inner_radius: promień narożnika dowolnego widoku w widżecie. Jest to dokładnie o 8 dp mniej niż promień tła, aby zapewnić właściwe dopasowanie przy zastosowaniu dopełnienia 8 dp.

Poniższy przykład przedstawia widżet, który używa system_app_widget_background_radius jako rogu widżetu i system_app_widget_inner_radius w przypadku widoków wewnątrz widżetu.

1 Róg widżetu.

2 Róg widoku w widżecie.

Ważne informacje o zaokrąglonych rogach

• Programy uruchamiające i producenci innych urządzeń mogą zastąpić parametr system_app_widget_background_radius mniejszy niż 28 dp. Parametr system_app_widget_inner_radius jest zawsze o 8 dp mniejszy niż wartość system_app_widget_background_radius.
• Jeśli widżet nie używa @android:id/background lub ma zdefiniowany tło, które nakłada treść na podstawie obrysu (android:clipToOutline ma wartość true), program uruchamiający automatycznie rozpoznaje tło i przycina widżet za pomocą prostokąta z zaokrąglonymi rogami do 16 dp. Zapoznaj się z sekcją Sprawdzanie, czy widżet jest zgodny z Androidem 12.

Aby zapewnić zgodność widżetów z poprzednimi wersjami Androida, zalecamy zdefiniowanie atrybutów niestandardowych i zastąpienie ich motywem niestandardowym, jak widać w tych przykładowych plikach XML:

<resources>
  <attr name="backgroundRadius" format="dimension" />
</resources>

<resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
</resources>

<resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
</resources>

<shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  ...
</shape>

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:background="@drawable/my_widget_background" />