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 zamiennik ekranu głównego lub podobną aplikację, możesz też umożliwić użytkownikowi osadzanie widżetów, implementując AppWidgetHost. Nie jest to wymagane w przypadku większości aplikacji, ale jeśli tworzysz własnego hosta, musisz znać zobowiązania umowne, na które host wyraża dorozumianą zgodę.

Ta strona zawiera informacje o obowiązkach związanych z wdrażaniem niestandardowegoAppWidgetHost. Konkretny przykład implementacji AppWidgetHost znajdziesz w kodzie źródłowym ekranu głównego AndroidaLauncherAppWidgetHost.

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 osadzają widżety w swoim interfejsie. AppWidgetHost musi mieć identyfikator, który jest unikalny w ramach własnego pakietu hosta. Ten identyfikator jest zachowywany we wszystkich przypadkach użycia hosta. Jest to zwykle zakodowana na stałe wartość, 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 bindAppWidgetIdIfAllowed() i w następnej sekcji Powiązywanie widżetów. Host uzyskuje unikalny identyfikator za pomocą funkcji 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ć przechowywane przez pakiet hosta i powiązane z identyfikatorem widżetu aplikacji.

• Widok hosta widżetu aplikacji: wyobraź sobie AppWidgetHostView jako ramkę , w której widżet jest umieszczany, gdy trzeba go wyświetlić. Widżet jest powiązany z AppWidgetHostView za każdym razem, gdy jest on rozwijany przez hosta.

  • Domyślnie system tworzy obiekt AppWidgetHostView, ale host może utworzyć własną podklasę AppWidgetHostView, rozszerzając ją.
  • Od Androida 12 (API na poziomie 31) klasa AppWidgetHostView udostępnia metody setColorResources() i resetColorResources() do obsługi dynamicznie przeciążonych kolorów. Za przekazywanie kolorów do tych metod odpowiada host.

• Pakiet opcji: AppWidgetHost używa pakietu opcji do przekazywania informacji do AppWidgetProvider o sposobie wyświetlania widżetu, np. listy zakresów rozmiarów, oraz o tym, czy widżet znajduje się na ekranie blokady czy na ekranie głównym. Dzięki tym informacjom AppWidgetProvidermoże dostosowywać zawartość i wygląd widżetu do sposobu i miejsca jego wyświetlania. Do modyfikowania pakietu widżetu możesz używać znaków updateAppWidgetOptions() i updateAppWidgetSize(). Obie te metody wywołują wywołanie zwrotne onAppWidgetOptionsChanged() do AppWidgetProvider.

Powiązywanie widżetów

Gdy użytkownik doda widżet do hosta, następuje proces zwany powiązaniem. Powiązanie oznacza przypisanie konkretnego identyfikatora widżetu aplikacji do konkretnego hosta i konkretnego AppWidgetProvider.

Interfejsy API powiązań umożliwiają też hostowi udostępnianie niestandardowego interfejsu do powiązywania. 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 użytkownik musi wyraźnie przyznać aplikacji uprawnienia, aby mogła ona dodać widżet do hosta. Aby sprawdzić, czy aplikacja ma uprawnienia do dodawania widżetu, użyj metody bindAppWidgetIdIfAllowed(). Jeśli funkcja bindAppWidgetIdIfAllowed() zwróci wartość false, aplikacja musi wyświetlić okno z prośbą o przyznanie uprawnień: „Zezwól” w przypadku bieżącego dodawania widżetu lub „Zawsze zezwalaj” w przypadku wszystkich przyszłych widżetów.

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

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 Umożliwianie użytkownikom konfigurowania widżetów aplikacji.

Obowiązki gospodarza

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

Niezależnie od wersji Androida, na którą kierujesz reklamy, wszystkie hosty mają następujące obowiązki:

• Podczas dodawania widżetu przypisz mu identyfikator zgodnie z opisem powyżej. Gdy widżet zostanie usunięty z hosta, wywołaj funkcję deleteAppWidgetId(), aby zwolnić identyfikator widżetu.

• Podczas dodawania widżetu sprawdź, czy trzeba uruchomić aktywność konfiguracji. Zwykle host musi uruchomić aktywność związaną z konfiguracją 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 działania konfiguracji. Jest to konieczne w przypadku wielu widżetów, aby mogły się wyświetlać.

• Widżety określają domyślną szerokość i wysokość w AppWidgetProviderInfometadanych. Wartości te są zdefiniowane w komórkach – od Androida 12, jeśli podano wartości targetCellWidth i targetCellHeight – lub w jednostkach dp, jeśli podano tylko wartości minWidth i minHeight. Zobacz atrybuty rozmiaru widżetu.

  Upewnij się, że widżet ma co najmniej tyle pikseli niezależnych od gęstości. Na przykład wielu hostów umieszcza ikony i widżety w siatce. W tym scenariuszu host domyślnie 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 poszczególne wersje platformy wprowadzają funkcje, które nakładają na hosta nowe obowiązki.

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

Android 12

Android 12 (poziom API 31) zawiera dodatkowy List<SizeF>, który zawiera listę możliwych rozmiarów w jednostkach dp, jakie może przyjąć instancja widżetu w pakiecie opcji. Liczba podanych rozmiarów zależy od implementacji hosta. Zazwyczaj udostępniają 2 rozmiary reklam na telefony – w orientacji pionowej i poziomej – oraz 4 rozmiary na urządzenia składane.

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

W Androidzie 12 wprowadziliśmy też atrybuty maxResizeWidth i maxResizeHeight w dps. 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 dokumentacją referencyjną Glance.