Ekran główny Androida, dostępny na większości urządzeń z Androidem, umożliwia użytkownikowi umieszczanie widżetów aplikacji (lub widżetów) w celu szybkiego dostępu do treści. Jeśli tworzysz zamiennik ekranu głównego lub podobną aplikację, możesz też umożliwić użytkownikowi osadzanie widżetów, implementując AppWidgetHost
. Nie jest to wymagane w przypadku większości aplikacji, ale jeśli tworzysz własnego hosta, musisz znać zobowiązania umowne, na które host wyraża dorozumianą zgodę.
Ta strona zawiera informacje o obowiązkach związanych z wdrażaniem niestandardowegoAppWidgetHost
. Konkretny przykład implementacji AppWidgetHost
znajdziesz w kodzie źródłowym ekranu głównego AndroidaLauncherAppWidgetHost
.
Oto przegląd najważniejszych klas i pojęć związanych z wdrażaniem niestandardowego AppWidgetHost
:
Host widżetu aplikacji:
AppWidgetHost
zapewnia interakcję z usługą AppWidget w przypadku aplikacji, które osadzają widżety w swoim interfejsie.AppWidgetHost
musi mieć identyfikator, który jest unikalny w ramach własnego pakietu hosta. Ten identyfikator jest zachowywany we wszystkich przypadkach użycia hosta. Jest to zwykle zakodowana na stałe wartość, którą przypisujesz w aplikacji.Identyfikator widżetu aplikacji: każda instancja widżetu otrzymuje unikalny identyfikator w momencie powiązania. Więcej informacji znajdziesz w sekcji
bindAppWidgetIdIfAllowed()
i w następnej sekcji Powiązywanie widżetów. Host uzyskuje unikalny identyfikator za pomocą funkcjiallocateAppWidgetId()
. Ten identyfikator jest zachowywany przez cały okres istnienia widżetu, dopóki nie zostanie on usunięty z hosta. Wszelkie stany specyficzne dla hosta, takie jak rozmiar i lokalizacja widżetu, muszą być przechowywane przez pakiet hosta i powiązane z identyfikatorem widżetu aplikacji.Widok hosta widżetu aplikacji: wyobraź sobie
AppWidgetHostView
jako ramkę , w której widżet jest umieszczany, gdy trzeba go wyświetlić. Widżet jest powiązany zAppWidgetHostView
za każdym razem, gdy jest on rozwijany przez hosta.- Domyślnie system tworzy obiekt
AppWidgetHostView
, ale host może utworzyć własną podklasęAppWidgetHostView
, rozszerzając ją. - Od Androida 12 (API na poziomie 31) klasa
AppWidgetHostView
udostępnia metodysetColorResources()
iresetColorResources()
do obsługi dynamicznie przeciążonych kolorów. Za przekazywanie kolorów do tych metod odpowiada host.
- Domyślnie system tworzy obiekt
Pakiet opcji:
AppWidgetHost
używa pakietu opcji do przekazywania informacji doAppWidgetProvider
o sposobie wyświetlania widżetu, np. listy zakresów rozmiarów, oraz o tym, czy widżet znajduje się na ekranie blokady czy na ekranie głównym. Dzięki tym informacjomAppWidgetProvider
może dostosowywać zawartość i wygląd widżetu do sposobu i miejsca jego wyświetlania. Do modyfikowania pakietu widżetu możesz używać znakówupdateAppWidgetOptions()
iupdateAppWidgetSize()
. Obie te metody wywołują wywołanie zwrotneonAppWidgetOptionsChanged()
doAppWidgetProvider
.
Powiązywanie widżetów
Gdy użytkownik doda widżet do hosta, następuje proces zwany powiązaniem. Powiązanie oznacza przypisanie konkretnego identyfikatora widżetu aplikacji do konkretnego hosta i konkretnego AppWidgetProvider
.
Interfejsy API powiązań umożliwiają też hostowi udostępnianie niestandardowego interfejsu do powiązywania. Aby skorzystać z tego procesu, aplikacja musi zadeklarować uprawnienie
BIND_APPWIDGET
w pliku manifestu hosta:
<uses-permission android:name="android.permission.BIND_APPWIDGET" />
To jednak dopiero pierwszy krok. W czasie działania użytkownik musi wyraźnie przyznać aplikacji uprawnienia, aby mogła ona dodać widżet do hosta. Aby sprawdzić, czy aplikacja ma uprawnienia do dodawania widżetu, użyj metody bindAppWidgetIdIfAllowed()
. Jeśli funkcja bindAppWidgetIdIfAllowed()
zwróci wartość false
, aplikacja musi wyświetlić okno z prośbą o przyznanie uprawnień: „Zezwól” w przypadku bieżącego dodawania widżetu lub „Zawsze zezwalaj” w przypadku wszystkich przyszłych widżetów.
Ten fragment kodu pokazuje, jak wyświetlić okno:
Kotlin
val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply { putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName) // This is the options bundle described in the preceding section. putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options) } startActivityForResult(intent, REQUEST_BIND_APPWIDGET)
Java
Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND); intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName); // This is the options bundle described in the preceding section. intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options); startActivityForResult(intent, REQUEST_BIND_APPWIDGET);
Host musi sprawdzić, czy widżet dodany przez użytkownika wymaga konfiguracji. Więcej informacji znajdziesz w artykule Umożliwianie użytkownikom konfigurowania widżetów aplikacji.
Obowiązki gospodarza
Za pomocą AppWidgetProviderInfo
metadanych możesz określić wiele ustawień konfiguracji widżetów.
Te opcje konfiguracji, które są szczegółowo omówione w kolejnych sekcjach, możesz pobrać z obiektu AppWidgetProviderInfo
powiązanego z dostawcą widżetu.
Niezależnie od wersji Androida, na którą kierujesz reklamy, wszystkie hosty mają następujące obowiązki:
Podczas dodawania widżetu przypisz mu identyfikator zgodnie z opisem powyżej. Gdy widżet zostanie usunięty z hosta, wywołaj funkcję
deleteAppWidgetId()
, aby zwolnić identyfikator widżetu.Podczas dodawania widżetu sprawdź, czy trzeba uruchomić aktywność konfiguracji. Zwykle host musi uruchomić aktywność związaną z konfiguracją widżetu, jeśli istnieje i nie jest oznaczona jako opcjonalna przez określenie flag
configuration_optional
ireconfigurable
. Szczegółowe informacje znajdziesz w artykule Aktualizowanie widżetu z poziomu działania konfiguracji. Jest to konieczne w przypadku wielu widżetów, aby mogły się wyświetlać.Widżety określają domyślną szerokość i wysokość w
AppWidgetProviderInfo
metadanych. Wartości te są zdefiniowane w komórkach – od Androida 12, jeśli podano wartościtargetCellWidth
itargetCellHeight
– lub w jednostkach dp, jeśli podano tylko wartościminWidth
iminHeight
. Zobacz atrybuty rozmiaru widżetu.Upewnij się, że widżet ma co najmniej tyle pikseli niezależnych od gęstości. Na przykład wielu hostów umieszcza ikony i widżety w siatce. W tym scenariuszu host domyślnie dodaje widżet, używając minimalnej liczby komórek, które spełniają ograniczenia
minWidth
iminHeight
.
Oprócz wymagań wymienionych w poprzedniej sekcji poszczególne wersje platformy wprowadzają funkcje, które nakładają na hosta nowe obowiązki.
Określ podejście na podstawie wersji Androida, na którą kierujesz reklamy
Android 12
Android 12 (poziom API 31) zawiera dodatkowy List<SizeF>
, który zawiera listę możliwych rozmiarów w jednostkach dp, jakie może przyjąć instancja widżetu w pakiecie opcji.
Liczba podanych rozmiarów zależy od implementacji hosta. Zazwyczaj udostępniają 2 rozmiary reklam na telefony – w orientacji pionowej i poziomej – oraz 4 rozmiary na urządzenia składane.
Liczba różnych MAX_INIT_VIEW_COUNT
RemoteViews
, które AppWidgetProvider
może udostępnić RemoteViews
, jest ograniczona do MAX_INIT_VIEW_COUNT
(16).
Ponieważ obiekty AppWidgetProvider
mapują obiekt RemoteViews
na każdy rozmiar w List<SizeF>
, nie podawaj więcej niż MAX_INIT_VIEW_COUNT
rozmiarów.
W Androidzie 12 wprowadziliśmy też atrybuty maxResizeWidth
i maxResizeHeight
w dps. Zalecamy, aby widżet, który używa co najmniej jednego z tych atrybutów, nie przekraczał rozmiaru określonego przez te atrybuty.
Dodatkowe materiały
- Zapoznaj się z dokumentacją referencyjną
Glance
.