Wygenerowane podglądy widżetów umożliwiają tworzenie dynamicznych, spersonalizowanych podglądów widżetów, które dokładnie odzwierciedlają ich wygląd na ekranie głównym użytkownika. Są one udostępniane przez interfejs API push, co oznacza, że aplikacja udostępnia podgląd w dowolnym momencie 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 Glance. Jeśli widżet jest zaimplementowany za pomocą RemoteViews, zapoznaj się z artykułem Dodawanie podglądów do selektora widżetów.
Aby ulepszyć działanie selektora widżetów Glance w aplikacji, podaj wygenerowany podgląd widżetu za pomocą GlanceAppWidget.providePreview na urządzeniach z Androidem 15 lub nowszym i określ previewImage w przypadku starszych wersji oraz jako kreację zastępczą na Androidzie 15 lub nowszym, jeśli wygenerowany podgląd jest niedostępny.
Więcej informacji znajdziesz w filmie Enrich your app with aktualizacje na żywo and widżety na YouTube.
Konfigurowanie aplikacji pod kątem generowanych podglądów widżetów
Aby wyświetlać wygenerowane podglądy widżetów na urządzeniu z Androidem 15 lub nowszym, najpierw ustaw wartość compileSdk na 35 lub wyższą w pliku modułu build.gradle, aby włączyć wygenerowane podglądy w selektorze widżetów.
Aplikacje mogą następnie używać setWidgetPreview w GlanceAppWidgetManager. Aby zapobiegać nadużyciom i ograniczyć problemy ze stanem systemu, interfejs setWidgetPreview ma ograniczoną liczbę żądań. Domyślny limit to około 2 połączenia na godzinę.
Generowanie zaktualizowanego podglądu za pomocą Jetpack Glance
W przypadku widżetów utworzonych za pomocą Jetpack Glance:
Zastąp funkcję
GlanceAppWidget.providePreview, aby udostępnić zawartość funkcji kompozycyjnej na potrzeby podglądu. Podobnie jak wprovideGlance, wczytaj dane aplikacji i przekaż je do funkcji kompozycyjnej treści widżetu, aby podgląd wyświetlał dokładne dane. W przeciwieństwie doprovideGlancejest to pojedyncza kompozycja bez rekompozycji i efektów.Wywołaj
GlanceAppWidgetManager.setWidgetPreviews, aby wygenerować i opublikować podgląd.
System nie udostępnia wywołania zwrotnego do wyświetlania podglądów, więc aplikacja musi zdecydować, kiedy wywołać setWidgetPreviews. Strategia aktualizacji zależy od przypadku użycia widżetu:
- Jeśli widżet zawiera informacje statyczne lub jest skrótem, ustaw podgląd przy pierwszym uruchomieniu aplikacji.
- Podgląd możesz ustawić, gdy aplikacja będzie miała dane, np. po zalogowaniu się użytkownika lub po wstępnej 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 może brakować obrazów, ikon lub innych elementów kompozycyjnych w porównaniu z rozmiarem widżetu. Rozmiar upuszczanego elementu jest określany przez atrybuty targetCellWidth i targetCellHeight (jeśli są podane) lub 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 previewSizeMode na SizeMode.Single. Używa on android:minHeight i android:minWidth w pliku XML z informacjami o dostawcy widżetu aplikacji, aby określić, które elementy kompozycyjne mają zostać narysowane.
Aby rozwiązać ten problem, zastąp previewSizeMode w GlanceAppWidget i ustaw na SizeMode.Responsive, podając zestaw wartości DpSize. Dzięki temu Android będzie znał wszystkie rozmiary układu, które musi wyrenderować na potrzeby podglądu, 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 postępując zgodnie z punktami przerwania widżetu. Określ co najmniej 1 previewImage, aby obsługiwać starsze wersje Androida. Odpowiednie minimalne wartości DP dla różnych rozmiarów siatki znajdziesz we wskazówkach dotyczących projektowania widżetów.
Obsługa starszych wersji Androida
Aby wyświetlać podglądy widżetów na urządzeniach z Androidem 14 lub starszym albo gdy wygenerowany podgląd nie jest dostępny na Androidzie 15 lub nowszym, określ atrybut previewImage.
Jeśli zmienisz wygląd widżetu, zaktualizuj obraz podglądu.