Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Tworzenie widżetu podstawowego

Widżety aplikacji to miniaturowe widoki aplikacji, które można umieszczać w innych aplikacjach, np. na ekranie głównym, i które są okresowo aktualizowane. W interfejsie te widoki są nazywane widżetami. Możesz opublikować widżet za pomocą dostawcy widżetów aplikacji (lub dostawcy widżetów). Komponent aplikacji, który zawiera inne widżety, nazywa się hostem widżetów aplikacji (lub hostem widżetów). Rysunek 1 przedstawia przykładowy widżet muzyczny:

**Rysunek 1.** Przykład widżetu muzycznego.

Ten dokument opisuje, jak opublikować widżet za pomocą dostawcy widżetów. Szczegółowe informacje o tworzeniu własnego elementu AppWidgetHost do hostowania widżetów aplikacji znajdziesz w artykule Tworzenie hosta widżetów.

Informacje o projektowaniu widżetu znajdziesz w artykule Omówienie widżetów aplikacji.

Komponenty widżetu

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

Obiekt AppWidgetProviderInfo: Opisuje metadane widżetu, takie jak układ widżetu, częstotliwość aktualizacji i klasa AppWidgetProvider. AppWidgetProviderInfo jest zdefiniowany w XML, jak opisano w tym dokumencie.
Klasa AppWidgetProvider: Definiuje podstawowe metody, które umożliwiają programową interakcję z widżetem. Dzięki temu otrzymujesz transmisje, gdy widżet jest aktualizowany, włączany, wyłączany lub usuwany. Zadeklaruj AppWidgetProvider w pliku manifestu, a następnie wdroż 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 pasują do ogólnego procesu przetwarzania widżetu aplikacji.

Proces przetwarzania widżetu aplikacji — **Rysunek 2.** Schemat przetwarzania widżetu aplikacji.

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

Od Androida 12 (poziom interfejsu API 31) możesz podać domyślną konfigurację i pozwolić użytkownikom na późniejsze ponowne skonfigurowanie widżetu. Więcej informacji znajdziesz w sekcjach Używanie domyślnej konfiguracji widżetu i Umożliwianie użytkownikom ponownego konfigurowania umieszczonych widżetów.
W systemie Android 11 (poziom interfejsu API 30) lub starszym ta aktywność jest uruchamiana za każdym razem, gdy użytkownik dodaje widżet do ekranu głównego.

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

Deklarowanie pliku XML AppWidgetProviderInfo

Definiowanie ustawień metadanych (takich jak domyślne rozmiary komórek, ograniczenia zmiany rozmiaru i częstotliwość aktualizacji) jest dokładnie takie samo w przypadku tradycyjnych widoków i widżetów opartych na Glance.

Aby dowiedzieć się, jak zdefiniować i skonfigurować plik XML metadanych, zapoznaj się z sekcją Deklarowanie pliku XML AppWidgetProviderInfo w dokumentacji Glance.

Mechanizmy odbiornika komunikatów, filtry deklaracji manifestu i pętle zdarzeń cyklu życia są ujednolicone na platformie. W przypadku programowania z wykorzystaniem Compose te komunikaty są koordynowane za pomocą opakowania GlanceAppWidgetReceiver.

Aby dowiedzieć się, jak zarejestrować odbiornik w pliku manifestu i wdrożyć zastąpienia cyklu życia zgodne z Hilt, zapoznaj się z sekcją Używanie klasy AppWidgetProvider do obsługi transmisji w dokumentacji Glance.

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 we wskazówkach 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 RemoteViews, który nie obsługuje wszystkich rodzajów układów ani widżetów widoku. Nie możesz używać widoków niestandardowych ani podklas widoków obsługiwanych przez RemoteViews.

RemoteViews obsługuje też ViewStub, czyli niewidoczny, mający zerowy rozmiar element View, którego można używać do leniwego rozszerzania zasobów layoutu w czasie działania.

Obsługa zachowania stanowego

Android 12 dodaje obsługę zachowania stanowego za pomocą tych istniejących komponentów:

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

Przykład widżetu listy zakupów pokazującego zachowanie zależne od stanu — **Rysunek 3.** Przykład zachowania stanowego.

Poniższy przykładowy kod 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)
)AppWidget.kt

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

Zaimplementuj zaokrąglone rogi

Obliczanie zewnętrznego tła i wewnętrznych promieni proporcjonalnych jest standardowe i wspólne. W przypadku programowania z wykorzystaniem Compose można to ustawić dynamicznie w języku Kotlin wraz z zasobami motywu niestandardowego.

Aby wdrożyć promienie narożników lub skonfigurować style dynamiczne na starszych urządzeniach z Androidem, zapoznaj się z sekcją Wdrażanie zaokrąglonych rogów w dokumentacji Glance.