Ekran główny Androida, dostępny na większości urządzeń z Androidem, pozwala użytkownikowi umieścić widżety aplikacji (lub widżety), aby mieć szybki dostęp do treści. Jeśli chcesz wymienić ekran główny lub podobną aplikację, możesz też zezwolić użytkownikowi na umieszczanie widżetów, implementując AppWidgetHost
. Nie jest to wymagane w przypadku większości aplikacji, ale jeśli tworzysz własny host, ważne jest zrozumienie zobowiązań umownych, na które host domyślnie wyraża zgodę.
Na tej stronie omawiamy obowiązki związane z implementacją niestandardowego elementu AppWidgetHost
. Konkretny przykład implementacji obiektu AppWidgetHost
znajdziesz w kodzie źródłowym ekranu głównego Androida LauncherAppWidgetHost
.
Oto przegląd najważniejszych klas i koncepcji związanych z implementacją niestandardowego elementu AppWidgetHost
:
Host widżetu aplikacji:
AppWidgetHost
umożliwia interakcję z usługą AppWidget w przypadku aplikacji, które zawierają widżety w swoim interfejsie.AppWidgetHost
musi mieć unikalny identyfikator w pakiecie hosta. Identyfikator ten jest widoczny we wszystkich przypadkach użycia hosta. Jest to zwykle zakodowana na stałe wartość, którą przypisujesz w aplikacji.Identyfikator widżetu aplikacji: do każdego wystąpienia widżetu przypisywany jest unikalny identyfikator w czasie tworzenia powiązania.
bindAppWidgetIdIfAllowed()
oraz więcej szczegółów znajdziesz w poniższej sekcji Wiązanie widżetów. Host uzyskuje unikalny identyfikator za pomocą parametruallocateAppWidgetId()
. Ten identyfikator będzie widoczny przez cały okres istnienia widżetu, dopóki nie zostanie usunięty z hosta. Każdy stan specyficzny dla hosta – taki jak rozmiar i lokalizacja widżetu – musi być zachowany przez pakiet hostingowy i powiązany z identyfikatorem widżetu aplikacji.Widok hosta widżetu aplikacji: traktuj
AppWidgetHostView
jako ramkę, w którą zawija się widżet, gdy chce się wyświetlić. Widżet jest powiązany z funkcjąAppWidgetHostView
za każdym razem, gdy hostuje widżet.- Domyślnie system tworzy klasę
AppWidgetHostView
, ale host może utworzyć własną podklasę klasyAppWidgetHostView
przez rozszerzenie. - Począwszy od Androida 12 (poziom interfejsu API 31)
AppWidgetHostView
wprowadza metodysetColorResources()
iresetColorResources()
do obsługi dynamicznie przeciążonych kolorów. To gospodarz jest odpowiedzialny za dodanie kolorów do tych metod.
- Domyślnie system tworzy klasę
Pakiet opcji:
AppWidgetHost
używa tego pakietu, aby przekazywać doAppWidgetProvider
informacje o sposobie wyświetlania widżetu – np. o liście zakresów rozmiarów – oraz o tym, czy widżet znajduje się na ekranie blokady czy na ekranie głównym. Te informacje pozwalająAppWidgetProvider
dostosować zawartość i wygląd widżetu w zależności od sposobu i miejsca jego wyświetlania. Aby zmodyfikować pakiet widżetów, możesz użyćupdateAppWidgetOptions()
iupdateAppWidgetSize()
. Obie te metody wywołują wywołanie zwrotneonAppWidgetOptionsChanged()
doAppWidgetProvider
.
Wiązania widżetów
Gdy użytkownik dodaje widżet do hosta, odbywa się proces nazywany powiązaniem. Powiązanie odnosi się do powiązania konkretnego identyfikatora widżetu aplikacji z konkretnym hostem i konkretnym obiektem AppWidgetProvider
.
Interfejsy API powiązań umożliwiają też hostowi dostarczanie niestandardowych interfejsów użytkownika do powiązań. Aby można było korzystać 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 aplikacji użytkownik musi wprost przyznać jej uprawnienia, aby mogła ona dodawać widżety do hosta. Aby sprawdzić, czy aplikacja ma uprawnienia do dodawania widżetu, użyj metody bindAppWidgetIdIfAllowed()
. Jeśli bindAppWidgetIdIfAllowed()
zwraca wartość false
, aplikacja musi wyświetlić okno z prośbą o przyznanie uprawnień: „allow” (zezwól) w przypadku bieżącego dodawania widżetów lub „always allow” (Zawsze zezwalaj), aby uwzględnić wszystkie przyszłe dodawane widżety.
Ten fragment kodu pokazuje na przykład, jak wyświetlić to 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 organizatora
Za pomocą metadanych AppWidgetProviderInfo
możesz określić różne ustawienia konfiguracji widżetów.
Te opcje konfiguracji, które zostały szczegółowo omówione w poniższych sekcjach, możesz pobrać z obiektu AppWidgetProviderInfo
powiązanego z dostawcą widżetów.
Niezależnie od docelowej wersji Androida wszystkie hosty są odpowiedzialne za:
Podczas dodawania widżetu przydziel identyfikator widżetu w sposób opisany powyżej. Po usunięciu widżetu z hosta wywołaj
deleteAppWidgetId()
, by zwolnić jego identyfikatory.Podczas dodawania widżetu sprawdź, czy trzeba uruchomić aktywność związaną z konfiguracją. Zwykle host musi uruchomić aktywność konfiguracyjną widżetu, jeśli istnieje i nie jest oznaczony jako opcjonalny, używając flag
configuration_optional
ireconfigurable
. Więcej informacji znajdziesz w sekcji Aktualizowanie widżetu na podstawie aktywności konfiguracji. Jest to konieczne, zanim widżety zaczną się wyświetlać.Widżety określają domyślną szerokość i wysokość w metadanych
AppWidgetProviderInfo
. Te wartości są zdefiniowane w komórkach – począwszy od Androida 12, jeśli określono właściwościtargetCellWidth
itargetCellHeight
, lub dps, jeśli określono tylkominWidth
iminHeight
. Zobacz Atrybuty rozmiaru widżetów.Dopilnuj, aby układ widżetu miał co najmniej taką liczbę dps. Na przykład wiele hostów wyrównuje ikony i widżety w siatce. W tym scenariuszu domyślnie host dodaje widżet z użyciem minimalnej liczby komórek zgodnych z ograniczeniami
minWidth
iminHeight
.
Oprócz wymagań wymienionych w poprzedniej sekcji niektóre wersje platform wprowadzają funkcje, które nakładają nowe obowiązki na hosta.
Określ podejście na podstawie docelowej wersji Androida
Android 12
Android 12 (poziom interfejsu API 31) obejmuje dodatkowy element List<SizeF>
zawierający listę możliwych rozmiarów w dps, które wystąpienie widżetu może przyjmować w pakiecie opcji.
Podana liczba rozmiarów zależy od implementacji hosta. Gospodarze zwykle udostępniają 2 rozmiary dla telefonów (pionowe i poziome) oraz 4 rozmiary dla urządzeń składanych.
Obowiązuje limit MAX_INIT_VIEW_COUNT
(16) liczby różnych elementów RemoteViews
, które AppWidgetProvider
może przekazać do RemoteViews
.
Obiekty AppWidgetProvider
mapują obiekt RemoteViews
na każdy rozmiar w List<SizeF>
, więc nie podawaj więcej niż MAX_INIT_VIEW_COUNT
rozmiarów.
Android 12 wprowadza też atrybuty maxResizeWidth
i maxResizeHeight
w dps. Zalecamy, aby rozmiar widżetu, który korzysta z co najmniej jednego z tych atrybutów, nie przekraczał rozmiaru określonego w atrybutach.
Dodatkowe materiały
- Więcej informacji znajdziesz w dokumentacji referencyjnej
Glance
.