Wygenerowane podglądy widżetów umożliwiają tworzenie dynamicznych, spersonalizowanych podglądów widżetów, które dokładnie odzwierciedlają sposób, w jaki będą one wyświetlane na ekranie głównym użytkownika. Są one udostępniane za pomocą interfejsu Push API, co oznacza, że aplikacja udostępnia podgląd w dowolnym momencie swojego cyklu życia bez otrzymywania wyraźnego żądania od hosta widżetu.
Z tego przewodnika dowiesz się, jak udostępniać podglądy widżetów opartych na widoku. Jeśli widżet jest zaimplementowany za pomocą RemoteViews, zapoznaj się z artykułem Dodawanie podglądów do selektora widżetów.
Aby ułatwić użytkownikom wybieranie widżetów w przypadku widżetów Glance, udostępnij wygenerowaną podglądową wersję widżetu za pomocą GlanceAppWidget.providePreview na urządzeniach z Androidem 15 i nowszym oraz określ previewImage w przypadku starszych wersji i jako wersję zapasową na Androidzie 15+, jeśli wygenerowany podgląd nie jest dostępny.
Więcej informacji znajdziesz w filmie Wzbogać aplikację o aktualizacje na żywo i widżety w YouTube.
Konfigurowanie aplikacji pod kątem wygenerowanych podglądów widżetów
Aby wyświetlać podglądy wygenerowanych widżetów na urządzeniu z Androidem 15 lub nowszym, najpierw ustaw wartość
compileSdk na 35 lub nowszą w pliku modułu build.gradle, aby mieć możliwość przekazywania wartości RemoteViews do selektora widżetów.
Aplikacje mogą wtedy używać elementu setWidgetPreview w GlanceAppWidgetManager. Aby zapobiegać nadużyciom i ograniczać problemy z działaniem systemu, interfejs setWidgetPreview ma ograniczone tempo wysyłania żądań. Domyślny limit to około 2 rozmowy na godzinę.
Generowanie zaktualizowanego podglądu za pomocą Jetpack Glance
W przypadku widżetów utworzonych za pomocą Jetpack Glance wykonaj te czynności:
Zastąp funkcję
GlanceAppWidget.providePreview, aby udostępnić treści do podglądu. Podobnie jak wprovideGlance, załaduj dane aplikacji i przekaż je do funkcji kompozycyjnej treści widżetu, aby w podglądzie wyświetlały się prawidłowe dane. W przeciwieństwie doprovideGlancejest to pojedyncza kompozycja bez ponownej kompozycji ani efektów.Wywołaj funkcję
GlanceAppWidgetManager.setWidgetPreviews, aby wygenerować i opublikować podgląd.
System nie wywołuje zwrotnego wywołania, aby udostępnić podgląd, więc aplikacja musi zdecydować, kiedy wywołać funkcję setWidgetPreviews. Strategia aktualizacji zależy od przypadku użycia widżetu:
- Jeśli widżet zawiera statyczne informacje lub jest skrótem, ustaw podgląd przy pierwszym uruchomieniu aplikacji.
- Podgląd możesz ustawić, gdy aplikacja będzie zawierać dane, np. po zalogowaniu się użytkownika lub po początkowej konfiguracji.
- Możesz skonfigurować okresowe zadanie, aby aktualizować podglądy z wybraną częstotliwością.
Rozwiązywanie problemów z wygenerowanymi podglądami
Częstym problemem jest to, że po wygenerowaniu podglądu na obrazie podglądu mogą nie być widoczne obrazy, ikony ani inne komponenty, w porównaniu z rozmiarem widżetu. Rozmiar elementu jest określony przez targetCellWidth i targetCellHeight (jeśli są podane) lub przez minWidth i minHeight w pliku informacji o dostawcy widżetu aplikacji.
Dzieje się tak, ponieważ Android domyślnie renderuje tylko elementy kompozycyjne widoczne przy minimalnym rozmiarze widżetu. Innymi słowy, Android domyślnie ustawia wartość previewSizeMode na SizeMode.Single. Używa android:minHeight i android:minWidth
w pliku XML z informacjami o widżecie aplikacji, aby określić, które komponenty mają być rysowane.
Aby to naprawić, zastąp wartość previewSizeMode w GlanceAppWidget i ustaw ją na SizeMode.Responsive, podając zestaw wartości DpSize. Dzięki temu Android będzie wiedzieć, jakie rozmiary układu ma renderować w podglądzie, co zapewni prawidłowe wyświetlanie wszystkich elementów.
Optymalizuj pod kątem konkretnych formatów. Podaj 1 lub 2 rozmiary, zaczynając od minimalnego i uwzględniając punkty przerwania widżetu. Określ co najmniej 1 element previewImage w celu zapewnienia zgodności wstecznej. Odpowiednie minimalne wartości DP dla różnych rozmiarów siatki znajdziesz w wytycznych dotyczących projektowania widżetów.
Zgodność wsteczna z podglądami widżetów
Aby selektory widżetów na urządzeniach z Androidem w wersji starszej niż 15 wyświetlały podglądy widżetu lub jako rezerwę dla wygenerowanych podglądów na Androidzie 15 lub nowszym, określ atrybut previewImage.
Jeśli zmienisz wygląd widżetu, zaktualizuj obraz podglądu.