Tworzenie prostego widżetu

Widżety aplikacji to miniatury aplikacji, które możesz umieszczać w innych aplikacjach (np. na ekranie głównym) i regularnie aktualizować. W interfejsie te widoki są nazywane widżetami. Możesz opublikować jeden z nich za pomocą dostawcy widżetów aplikacji (czyli dostawcy widżetów). Składnik aplikacji, który zawiera inne widżety, nazywa się hostem widżetu aplikacji (lub hostem widżetu). Rysunek 1 pokazuje przykładowy widżet muzyczny:

Z tego dokumentu dowiesz się, jak opublikować widżet za pomocą dostawcy widżetów. Szczegółowe informacje o tworzeniu własnych AppWidgetHost do hostowania widżetów aplikacji znajdziesz w artykule Tworzenie hosta widżetów.

Informacje o projektowaniu widżetów znajdziesz w artykule Przegląd widżetów aplikacji.

Komponenty widżetu

Aby utworzyć widżet, potrzebujesz tych podstawowych komponentów:

AppWidgetProviderInfo obiekt

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

AppWidgetProvider zajęcia

Określa podstawowe metody, które umożliwiają programowe tworzenie interfejsu z widżetem. Dzięki niemu otrzymujesz powiadomienia, gdy widżet zostanie zaktualizowany, włączony, wyłączony lub usunięty. Zadeklaruj AppWidgetProvider w pliku manifestu, a następnie wdróż go zgodnie z opisem w tym dokumencie.

Wyświetlanie układu

Określa początkowy układ widżetu. Układ jest zdefiniowany w formacie XML, zgodnie z opisem w tym dokumencie.

Na rysunku 2 widać, jak te komponenty pasują do ogólnego przepływu danych w przypadku widżetów aplikacji.

Jeśli widżet wymaga konfiguracji przez użytkownika, zaimplementuj odpowiednią aktywność. Ta aktywność umożliwia użytkownikom modyfikowanie ustawień widżetów, np. strefy czasowej w widżecie zegara.

• Od Androida 12 (poziom API 31) możesz udostępnić domyślną konfigurację i pozwolić użytkownikom na ponowną konfigurację widżetu. Więcej informacji znajdziesz w artykułach Używanie domyślnej konfiguracji widżetu i Zezwalanie użytkownikom na zmianę konfiguracji umieszczonych widżetów.
• W Androidzie 11 (poziom interfejsu API 30) lub niższym ta aktywność jest uruchamiana za każdym razem, gdy użytkownik dodaje widżet do ekranu głównego.

Polecamy też te usprawnienia: elastyczne układy widżetów, różne ulepszenia, zaawansowane widżety, widżety kolekcji i tworzenie hosta widżetów.

Zadeklaruj plik XML AppWidgetProviderInfo

Obiekt AppWidgetProviderInfo definiuje najważniejsze cechy widżetu. Zdefiniuj obiekt AppWidgetProviderInfo w pliku zasobu XML, używając pojedynczego elementu <appwidget-provider>, i zapisz go w folderze res/xml/ projektu.

Przykład:

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

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 pozwala na umieszczanie widżetów o rozmiarze będącym wielokrotnością liczby całkowitej komórek siatki – na przykład 2 komórki w poziomie i 3 komórki w pionie.

Atrybuty rozmiaru widżetu umożliwiają określenie domyślnego rozmiaru widżetu oraz podanie dolnego i górnego limitu rozmiaru. W tym kontekście domyślny rozmiar widżetu to rozmiar, który widżet ma, gdy jest po raz pierwszy dodawany do ekranu głównego.

W tej tabeli opisano atrybuty <appwidget-provider> dotyczące rozmiaru widgeta:

Przykład

Aby zilustrować, jak atrybuty z poprzedniej tabeli wpływają na rozmiar widżetu, załóżmy następujące specyfikacje:

• Komórka siatki ma 30 dp szerokości i 50 dp wysokości.
• Oto specyfikacja atrybutu:

<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" />

Począwszy od Androida 12:

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

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

Android 11 i starsze:

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

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

Domyślna wysokość = Math.ceil(80 / 50) = 2

Domyślny rozmiar widżetu to 3 x 2. Rozmiar widżetu można zmienić na 2 x 1 lub na pełny ekran.

Dodatkowe atrybuty widżetu

W tej tabeli opisano atrybuty <appwidget-provider> dotyczące właściwości innych niż rozmiary widgetów.

Obsługa transmisji widżetów za pomocą klasy AppWidgetProvider

Klasa AppWidgetProvider obsługuje transmisje danych z widżetów i aktualizuje widżet w odpowiedzi na zdarzenia cyklu życia widżetu. W następnych sekcjach znajdziesz informacje o deklarowaniu AppWidgetProvider w pliku manifestu i jego implementowaniu.

