Tworzenie hosta widżetów

Ekran główny Androida, dostępny na większości urządzeń z Androidem, pozwala użytkownikowi umieścić widżety aplikacji (lub widżety), aby mieć szybki dostęp do treści. Jeśli chcesz wymienić ekran główny lub podobną aplikację, możesz też zezwolić użytkownikowi na umieszczanie widżetów, implementując AppWidgetHost. Nie jest to wymagane w przypadku większości aplikacji, ale jeśli tworzysz własny host, ważne jest zrozumienie zobowiązań umownych, na które host domyślnie wyraża zgodę.

Na tej stronie omawiamy obowiązki związane z implementacją niestandardowego elementu AppWidgetHost. Konkretny przykład implementacji obiektu AppWidgetHost znajdziesz w kodzie źródłowym ekranu głównego Androida LauncherAppWidgetHost.

Oto przegląd najważniejszych klas i koncepcji związanych z implementacją niestandardowego elementu AppWidgetHost:

• Host widżetu aplikacji: AppWidgetHost umożliwia interakcję z usługą AppWidget w przypadku aplikacji, które zawierają widżety w swoim interfejsie. AppWidgetHost musi mieć unikalny identyfikator w pakiecie hosta. Identyfikator ten jest widoczny we wszystkich przypadkach użycia hosta. Jest to zwykle zakodowana na stałe wartość, 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. bindAppWidgetIdIfAllowed() oraz więcej szczegółów znajdziesz w poniższej sekcji Wiązanie 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 – taki jak rozmiar i lokalizacja widżetu – musi być zachowany przez pakiet hostingowy i powiązany z identyfikatorem widżetu aplikacji.

• Widok hosta widżetu aplikacji: traktuj AppWidgetHostView jako ramkę, w którą zawija się widżet, gdy chce się wyświetlić. Widżet jest powiązany z funkcją AppWidgetHostView za każdym razem, gdy hostuje widżet.

  • Domyślnie system tworzy klasę AppWidgetHostView, ale host może utworzyć własną podklasę klasy AppWidgetHostView przez rozszerzenie.
  • Począwszy od Androida 12 (poziom interfejsu API 31) AppWidgetHostView wprowadza metody setColorResources() i resetColorResources() do obsługi dynamicznie przeciążonych kolorów. To gospodarz jest odpowiedzialny za dodanie kolorów do tych metod.

• Pakiet opcji: AppWidgetHost używa tego pakietu, aby przekazywać do AppWidgetProvider informacje o sposobie wyświetlania widżetu – np. o liście 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 w zależności od sposobu i miejsca jego wyświetlania. Aby zmodyfikować pakiet widżetów, możesz użyć updateAppWidgetOptions() i updateAppWidgetSize(). Obie te metody wywołują wywołanie zwrotne onAppWidgetOptionsChanged() do AppWidgetProvider.

Wiązania widżetów

Gdy użytkownik dodaje widżet do hosta, odbywa się proces nazywany powiązaniem. Powiązanie odnosi się do powiązania konkretnego identyfikatora widżetu aplikacji z konkretnym hostem i konkretnym obiektem AppWidgetProvider.

Interfejsy API powiązań umożliwiają też hostowi dostarczanie niestandardowych interfejsów użytkownika do powiązań. Aby można było 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 aplikacji użytkownik musi wprost przyznać jej uprawnienia, aby mogła ona dodawać widżety do hosta. Aby sprawdzić, czy aplikacja ma uprawnienia do dodawania widżetu, użyj metody bindAppWidgetIdIfAllowed(). Jeśli bindAppWidgetIdIfAllowed() zwraca wartość false, aplikacja musi wyświetlić okno z prośbą o przyznanie uprawnień: „allow” (zezwól) w przypadku bieżącego dodawania widżetów lub „always allow” (Zawsze zezwalaj), aby uwzględnić wszystkie przyszłe dodawane widżety.

Ten fragment kodu pokazuje na przykład, jak wyświetlić to 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 organizatora

Za pomocą metadanych AppWidgetProviderInfo możesz określić różne ustawienia konfiguracji widżetów. Te opcje konfiguracji, które zostały szczegółowo omówione w poniższych sekcjach, możesz pobrać z obiektu AppWidgetProviderInfo powiązanego z dostawcą widżetów.

Niezależnie od docelowej wersji Androida wszystkie hosty są odpowiedzialne za:

• Podczas dodawania widżetu przydziel identyfikator widżetu w sposób opisany powyżej. 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ą. Zwykle host musi uruchomić aktywność konfiguracyjną widżetu, jeśli istnieje i nie jest oznaczony jako opcjonalny, używając 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 – począwszy od Androida 12, jeśli określono właściwości targetCellWidth i targetCellHeight, lub dps, jeśli określono tylko minWidth i minHeight. Zobacz Atrybuty rozmiaru widżetów.

  Dopilnuj, aby układ widżetu miał co najmniej taką liczbę dps. Na przykład wiele hostów wyrównuje ikony i widżety w siatce. W tym scenariuszu domyślnie host dodaje widżet z użyciem minimalnej liczby komórek zgodnych z ograniczeniami minWidth i minHeight.

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

Określ podejście na podstawie docelowej wersji Androida

Android 12

Android 12 (poziom interfejsu API 31) obejmuje dodatkowy element List<SizeF> zawierający listę możliwych rozmiarów w dps, które wystąpienie widżetu może przyjmować w pakiecie opcji. Podana liczba rozmiarów zależy od implementacji hosta. Gospodarze zwykle udostępniają 2 rozmiary dla telefonów (pionowe i poziome) oraz 4 rozmiary dla urządzeń składanych.

Obowiązuje limit MAX_INIT_VIEW_COUNT (16) liczby różnych elementów RemoteViews, które AppWidgetProvider może przekazać do RemoteViews. 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

• Więcej informacji znajdziesz w dokumentacji referencyjnej Glance.