Tworzenie hosta widżetów

Ekran główny Androida, dostępny na większości urządzeń z Androidem, umożliwia widżety aplikacji (lub widżety) umieszczonych przez użytkowników dla szybki dostęp do treści. Jeśli chcesz wymienić ekran główny lub aplikacji, możesz też zezwolić użytkownikowi na umieszczanie widżetów, implementując AppWidgetHost Większość aplikacji nie musi tego robić, ale jeśli tworzysz własne hosty, musisz znać zobowiązania umowne, na które host się zgadza.

Na tej stronie omawiamy obowiązki związane z wdrażaniem niestandardowych AppWidgetHost Konkretny przykład implementacji obiektu AppWidgetHost: spójrz na kod źródłowy ekranu głównego Androida LauncherAppWidgetHost

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

• Host widżetu aplikacji: AppWidgetHost udostępnia interakcję z Usługa AppWidget dla aplikacji osadzonych w interfejsie użytkownika. AppWidgetHost musi mieć unikalny identyfikator w pakiecie hosta. Ten identyfikator pozostaje bez zmian w przypadku wszystkich sposobów korzystania z hosta. Identyfikator jest zwykle zakodowaną na stałe wartością, którą przypisujesz w aplikacji.

• Identyfikator widżetu aplikacji: każdemu wystąpieniu widżetu przypisany jest unikalny identyfikator w momencie powiązania. Zobacz bindAppWidgetIdIfAllowed() Więcej szczegółów znajdziesz w dalszej sekcji Wiązania widżetów. Host uzyskuje unikalny identyfikator za pomocą allocateAppWidgetId(). Ten identyfikator będzie widoczny przez cały okres aktywności widżetu, dopóki nie zostanie usunięty z hosta. Dowolny stan specyficzny dla hosta, taki jak rozmiar i lokalizacja widżet – musi być zachowywany przez pakiet hostingowy i powiązany z tagiem identyfikator widżetu aplikacji.

• Widok hosta widżetu aplikacji: AppWidgetHostView jako ramka aby widżet został zapakowany, gdy ma być wyświetlany. Widżet jest powiązany z elementem AppWidgetHostView za każdym razem, gdy host go tworzy.

  • Domyślnie system tworzy AppWidgetHostView, ale host może utworzy własną podklasę AppWidgetHostView przez rozszerzenie.
  • Począwszy od Androida 12 (poziom API 31) w AppWidgetHostView wprowadzono metody setColorResources() i resetColorResources() do obsługi dynamicznie przeciążonych kolorów. Gospodarz jest odpowiedzialny za udostępnianie kolorów w ramach tych metod.

• Pakiet opcji: AppWidgetHost używa pakietu opcji do: przekazują informacje AppWidgetProvider o sposobie wyświetlania widżetu – na przykład listę zakresów rozmiarów oraz informację, czy jest na ekranie blokady lub ekranie głównym. Te informacje pozwalają AppWidgetProvider dostosować zawartość i wygląd widżetu na podstawie sposobu i miejsca wyświetlania. Za pomocą updateAppWidgetOptions() oraz updateAppWidgetSize() aby zmodyfikować pakiet widżetów. Obie te metody wywołują wywołanie AppWidgetProvideronAppWidgetOptionsChanged().

Wiązania widżetów

Gdy użytkownik dodaje widżet do hosta, odbywa się proces zwany wiązaniem. Powiązanie oznacza powiązanie identyfikatora konkretnego widżetu aplikacji z określonym hostem i określonym AppWidgetProvider.

Interfejsy API do wiązania umożliwiają też hostowi udostępnienie niestandardowego interfejsu użytkownika do wiązania. 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 aplikacji użytkownik musi wyraźnie przyznać jej uprawnienia, aby mogła dodać widżet do hosta. Aby sprawdzić, czy Twoja aplikacja ma uprawnienia do dodania widżetu, użyj metody bindAppWidgetIdIfAllowed(). Jeśli bindAppWidgetIdIfAllowed() zwraca false, aplikacja musi wyświetlić okno dialogowe z prośbą o przyznanie uprawnień: „Zezwól” w przypadku bieżącego dodania widżetu lub „Zawsze zezwól” w przypadku wszystkich przyszłych dodanych widżetów.

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

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 Zezwalanie użytkownikom na konfigurowanie widżetów aplikacji.

Obowiązki hosta

Za pomocą metadanych AppWidgetProviderInfo możesz określić wiele ustawień konfiguracji widżetów. Wszystkie te opcje konfiguracji znajdziesz szczegółowo w kolejnych sekcji, od AppWidgetProviderInfo powiązany z dostawcą widżetu.

Niezależnie od docelowej wersji Androida wszystkie hosty mają parametr następujące obowiązki:

• Podczas dodawania widżetu przydziel identyfikator widżetu w sposób opisany 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 należy uruchomić aktywność konfiguracyjną. Zwykle host musi uruchomić konfigurację widżetu. jeśli istnieje i nie jest oznaczona jako opcjonalna przez określenie obu Flagi configuration_optional i reconfigurable. Zobacz Aktualizowanie widżetu z poziomu aktywności związanej z konfiguracją . 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 – od Androida 12, jeśli są określone wartości targetCellWidth i targetCellHeight, lub w przypadku pikseli na cal, jeśli są określone tylko wartości minWidth i minHeight. Zobacz Atrybuty rozmiaru widżetu.

  Upewnij się, że układ widżetu zawiera co najmniej tę liczbę pikseli na cal. Na przykład wielu gospodarzy wyrównuje ikony i widżety na siatce. W tym scenariuszu przez domyślnie host dodaje widżet z minimalną liczbą komórek, które spełniają warunki minWidth i minHeight.

Oprócz wymagań wymienionych w poprzedniej sekcji niektóre wersje platformy 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) zawiera dodatkowy pakiet List<SizeF> z listą możliwych rozmiarów w pikselach na cal, które może przyjąć instancja widżetu w pakiecie opcji. Liczba dostępnych rozmiarów zależy od implementacji hosta. Zwykle gospodarze na telefony komórkowe i w 4 rozmiarach – w orientacji pionowej i poziomej urządzeń składanych.

Obowiązuje limit MAX_INIT_VIEW_COUNT (16) liczby różnych RemoteViews, które może przesłać AppWidgetProvider RemoteViews Ponieważ obiekty AppWidgetProvider mapują obiekt RemoteViews na każdy rozmiar w tabeli List<SizeF>, podaj maksymalnie MAX_INIT_VIEW_COUNT rozmiary.

Android 12 to także maxResizeWidth oraz maxResizeHeight atrybutów w dps. Zalecamy, aby widżet używający co najmniej jednego z tych elementów rozmiar nie przekracza wartości określonej przez atrybuty.

Dodatkowe materiały

• Więcej informacji znajdziesz w dokumentacji referencyjnej Glance.