Tworzenie hosta widżetów

Ekran główny Androida, dostępny na większości urządzeń z tym systemem, 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 umieszczanie widżetów, implementując AppWidgetHost. Większość aplikacji nie musi tego robić, ale jeśli tworzysz własnego hosta, musisz zrozumieć zobowiązania umowne, które host akceptuje w sposób dorozumiany.

Na tej stronie omawiamy obowiązki związane z implementacją niestandardowego AppWidgetHost. Konkretny 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 implementacją niestandardowego elementu 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 pakiecie 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. Zobacz bindAppWidgetIdIfAllowed() i sekcję Wiązanie widżetów poniżej, aby dowiedzieć się więcej. Host uzyskuje unikalny identyfikator za pomocą allocateAppWidgetId(). Ten identyfikator jest zachowywany przez cały okres ważności widżetu, dopóki nie zostanie on usunięty z hosta. Wszystkie stany związane z hostem, takie jak rozmiar i lokalizacja widżetu, muszą być przechowywane przez pakiet hostujący i powiązane z identyfikatorem widżetu aplikacji.

• Widok hosta widżetu aplikacji: AppWidgetHostView to ramka, w której widżet jest umieszczany, gdy ma zostać wyświetlony. 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 (poziom interfejsu API 31) AppWidgetHostView wprowadza metody setColorResources() i resetColorResources() do obsługi dynamicznie przeciążonych kolorów. Host jest odpowiedzialny za dostarczanie kolorów do tych metod.

• Pakiet opcji: AppWidgetHost używa pakietu opcji do przekazywania informacji do AppWidgetProvider o tym, jak wyświetlany jest widżet, 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 AppWidgetProvider może dostosować zawartość i wygląd widżetu do sposobu i miejsca jego wyświetlania. Aby zmodyfikować pakiet widżetu, możesz użyć updateAppWidgetOptions() i updateAppWidgetSize(). Obie te metody wywołują wywołanie zwrotne onAppWidgetOptionsChanged() do AppWidgetProvider.

Bindowanie widżetów

Gdy użytkownik dodaje widżet do hosta, następuje proces nazywany wiązaniem. Powiązanie odnosi się do powiązania konkretnego identyfikatora widżetu aplikacji z określonym hostem i określonym AppWidgetProvider.

Interfejsy API powiązań umożliwiają też hostowi udostępnianie niestandardowego interfejsu do powiązań. 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 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 bindAppWidgetIdIfAllowed() zwraca 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 dodawań 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.provider)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)
Host.kt

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

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

Wszyscy gospodarze mają te obowiązki:

• Podczas dodawania widżetu przydziel identyfikator widżetu zgodnie z opisem powyżej. Gdy widżet zostanie usunięty z hosta, wywołaj funkcję deleteAppWidgetId(), aby wycofać przydział 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 sekcji Aktualizowanie widżetu z poziomu aktywności konfiguracji. Jest to konieczny krok, aby wiele widżetów mogło się wyświetlać.

• Widżety określają domyślną szerokość i wysokość w metadanych AppWidgetProviderInfo. Te wartości są definiowane w komórkach – począwszy 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 ma co najmniej tyle dp. Na przykład wiele hostów 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óre spełniają ograniczenia minWidth i minHeight.

Wskazówki dotyczące podejścia

Oprócz wymagań wymienionych w poprzedniej sekcji pamiętaj o tych wskazówkach:

Pakiet opcji może zawierać element List<SizeF>, który zawiera listę możliwych rozmiarów w dp, jakie może przyjąć instancja widżetu. Liczba podanych rozmiarów zależy od implementacji hosta. Hosty zwykle udostępniają 2 rozmiary dla telefonów (pionowy i poziomy) oraz 4 rozmiary dla urządzeń składanych.

Liczba różnych RemoteViews, które AppWidgetProvider może udostępniać 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.

Jeśli widżety określają 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 atrybuty.

Dodatkowe materiały

• Zapoznaj się z dokumentacją referencyjną Glance.