Tworzenie hosta widżetów

Ekran główny Androida, dostępny na większości urządzeń z Androidem, pozwala użytkownikowi umieszczać widżety aplikacji (lub widżety) w celu szybkiego dostępu 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.

Ta strona skupia się na obowiązkach związanych z wdrażaniem niestandardowego AppWidgetHost. 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 wdrażaniem niestandardowego AppWidgetHost:

• Host widżetów aplikacji: AppWidgetHost zapewnia interakcję z usługą AppWidget w przypadku aplikacji, które umieszczają widżety w interfejsie. 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ą, przypisać w aplikacji.

• Identyfikator widżetu aplikacji: każde wystąpienie widżetu ma w danym momencie przypisany unikalny identyfikator. nie jest wiążąca. Zobacz bindAppWidgetIdIfAllowed() Więcej szczegółów znajdziesz w dalszej sekcji Wiązania widżetów. Host uzyskuje unikalny identyfikator za pomocą allocateAppWidgetId(). Ten identyfikator jest zachowany przez cały czas istnienia widżetu, dopóki nie zostanie usunięty z hosta. Każdy stan specyficzny dla hosta, np. rozmiar i położenie widżetu, musi być zapisany w pakiecie hosta i powiązany z identyfikatorem widżetu aplikacji.

• Widok hosta widżetu aplikacji: AppWidgetHostView to ramka, w której widżet jest 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 interfejsu API 31), AppWidgetHostView wprowadza setColorResources() oraz resetColorResources() obsługi kolorów przeładowanych dynamicznie. 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. Dzięki tym informacjom AppWidgetProvider dostosowuje zawartość i wygląd widżetu do gdzie jest wyświetlany. Możesz użyć elementów updateAppWidgetOptions() i updateAppWidgetSize(), aby zmodyfikować pakiet widgeta. Obie te metody wywołują wywołanie AppWidgetProvideronAppWidgetOptionsChanged().

Wiązanie widżetów

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

Interfejsy API powiązań umożliwiają również hostowi udostępnienie niestandardowego interfejsu użytkownika powiązanie. 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 ma uprawnienia do dodania widżetu, użyj bindAppWidgetIdIfAllowed() . Jeśli bindAppWidgetIdIfAllowed() zwraca wartość false, aplikacja musi wyświetlić okno z prośbą o przyznanie uprawnień: „allow” (zezwalaj) dla bieżącego widżetu add lub „zawsze zezwalaj” , aby uwzględnić wszystkie przyszłe dodatki do widżetów.

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

Obowiązki organizatora

Możesz określić wiele ustawień konfiguracji widżetów, korzystając z Metadane AppWidgetProviderInfo. Te opcje konfiguracji, opisane szczegółowo w następnych sekcjach, możesz pobrać z obiektu AppWidgetProviderInfo powiązanego 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 został usunięty z hosta, wywołaj deleteAppWidgetId() do alokacji identyfikatora widżetu.

• Podczas dodawania widżetu sprawdź, czy aktywność związana z konfiguracją musi być który został uruchomiony. 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. Szczegółowe informacje znajdziesz w sekcji Aktualizowanie widżetu z działania konfiguracji. Jest to konieczne, zanim widżety zaczną się wyświetlać.

• Widżety określają domyślną szerokość i wysokość w AppWidgetProviderInfo metadanych. 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.

  Dopilnuj, aby układ widżetu miał co najmniej taką liczbę dps. Dla: Na przykład wiele hostów wyrównuje ikony i widżety w 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 musisz też wersje platformowe 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, jakie wystąpienie widżetu może przyjąć w pakiecie opcji. Podana liczba 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.

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 tabeli List<SizeF>, podaj maksymalnie MAX_INIT_VIEW_COUNT rozmiary.

Android 12 to także maxResizeWidth oraz maxResizeHeight atrybutów w dps. Zalecamy, aby widget, który używa co najmniej jednego z tych atrybutów, nie przekraczał rozmiaru określonego przez te atrybuty.

Dodatkowe materiały

• Więcej informacji znajdziesz w dokumentacji referencyjnej Glance.