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 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 poprawić wygodę korzystania z selektora widżetów w przypadku widżetów Glance, udostępnij wygenerowaną 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 rezerwę na Androidzie 15 lub nowszym, jeśli wygenerowany podgląd nie jest dostępny.

Więcej informacji znajdziesz w filmie Enrich your app with live updates and widgets (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ć 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ą wtedy używać elementu setWidgetPreview w GlanceAppWidgetManager. Aby zapobiegać nadużyciom i ograniczać problemy z działaniem systemu, interfejs setWidgetPreview ma ograniczenie liczby żą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 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 już 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 w porównaniu z rozmiarem widżetu na obrazie podglądu mogą nie być widoczne obrazy, ikony lub inne komponenty. Rozmiar elementu do przeciągania 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 wie, jakie rozmiary układu musi renderować w podglądzie, co zapewnia 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 , aby obsługiwać starsze wersje Androida. Odpowiednie minimalne wartości DP dla różnych rozmiarów siatki znajdziesz w wytycznych dotyczących projektowania widżetów.

Obsługa starszych wersji Androida

Aby wyświetlać podgląd widżetów na urządzeniach z Androidem 14 i starszym lub gdy wygenerowany podgląd nie jest dostępny na urządzeniach z Androidem 15 i nowszym, określ atrybut previewImage.

Jeśli zmienisz wygląd widżetu, zaktualizuj obraz podglądu.