Tworzenie hosta widżetów

Ekran główny Androida, dostępny na większości urządzeń z Androidem, umożliwia umieszczanie przez użytkownika 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, 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ładowy kod źródłowy implementacji AppWidgetHost znajdziesz na ekranie głównym Androida: LauncherAppWidgetHost.

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

• Host widżetów aplikacji: AppWidgetHost zapewnia interakcję z usługą AppWidget w przypadku aplikacji, które umieszczają widżety w interfejsie użytkownika. 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: każdemu wystąpieniu widżetu przypisany jest unikalny identyfikator w momencie 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ą allocateAppWidgetId(). Ten identyfikator jest zachowany przez cały czas 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. Do modyfikowania pakietu widżetu możesz użyć elementów updateAppWidgetOptions() i updateAppWidgetSize(). 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 aplikacja musi wyraźnie uzyskać od użytkownika uprawnienia, aby mogła dodać widżet 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 dodania bieżącego widżetu lub „Zawsze zezwalaj” w przypadku wszystkich przyszłych dodanych widżetów.

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

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)

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 hosta

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. Gdy widżet zostanie usunięty z hosta, wywołaj funkcję deleteAppWidgetId(), aby zwolnić identyfikator widżetu.

• Podczas dodawania widżetu sprawdź, czy należy uruchomić aktywność konfiguracyjną. 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 sekcji Aktualizowanie widżetu z działania konfiguracji. Jest to konieczne, aby widżety mogły się wyświetlać.

• Widżety określają domyślną szerokość i wysokość w metadanych AppWidgetProviderInfo. Wartości te 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 rozmiarów widżetu.

  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. Liczba dostępnych 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>, dlatego nie podawaj więcej niż MAX_INIT_VIEW_COUNT rozmiarów.

Android 12 wprowadza też atrybuty maxResizeWidth i maxResizeHeight w jednostce dps. Zalecamy, aby widget, 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ą Glance.