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 konieczne w przypadku większości aplikacji, ale jeśli tworzysz własnego hosta, musisz znać zobowiązania umowne, na które host domyślnie się zgadza.

Ta strona zawiera informacje o obowiązkach związanych z wdrażaniem niestandardowego AppWidgetHost. 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. Identyfikator jest zwykle zakodowaną na stałe wartością, którą przypisujesz w aplikacji.

  • Identyfikator widżetu aplikacji: każdej instancji widżetu jest przypisywany unikalny identyfikator w momencie powiązania. bindAppWidgetIdIfAllowed() Więcej informacji znajdziesz w sekcji Wiązanie widżetów poniżej. 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 hostujący i powiązane z identyfikatorem widżetu aplikacji.

  • Widok hosta widżetu aplikacji: wyobraź sobie AppWidgetHostView jako ramkę otaczającą widżet, 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. Możesz użyć updateAppWidgetOptions() i updateAppWidgetSize() do modyfikowania pakietu widżetu. 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.provider)
    // This is the options bundle described in the preceding section.
    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 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 przypisz jego 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 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 konieczny krok w przypadku wielu widżetów, zanim będą 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 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 pikseli niezależnych od gęstości. Na przykład wielu hostów wyrównuje 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.

Wskazówki dotyczące podejścia

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

Pakiet opcji może zawierać List<SizeF>, który zawiera listę możliwych rozmiarów w jednostkach dp, jakie może przyjąć instancja widżetu. Liczba podanych rozmiarów zależy od implementacji hosta. Zazwyczaj udostępniają 2 rozmiary na telefony – pionowy i poziomy – 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). Ponieważ obiekty AppWidgetProvider mapują obiekt RemoteViews na każdy rozmiar w List<SizeF>, nie podawaj więcej niż MAX_INIT_VIEW_COUNT rozmiarów.

Jeśli widżety określają atrybuty maxResizeWidth i maxResizeHeight w parametrze 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.