Zadeklaruj widżet 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 widget. Komponent nie musi być eksportowany, chyba że inny proces musi być przesyłany do AppWidgetProvider, co zwykle nie jest konieczne.

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

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

• android:name: określa nazwę metadanych. Użyj atrybutu android.appwidget.provider, aby zidentyfikować dane jako opis AppWidgetProviderInfo.
• android:resource: określa lokalizację zasobu AppWidgetProviderInfo.

Implementacja klasy AppWidgetProvider

Klasa AppWidgetProvider rozszerza klasę BroadcastReceiver jako klasa ułatwiająca obsługę transmisji widżetów. Otrzymuje tylko transmisje zdarzeń, które są istotne dla widżetu, np. gdy widżet jest aktualizowany, usuwany, włączany lub wyłączany. Gdy występują te zdarzenia transmisji, są wywoływane te metody:AppWidgetProvider:

onUpdate()

Jest ona wywoływana w celu aktualizowania widżetu w określonych odstępach czasu zdefiniowanych przez atrybut updatePeriodMillis w elementach AppWidgetProviderInfo. Więcej informacji znajdziesz w tabeli z opisem dodatkowych atrybutów widżetów na tej stronie.

Ta metoda jest też wywoływana, gdy użytkownik dodaje widżet, aby wykonać niezbędną konfigurację, np. zdefiniować przetwarzacze zdarzeń dla obiektów View lub uruchomić zadania wczytywania danych do wyświetlenia w widżecie. Jeśli jednak deklarujesz aktywność konfiguracji bez flagi configuration_optional, ta metoda nie zostanie wywołana, gdy użytkownik doda widżet, ale będzie wywoływana podczas kolejnych aktualizacji. Po zakończeniu konfiguracji pierwszą aktualizację musi wykonać aktywność konfiguracji. Więcej informacji znajdziesz w artykule Włączanie możliwości konfigurowania widżetów aplikacji przez użytkowników.

Najważniejsza funkcja zwracana przez tę funkcję to onUpdate(). Więcej informacji znajdziesz na stronie Obsługa zdarzeń za pomocą klasy onUpdate().

onAppWidgetOptionsChanged()

Jest ona wywoływana przy pierwszym umieszczeniu widżetu i za każdym razem, gdy jego rozmiar zostanie zmieniony. Za pomocą tego wywołania zwrotnego możesz wyświetlać lub ukrywać treści na podstawie zakresów rozmiarów widżetu. Aby uzyskać zakresy rozmiarów (a od Androida 12 – listę możliwych rozmiarów, które może przyjąć instancja widżetu), wywołaj funkcję getAppWidgetOptions(), która zwraca obiekt Bundle zawierający:

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

onDeleted(Context, int[])

Jest ona wywoływana za każdym razem, gdy widżet zostanie usunięty z hosta widżetów.

onEnabled(Context)

Jest on wywoływany, gdy instancja widżetu jest tworzona po raz pierwszy. Jeśli na przykład użytkownik doda 2 wystąpienia Twojego widżetu, metoda ta zostanie wywołana tylko raz. Jeśli chcesz otworzyć nową bazę danych lub przeprowadzić inną konfigurację, która musi zostać wykonana tylko raz w przypadku wszystkich wystąpień widżetu, możesz to zrobić w tym miejscu.

onDisabled(Context)

Ta metoda jest wywoływana, gdy ostatnia instancja widżetu zostanie usunięta z hosta widżetu. Tutaj możesz uporządkować wszystkie działania wykonane w onEnabled(Context), na przykład usunąć tymczasową bazę danych.

onReceive(Context, Intent)

Jest on wywoływany w przypadku każdej transmisji i przed każdą z poprzednich metod wywołania zwrotnego. Zazwyczaj nie musisz stosować tej metody, ponieważ domyślna implementacja AppWidgetProvider filtruje wszystkie transmisje widżetu i w odpowiednich przypadkach wywołuje poprzednie metody.

Implementację klasy AppWidgetProvider musisz zadeklarować jako odbiornik transmisji za pomocą elementu <receiver> w komponencie AndroidManifest. Więcej informacji znajdziesz na stronie Deklarowanie widżetu w pliku manifestu.

Obsługa zdarzeń za pomocą klasy onUpdate()

Najważniejszym wywołaniem funkcji AppWidgetProvider jest onUpdate(), ponieważ jest ono wywoływane, gdy każdy widżet jest dodawany do hosta, chyba że używasz aktywności konfiguracji bez flagi configuration_optional. Jeśli widżet akceptuje jakiekolwiek zdarzenia interakcji z użytkownikiem, zarejestruj moduły obsługi zdarzeń w tym wywołaniu zwrotnym. Jeśli widżet nie tworzy tymczasowych plików ani baz danych i nie wykonuje innych zadań, które wymagają wyczyszczenia, onUpdate() może być jedyną metodą wywołania, którą musisz zdefiniować.

