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 To nie jest jest wymagane dla większości aplikacji. Jeśli jednak tworzysz własny ważne jest zrozumienie zobowiązań umownych, na które host domyślnie akceptuje zobowiązania umowne.

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ą, 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 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ązane z wartością AppWidgetHostView za każdym razem, gdy widżet zostanie powiększony przez hosta.

    • 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. Gospodarzem jest odpowiedzialnym za uatrakcyjnianie 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. Za pomocą updateAppWidgetOptions() oraz updateAppWidgetSize() aby zmodyfikować pakiet widżetów. Obie te metody wywołują onAppWidgetOptionsChanged() oddzwanianie do AppWidgetProvider.

Wiązania widżetów

Gdy użytkownik dodaje widżet do hosta, odbywa się proces nazywany powią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 i powiązania. Aby można było korzystać z tego procesu, aplikacja musi zadeklarować parametr BIND_APPWIDGET uprawnienia w pliku manifestu hosta:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

To jednak dopiero pierwszy krok. W trakcie działania aplikacji użytkownik musi wprost przyznać aplikacji, aby umożliwić jej dodanie widżetu 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:

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 dodany przez użytkownika wymaga konfiguracji. Dla: więcej informacji znajdziesz w artykule Umożliwianie użytkownikom konfigurowania aplikacji widżety.

Obowiązki organizatora

Możesz określić wiele ustawień konfiguracji widżetów, korzystając z Metadane AppWidgetProviderInfo. 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 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ł już wprowadzony. 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 na podstawie 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 AppWidgetProviderInfo metadanych. Te wartości są zdefiniowane w komórkach – poczynając od Android 12, jeśli targetCellWidth i targetCellHeight są – lub dps, jeśli określono tylko 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.

Obowiązuje limit MAX_INIT_VIEW_COUNT (16) liczby różnych RemoteViews, które może przesłać AppWidgetProvider RemoteViews Obiekty AppWidgetProvider mapują obiekt RemoteViews na każdy rozmiar w 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.