Widżety aplikacji to miniaturowe widoki aplikacji, które można umieszczać w innych aplikacjach (np. na ekranie głównym) i okresowo aktualizować. W interfejsie użytkownika 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). Na rysunku 1 przedstawiono przykładowy widżet muzyczny:
Z tego dokumentu dowiesz się, jak opublikować widżet za pomocą dostawcy widżetów. Więcej
informacji 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:
AppWidgetProviderInfoobiekt- Opisuje metadane widżetu, takie
jak jego układ, częstotliwość aktualizacji i
AppWidgetProviderklasa.AppWidgetProviderInfojest zdefiniowany w XML, jak opisano w tym dokumencie. AppWidgetProviderzajęcia- Definiuje podstawowe metody, które umożliwiają programowe interakcje z widżetem. Dzięki niej otrzymujesz transmisje, gdy widżet jest aktualizowany, włączany, wyłączany lub usuwany. Deklarujesz w pliku manifestu a następnie implementujesz go zgodnie z opisem w tym dokumencie.
- Wyświetl układ
- Definiuje początkowy układ widżetu. Układ jest zdefiniowany w XML, jak opisano w tym dokumencie.
AppWidgetProvider
Na rysunku 2 pokazano, jak te komponenty pasują do ogólnego przepływu przetwarzania widżetów 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żetu, np. strefy czasowej w przypadku widżetu zegara.
- Od Androida 12 (API na poziomie 31) możesz podać konfigurację domyślną i pozwolić użytkownikom na ponowne skonfigurowanie widżetu. Więcej informacji znajdziesz w sekcjach Use the widget's default configuration i Enable users to reconfigure placed widgets.
- W Androidzie 11 (API na poziomie 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, 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 rozmiaru i częstotliwości 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, przeczytaj sekcję Deklarowanie pliku XML AppWidgetProviderInfo w dokumentacji Glance.
Używanie klasy AppWidgetProvider do obsługi komunikatów widżetów
Mechanizmy odbiornika transmisji platformy, filtry deklaracji manifestu i pętle zdarzeń cyklu życia są ujednolicone w ramach platformy. W przypadku tworzenia aplikacji w stylu Compose te transmisje są koordynowane za pomocą otoki GlanceAppWidgetReceiver.
Aby dowiedzieć się, jak zarejestrować odbiornik w pliku manifestu i zaimplementować zastąpienia cyklu życia zgodne z Hiltem, przeczytaj 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 XML i zapisać go w katalogu res/layout/ projektu. Szczegółowe informacje znajdziesz w wytycznych dotyczących projektowania.
Jeśli znasz
układy, tworzenie układu widżetu jest proste. Pamiętaj jednak, że układy widżetów są oparte na
RemoteViews, które nie obsługują wszystkich rodzajów układów ani widżetów widoków.
Nie możesz używać widoków niestandardowych ani podklas widoków obsługiwanych przez RemoteViews.
RemoteViews obsługuje też ViewStub, czyli niewidoczny element
View o zerowym rozmiarze, którego można użyć do leniwego rozszerzania zasobów układu 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 jest bezstanowy. Twoja aplikacja musi przechowywać stan i rejestrować się na potrzeby zdarzeń zmiany stanu.
Poniższy przykład kodu pokazuje, jak zaimplementować te komponenty.
Kotlin
// 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)
)
Java
// 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 układy: jeden kierowany na urządzenia z Androidem 12 lub
nowszym w res/layout-v31, a drugi kierowany na poprzednie
urządzenia z Androidem 11 lub starszym w domyślnym res/layout folderze.
Implementowanie zaokrąglonych narożników
Obliczanie zewnętrznego tła i wewnętrznych proporcjonalnych promieni jest standardowe i wspólne. W przypadku tworzenia aplikacji w stylu Compose można to ustawić dynamicznie w Kotlinie wraz z niestandardowymi zasobami motywu.
Aby zaimplementować promienie narożników lub skonfigurować style dynamiczne na starszych urządzeniach z Androidem, przeczytaj sekcję Implementowanie zaokrąglonych narożników w dokumentacji Glance.