Tworzenie hosta widżetów

Ekran główny Androida, dostępny na większości urządzeń z Androidem, pozwala użytkownikowi umieszczać widżety aplikacji (lub widżety) 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, wdrażając AppWidgetHost. Większość aplikacji nie musi tego robić, ale jeśli tworzysz własne hostowanie, musisz znać zobowiązania umowne, na które host się zgadza.

Ta strona skupia się na obowiązkach związanych z wdrażaniem niestandardowego AppWidgetHost. Przykład implementacji AppWidgetHost znajdziesz w kodzie źródłowym ekranu głównego Androida LauncherAppWidgetHost.

Oto przegląd najważniejszych klas i pojęć związanych z wdrażaniem niestandardowego AppWidgetHost:

  • Host widżetu aplikacji: AppWidgetHost umożliwia interakcję z usługą AppWidget w przypadku aplikacji, które zawierają widżety w swoim interfejsie. AppWidgetHostmusi mieć identyfikator, który jest niepowtarzalny w ramach pakietu hosta. Ten identyfikator jest używany we wszystkich zastosowaniach hosta. Identyfikator jest zwykle zakodowaną na stałe wartością, 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. Więcej informacji znajdziesz w artykule bindAppWidgetIdIfAllowed(), a szczegółowe wskazówki – w następującej sekcji Połączanie widżetów. Host uzyskuje unikalny identyfikator za pomocą parametru allocateAppWidgetId(). 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, np. rozmiar i położenie widżetu, musi być zapisany w pakiecie hosta i powiązany z identyfikatorem widżetu aplikacji.

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

    • Domyślnie system tworzy AppWidgetHostView, ale host może utworzyć własną podklasę AppWidgetHostView, rozszerzając ją.
    • Począwszy od Androida 12 (poziom API 31) w AppWidgetHostView wprowadzono metody setColorResources() i resetColorResources() do obsługi dynamicznie przeciążonych kolorów. Gospodarz jest odpowiedzialny za udostępnianie kolorów w ramach tych metod.

  • Pakiet opcji: AppWidgetHost używa pakietu opcji do przekazywania informacji AppWidgetProvidero sposobie wyświetlania widżetu (np. lista 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 na podstawie sposobu i miejsca wyświetlania. Możesz użyć elementów updateAppWidgetOptions() i updateAppWidgetSize(), aby zmodyfikować pakiet widgeta. Obie te metody wywołują wywołanie AppWidgetProvider z parametrami onAppWidgetOptionsChanged().

Wiązanie widżetów

Gdy użytkownik dodaje widżet do hosta, odbywa się proces zwany wiązaniem. Powiązanie oznacza powiązanie identyfikatora konkretnego widżetu aplikacji z określonym hostem i określonym AppWidgetProvider.

Interfejsy API do wiązania umożliwiają też hostowi udostępnienie niestandardowego interfejsu użytkownika do wiązania. 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 aplikacji użytkownik musi wprost przyznać jej uprawnienia, aby mogła ona dodawać widżety do hosta. Aby sprawdzić, czy Twoja aplikacja ma uprawnienia do dodania widżetu, użyj metody bindAppWidgetIdIfAllowed(). Jeśli bindAppWidgetIdIfAllowed() zwraca false, aplikacja musi wyświetlić okno dialogowe z prośbą o przyznanie uprawnień: „Zezwól” w przypadku bieżącego dodania widżetu lub „Zawsze zezwól” w przypadku wszystkich przyszłych dodanych widżetów.

Ten fragment kodu pokazuje, jak wyświetlić okno dialogowe:

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 Zezwalanie użytkownikom na konfigurowanie widżetów aplikacji.

Obowiązki organizatora

Za pomocą metadanych AppWidgetProviderInfo możesz określić wiele ustawień konfiguracji widżetów. Te opcje konfiguracji, opisane szczegółowo w następnych sekcjach, możesz pobrać z obiektu AppWidgetProviderInfo powiązanego z dostawcą widżetu.

Niezależnie od wersji Androida, na którą kierujesz reklamy, wszyscy hostowie mają te same obowiązki:

  • Podczas dodawania widżetu przypisz mu identyfikator w sposób opisany wcześniej. 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ą. Host musi uruchomić aktywność konfiguracji widżetu, jeśli istnieje i nie jest oznaczona jako opcjonalna przez określenie flag configuration_optional i reconfigurable. 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 – od Androida 12, jeśli są określone wartości targetCellWidth i targetCellHeight, lub w przypadku pikseli na cal, jeśli są określone tylko wartości minWidth i minHeight. Zobacz Atrybuty rozmiaru widżetów.

    Upewnij się, że układ widżetu zawiera co najmniej tę liczbę pikseli na cal. Na przykład wielu gospodarzy wyrównuje ikony i widżety na siatce. W tym scenariuszu host domyślnie dodaje widżet, używając minimalnej liczby komórek, która spełnia ograniczenia minWidth i minHeight.

Oprócz wymagań wymienionych w poprzedniej sekcji niektóre wersje platformy wprowadzają funkcje, które nakładają nowe obowiązki na hosta.

Określ podejście na podstawie wersji Androida, na którą kierujesz aplikację

Android 12

Android 12 (poziom interfejsu API 31) zawiera dodatkowy pakiet List<SizeF> z listą możliwych rozmiarów w pikselach na cal, które może przyjąć instancja widżetu w pakiecie opcji. Podana liczba rozmiarów zależy od implementacji hosta. Gospodarze zwykle udostępniają 2 rozmiary na telefony (orientacja pionowa i pozioma) oraz 4 rozmiary na urządzenia składane.

Liczba różnych RemoteViews, które AppWidgetProvider może udostępnić RemoteViews, jest ograniczona do MAX_INIT_VIEW_COUNT (16). 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

  • Zapoznaj się z dokumentacją Glance.