Tworzenie hosta widżetów

Ekran główny Androida, dostępny na większości urządzeń z Androidem, pozwala użytkownikom umieszczać widżety aplikacji (lub widżety) w celu szybkiego dostępu do treści. Jeśli tworzysz zamiennik ekranu głównego lub podobną aplikację, możesz także pozwolić użytkownikom na umieszczanie widżetów, stosując metodę AppWidgetHost. Większość aplikacji nie musi tego zrobić, ale jeśli tworzysz własnego hosta, ważne jest, by poznać zobowiązania umowne, które host domyślnie akceptuje.

Ta strona zawiera informacje o obowiązkach związanych z wdrażaniem niestandardowych elementów zamówienia AppWidgetHost. Konkretny przykład implementacji 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żetów aplikacji: AppWidgetHost umożliwia interakcję z usługą AppWidget w przypadku aplikacji, które umieszczają widżety w swoim interfejsie. AppWidgetHost musi mieć unikalny identyfikator w ramach pakietu hosta. Ten identyfikator występuje we wszystkich zastosowaniach hosta. Jest to zwykle zakodowana na stałe wartość, którą przypisujesz w aplikacji.

  • Identyfikator widżetu aplikacji: w momencie tworzenia powiązania do każdej instancji widżetu jest przypisywany unikalny identyfikator. Więcej informacji znajdziesz w sekcji bindAppWidgetIdIfAllowed() oraz w kolejnej sekcji Wiązanie widżetów. Host uzyskuje unikalny identyfikator za pomocą allocateAppWidgetId(). Ten identyfikator będzie obowiązywał przez cały okres istnienia widżetu, aż zostanie usunięty z hosta. Każdy stan związany z hostem, taki jak rozmiar i lokalizacja widżetu, musi być utrwalony przez pakiet hostujący i powiązany z identyfikatorem widżetu aplikacji.

  • Widok hosta widżetu aplikacji: AppWidgetHostView można traktować jako ramkę, w którą widżet jest pakowany za każdym razem, gdy trzeba go wyświetlić. Widżet jest powiązany z AppWidgetHostView za każdym razem, gdy widżet jest zwiększany przez hosta.

    • Domyślnie system tworzy klasę AppWidgetHostView, ale po jej rozszerzeniu host może utworzyć własną podklasę klasy AppWidgetHostView.
    • Począwszy od Androida 12 (poziom interfejsu API 31) AppWidgetHostView wprowadza metody setColorResources() i resetColorResources() do obsługi dynamicznie przeciążonych kolorów. Za umieszczenie kolorów tych metod odpowiada gospodarz.

  • Pakiet opcji: AppWidgetHost używa pakietu opcji, aby przekazywać do AppWidgetProvider informacje o sposobie wyświetlania widżetu (np. liście 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 dostosowywać 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 metody onAppWidgetOptionsChanged() w metodzie AppWidgetProvider.

Wiązanie widżetów

Gdy użytkownik dodaje widżet do hosta, zachodzi proces o nazwie powiązanie. Powiązanie odnosi się do wiązania konkretnego identyfikatora widżetu aplikacji z konkretnym hostem i konkretnym zasobem AppWidgetProvider.

Interfejsy API powiązań umożliwiają też hostowi udostępnienie niestandardowego interfejsu do tworzenia 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 aplikacji użytkownik musi jawnie 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ń: „zezwól” w przypadku bieżącego dodania widżetu lub „zawsze zezwalaj” w przypadku wszystkich przyszłych dodatków do widżetu.

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

Kotlin

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)

Java

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, który dodaje użytkownik, wymaga konfiguracji. Więcej informacji znajdziesz w artykule Zezwalanie użytkownikom na konfigurowanie widżetów aplikacji.

Obowiązki gospodarza

Możesz określić różne ustawienia konfiguracji widżetów, używając metadanych AppWidgetProviderInfo. Te opcje konfiguracji, które zostały szczegółowo omówione w kolejnych sekcjach, możesz pobrać z obiektu AppWidgetProviderInfo powiązanego z dostawcą widżetu.

Bez względu na wersję Androida, na którą kierujesz reklamy, wszyscy hosty są odpowiedzialni za:

  • Podczas dodawania widżetu przydziel go w sposób opisany wcześniej. Po usunięciu widżetu z hosta wywołaj deleteAppWidgetId(), aby zwolnić identyfikator widżetu.

  • Podczas dodawania widżetu sprawdź, czy trzeba uruchomić działanie konfiguracji. Zwykle host musi uruchomić działanie konfiguracji widżetu, jeśli istnieje i nie jest oznaczone jako opcjonalne przez podanie zarówno flagi configuration_optional, jak i reconfigurable. Więcej informacji znajdziesz w sekcji Aktualizowanie widżetu z poziomu działania konfiguracji. W przypadku wielu widżetów jest to konieczne, aby mogły się wyświetlać.

  • Widżety określają domyślną szerokość i wysokość w metadanych AppWidgetProviderInfo. Wartości te są definiowane w komórkach (począwszy od Androida 12, jeśli określono targetCellWidth i targetCellHeight), lub dps, jeśli określono tylko minWidth i minHeight. Przeczytaj sekcję Atrybuty rozmiaru widżetów.

    Upewnij się, że układ widżetu ma 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 spełniających ograniczenia minWidth i minHeight.

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

Określ swoje podejście na podstawie docelowej wersji Androida.

Android 12

Android 12 (poziom interfejsu API 31) zawiera dodatkowy element List<SizeF> zawierający listę możliwych rozmiarów w dps, które instancja widżetu może przyjąć w pakiecie opcji. Liczba podanych rozmiarów zależy od implementacji hosta. Hosty są zwykle dostępne w 2 rozmiarach dla telefonów – pionowym i poziomym – oraz 4 rozmiarach dla urządzeń składanych.

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

  • Zobacz dokumentację Glance.