Tworzenie hosta widżetów

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 aplikację zastępującą ekran główny lub podobną , możesz też umożliwić użytkownikowi umieszczanie widżetów, implementując AppWidgetHost. Większość aplikacji nie musi tego robić, ale jeśli tworzysz własny host, ważne jest, aby zrozumieć zobowiązania umowne, na które host wyraża zgodę.

Ta strona koncentruje się na obowiązkach związanych z implementacją niestandardowego AppWidgetHost. Konkretny przykład implementacji AppWidgetHost, znajdziesz w kodzie źródłowym ekranu głównego Androida LauncherAppWidgetHost.

Oto omówienie najważniejszych klas i pojęć związanych z implementacją niestandardowego AppWidgetHost:

  • Host widżetu aplikacji: AppWidgetHost zapewnia interakcję z usługą AppWidget w przypadku aplikacji, które umieszczają widżety w swoim interfejsie. AppWidgetHost musi mieć identyfikator, który jest unikalny w obrębie pakietu hosta. Ten identyfikator jest zachowywany we wszystkich przypadkach użycia hosta. Identyfikator jest zwykle wartością zakodowaną na stałe, 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 Powiązywanie widżetów oraz w dokumentacji bindAppWidgetIdIfAllowed(). Host uzyskuje unikalny identyfikator za pomocą allocateAppWidgetId(). 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ć zachowywane przez pakiet hostujący i powiązane z identyfikatorem widżetu aplikacji.

  • Widok hosta widżetu aplikacji: AppWidgetHostView to ramka w której umieszczany jest widżet, gdy trzeba go wyświetlić. Widżet jest powiązany z AppWidgetHostView za każdym razem, gdy host go rozszerza.

    • Domyślnie system tworzy AppWidgetHostView, ale host może utworzyć własną podklasę AppWidgetHostView, rozszerzając ją.
    • Od Androida 12 (poziom API 31) AppWidgetHostView wprowadza metodysetColorResources() i resetColorResources() do obsługi dynamicznie przeciążonych kolorów. Host jest odpowiedzialny za przekazywanie kolorów do tych metod.

  • Pakiet opcji: AppWidgetHost używa pakietu opcji do przekazywania informacji do AppWidgetProvider 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 do sposobu i miejsca jego wyświetlania. Do modyfikowania pakietu widżetu możesz używać updateAppWidgetOptions() i updateAppWidgetSize(). Obie te metody wywołują wywołanie zwrotne do AppWidgetProvider.onAppWidgetOptionsChanged()

Powiązywanie widżetów

Gdy użytkownik dodaje widżet do hosta, następuje proces zwany powiązaniem. Powiązanie polega na powiązaniu określonego identyfikatora widżetu aplikacji z konkretnym hostem i konkretnym AppWidgetProvider.

Interfejsy API powiązań umożliwiają też hostowi udostępnianie niestandardowego interfejsu do powiązywania. Aby 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 użytkownik musi wyraźnie przyznać aplikacji uprawnienie do dodawania widżetu do hosta. Aby sprawdzić, czy aplikacja ma uprawnienia do dodawania widżetu, użyj metody bindAppWidgetIdIfAllowed(). Jeśli bindAppWidgetIdIfAllowed() zwróci false, aplikacja musi wyświetlić okno z prośbą o przyznanie uprawnień: „Zezwól” na dodanie bieżącego widżetu lub „Zawsze zezwalaj” na wszystkie przyszłe dodatki 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 dodawany przez użytkownika widżet wymaga konfiguracji. Więcej informacji znajdziesz w artykule Umożliwianie użytkownikom konfigurowania widżetów aplikacji.

Obowiązki hosta

Za pomocą metadanych AppWidgetProviderInfo możesz określić szereg ustawień konfiguracji widżetów. Te opcje konfiguracji, które są szczegółowo opisane w kolejnych sekcjach, możesz pobrać z AppWidgetProviderInfo obiektu powiązanego z dostawcą widżetu.

Niezależnie od wersji Androida, na którą kierujesz aplikację, wszystkie hosty mają te same obowiązki:

  • Podczas dodawania widżetu przydziel identyfikator widżetu zgodnie z opisem podanym wcześniej. Gdy widżet zostanie usunięty z hosta, wywołaj deleteAppWidgetId() , aby cofnąć przydzielenie identyfikatora widżetu.

  • Podczas dodawania widżetu sprawdź, czy trzeba uruchomić aktywność konfiguracji. Zwykle host musi uruchomić aktywność konfiguracji widżetu, jeśli istnieje i nie jest oznaczona jako opcjonalna przez określenie flag configuration_optional i reconfigurable. Szczegółowe informacje znajdziesz w artykule Aktualizowanie widżetu z poziomu aktywności konfiguracji. Jest to konieczny krok w przypadku wielu widżetów, zanim będą mogły się wyświetlić.

  • Widżety określają domyślną szerokość i wysokość w metadanych AppWidgetProviderInfo. Te wartości są definiowane w komórkach – od Androida 12, jeśli określono targetCellWidth i targetCellHeight – lub w dp, jeśli określono tylko minWidth i minHeight. Zobacz Atrybuty rozmiaru widżetu.

    Upewnij się, że widżet jest ułożony w co najmniej tylu dp. Na przykład wiele hostów wyrównuje ikony i widżety w siatce. W takim przypadku domyślnie host dodaje widżet, używając minimalnej liczby komórek, które spełniają ograniczenia minWidth i minHeight.

Oprócz wymagań wymienionych w poprzedniej sekcji w określonych wersjach platformy wprowadzono funkcje, które nakładają na hosta nowe obowiązki.

Określanie podejścia na podstawie docelowej wersji Androida

Android 12

Android 12 (poziom API 31) zawiera dodatkowy element List<SizeF>, który zawiera listę możliwych rozmiarów w dp, jakie może przyjąć instancja widżetu w pakiecie opcji. Liczba podanych rozmiarów zależy od implementacji hosta. Hosty zwykle udostępniają 2 rozmiary w przypadku telefonów (orientacja pionowa i pozioma) oraz 4 rozmiary w przypadku urządzeń składanych.

Liczba różnych 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.

Android 12 wprowadza też atrybuty maxResizeWidth i maxResizeHeight w dp. 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 Glance dokumentacją referencyjną.