Jeśli na przykład chcesz utworzyć widżet z przyciskiem, który po kliknięciu uruchamia działanie, możesz użyć takiej implementacji funkcji 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 element AppWidgetProvider definiuje tylko metodę onUpdate(), za pomocą której tworzy element PendingIntent, który uruchamia element Activity, i dołącza go do przycisku widżetu za pomocą elementu setOnClickPendingIntent(int, PendingIntent). Zawiera on pętlę, która przechodzi po każdym wpisie w tablicy appWidgetIds, czyli tablicy identyfikatorów identyfikujących każdy widżet utworzony przez tego dostawcę. Jeśli użytkownik utworzy więcej niż 1 wystąpieni widżetu, wszystkie zostaną zaktualizowane jednocześnie. Jednak dla wszystkich wystąpień widżetu zarządzana jest tylko jedna updatePeriodMillis. Jeśli na przykład harmonogram aktualizacji jest ustawiony co 2 godziny, a po godzinie od dodania pierwszego widgeta dodasz drugi, oba zostaną zaktualizowane zgodnie z harmonogramem pierwszego, a drugi okres aktualizacji zostanie zignorowany. Oba te raporty są aktualizowane co 2 godziny, a nie co godzinę.

Więcej informacji znajdziesz w próbnej klasie ExampleAppWidgetProvider.java.

Odbieranie intencji dotyczących transmisji widżetów

AppWidgetProvider to klasa ułatwiająca. Jeśli chcesz otrzymywać transmisje widgeta bezpośrednio, możesz zaimplementować własne BroadcastReceiver lub zastąpić wywołanie zwrotne onReceive(Context,Intent). Intencje, na które musisz zwrócić uwagę, to:

• 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 formacie XML i zapisać go w katalogu res/layout/ projektu. Szczegółowe informacje znajdziesz w wytycznych dotyczących projektowania.

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

RemoteViews obsługuje też ViewStub, czyli niewidoczny, zerowy View, którego można użyć do leniwego napełniania zasobów układu w czasie działania.

Obsługa stanów

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

• CheckBox

• Switch

• RadioButton

Widżet nadal nie ma stanu. Aplikacja musi przechowywać stan i rejestrować zdarzenia zmiany stanu.

Przykładowy kod poniżej pokazuje, jak zaimplementować 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));

Podaj 2 projekty: jeden kierowany na urządzenia z Androidem 12 lub nowszym w folderze res/layout-v31, a drugi na poprzednią wersję Androida 11 lub starszą w domyślnym folderze res/layout.

Zastosowanie zaokrąglonych narożników

Android 12 wprowadza te parametry systemu, które umożliwiają ustawienie zaokrąglonych rogów widżetu:

• system_app_widget_background_radius: promień narożnika tła widżetu, który nigdy nie przekracza 28 dp.

• system_app_widget_inner_radius: promień zaokrąglenia rogów dowolnego widoku w widżecie. Jest to dokładnie o 8 dp mniejszy od promienia tła, aby zapewnić prawidłowe wyrównanie przy użyciu marginesu 8 dp.

Ten przykład pokazuje widżet, który używa wartości system_app_widget_background_radius dla rogu widżetu i system_app_widget_inner_radius dla widoków wewnątrz widżetu.

1 Róg widżetu.

2 Rzut oka na widok wewnątrz widżetu.

Ważne uwagi dotyczące zaokrąglonych rogów

• Producenci urządzeń i inne niż domyślne programy uruchamiania mogą zastąpić parametr system_app_widget_background_radius wartością mniejszą niż 28 dp. Wartość parametru system_app_widget_inner_radius jest zawsze mniejsza o 8 pikseli od wartości parametru system_app_widget_background_radius.
• Jeśli widżet nie używa @android:id/background ani nie definiuje tła, które przycina zawartość na podstawie obrysu, a wartość android:clipToOutline jest ustawiona na true, program uruchamiający automatycznie rozpoznaje tło i przycina widżet za pomocą prostokąta o zaokrąglonych rogach o wysokości do 16 dp. Zapoznaj się z artykułem Sprawdzanie zgodności widżetu z Androidem 12.

Aby zapewnić zgodność widżetu z wcześniejszymi wersjami systemu Android, zalecamy zdefiniowanie atrybutów niestandardowych i użycie niestandardowego motywu, aby zastąpić je w Androidzie 12. Przykładowe pliki 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" />