Tworzenie hosta widżetów

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

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, wdrażając AppWidgetHost. Większość aplikacji tego nie wymaga, 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 zapewnia interakcję z usługą AppWidget w przypadku aplikacji, które umieszczają widżety w 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: każdemu wystąpieniu widżetu przypisany jest unikalny identyfikator w momencie powiązania. Więcej informacji znajdziesz w artykule bindAppWidgetIdIfAllowed(), a szczegółowe instrukcje – w sekcji Połączanie widżetów. Host uzyskuje unikalny identyfikator za pomocą allocateAppWidgetId(). Ten identyfikator pozostaje stały 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 ujęty, gdy musi zostać wyświetlony. 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, aby przekazać AppWidgetProviderinformacje o tym, jak widżet ma być wyświetlany (np. lista zakresów rozmiarów) oraz czy ma się on znajdować na ekranie blokady czy 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().

Widżety wiązania

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 bieżącego dodania 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 gospodarza

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ść konfiguracyjną 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. 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 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ą na hosta nowe obowiązki.

Określ swoje 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 – pionową i poziomą – 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.