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ą ich wygląd na ekranie głównym użytkownika. Są one udostępniane za pomocą interfejsu API push, co oznacza, że aplikacja może udostępnić podgląd w dowolnym momencie cyklu życia bez otrzymywania wyraźnego żądania od hosta widżetu.

Ten przewodnik opisuje, jak udostępniać podglądy widżetów opartych na Glance. Jeśli Twój widżet jest zaimplementowany za pomocą RemoteViews, przeczytaj artykuł 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 a wygenerowany podgląd widżetu za pomocą GlanceAppWidget.providePreview na urządzeniach z Androidem 15 lub nowszym. W przypadku starszych wersji określ previewImage oraz jako rezerwę w Androidzie 15+, jeśli wygenerowany podgląd jest niedostępny.

Więcej informacji znajdziesz w artykule Wzbogacanie aplikacji 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 compileSdk wartość na 35 lub nowszą w pliku build.gradle modułu, aby mieć możliwość udostępniania RemoteViews w selektorze widżetów.

Aplikacje mogą następnie używać setWidgetPreview w GlanceAppWidgetManager. Aby zapobiec nadużyciom i ograniczyć problemy z kondycją systemu, setWidgetPreview to interfejs API z ograniczeniem liczby wywołań. Domyślny limit to około 2 wywołania 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ć zawartość kompozycyjną na potrzeby podglądu. Podobnie jak w przypadku provideGlance, załaduj dane aplikacji i przekaż je do kompozycyjnego elementu treści widżetu, aby podgląd wyświetlał dokładne dane. W przeciwieństwie do provideGlance jest to pojedyncza kompozycja bez rekompozycji ani efektów.

2. Aby wygenerować i opublikować podgląd, wywołaj GlanceAppWidgetManager.setWidgetPreviews.

System nie wywołuje zwrotu, aby udostępnić podglądy, 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 ma już dane, np. po zalogowaniu się użytkownika lub wstępnej konfiguracji.
• Możesz skonfigurować zadanie okresowe, aby aktualizować podglądy w wybranym odstępie czasu.

Rozwiązywanie problemów z wygenerowanymi podglądami

Częstym problemem jest to, że po wygenerowaniu podglądu obrazy, ikony lub inne elementy kompozycyjne mogą być nieobecne na obrazie podglądu w stosunku do rozmiaru widżetu. Ten rozmiar jest określany 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 w minimalnym rozmiarze widżetu. Innymi słowy, Android domyślnie ustawia previewSizeMode na SizeMode.Single. Do określania, które elementy kompozycyjne mają być rysowane, używa android:minHeight i android:minWidth w pliku XML informacji o dostawcy widżetu aplikacji.

Aby to naprawić, zastąp previewSizeMode w GlanceAppWidget i ustaw go na SizeMode.Responsive, podając zestaw wartości DpSize. Dzięki temu Android wie, jakie rozmiary układu ma renderować na potrzeby podglądu, 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 zgodnie z punktami przerwania widżetu. Aby zapewnić zgodność wsteczną, określ co najmniej 1 previewImage . 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ż Android 15 mogły wyświetlać podglądy widżetu lub jako rezerwę dla wygenerowanych podglądów w Androidzie 15 lub nowszym, określ atrybut previewImage.

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