Dodawanie wygenerowanych podglądów do selektora widżetów

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:

1. Zastąp funkcję GlanceAppWidget.providePreview, aby udostępnić treści do podglądu. Podobnie jak w provideGlance, 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 do provideGlance jest to pojedyncza kompozycja bez ponownej kompozycji ani efektów.

2. 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.