Ulepsz swój widżet

Ta strona zawiera szczegółowe informacje o opcjonalnych ulepszeniach widżetów, które są dostępne od Androida 12 (poziom API 31). Te funkcje są opcjonalne, ale ich wdrożenie jest proste i umożliwia lepsze wykorzystanie widżetów przez użytkowników.

Używanie kolorów dynamicznych

Od Androida 12 widżet może używać kolorów motywu urządzenia do przycisków, tła i innych komponentów. Dzięki temu przejścia będą płynniejsze, a różne widżety będą spójne.

Dynamiczne kolory możesz uzyskać na 2 sposoby:

Gdy motyw zostanie ustawiony w układzie głównym, możesz użyć wspólnych atrybutów kolorów w układzie głównym lub dowolnym z jego elementów podrzędnych, aby wybrać kolory dynamiczne.

Oto kilka przykładów atrybutów kolorów, których możesz użyć:

  • ?attr/primary
  • ?attr/primaryContainer
  • ?attr/onPrimary
  • ?attr/onPrimaryContainer

W tym przykładzie, w ramach motywu Material 3, kolor motywu urządzenia to „purpurowy”. Kolor akcentu i tło widżetu dostosowują się do trybu jasnego i ciemnego, jak pokazano na rysunkach 1 i 2.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="?attr/colorPrimaryContainer"
  android:theme="@style/Theme.Material3.DynamicColors.DayNight">

  <ImageView
    ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />

    <!-- Other widget content. -->

</LinearLayout>
Widżet w jasnym trybie
Rysunek 1. Widżet w jasnym motywie.
Widgety w ciemnym motywie
Rysunek 2. Widżet w ciemnym motywie.

Zgodność wsteczna kolorów dynamicznych

Kolory dynamiczne są dostępne tylko na urządzeniach z Androidem 12 lub nowszym. Aby udostępnić niestandardowy motyw dla starszych wersji, utwórz domyślny motyw z niestandardowymi kolorami i nowym kwalifikatorem (values-v31) za pomocą domyślnych atrybutów motywu.

Oto przykład użycia motywu Material 3:

/values/styles.xml

<resources>
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    <!-- Override default colorBackground attribute with custom color. -->
    <item name="android:colorBackground">@color/my_background_color</item>

    <!-- Add other colors/attributes. -->

  </style>
</resources>

/values-v31/styles.xml

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

/layout/my_widget_layout.xml

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

Włącz obsługę głosową

Działania w aplikacji umożliwiają Asystentowi Google wyświetlanie widżetów w odpowiedzi na odpowiednie polecenia głosowe użytkownika. Jeśli skonfigurujesz widżet tak, aby reagował na wbudowane intencje, Twoja aplikacja będzie mogła wyświetlać widżety na interfejsach Asystenta, takich jak Android i Android Auto. Użytkownicy mogą przypinać widgety wyświetlane przez Asystenta do swojego menu, co zachęca do dalszego korzystania z tej funkcji.

Możesz na przykład skonfigurować widżet podsumowania treningu w aplikacji do ćwiczeń, aby spełniał polecenia głosowe użytkownika, które uruchamiają GET_EXERCISE_OBSERVATIONBII. Asystent wyświetla aktywnie widżet, gdy użytkownicy aktywują tę usługę, składając prośby takie jak „OK Google, ile kilometrów przebiegłem/przebiegłam w tym tygodniu w ExampleApp?”

Istnieją dziesiątki BIIs obejmujących kilka kategorii interakcji z użytkownikiem, dzięki czemu prawie każda aplikacja na Androida może ulepszać swoje widżety pod kątem obsługi głosu. Aby rozpocząć, zapoznaj się z artykułem Integracja działań aplikacji z widżetami na Androida.

Ulepszanie funkcji selektora widżetów w aplikacji

Android 12 umożliwia dodawanie powiększonych podglądów widżetów i ich opisów. Android 15 pozwala ulepszyć korzystanie z selektora widżetów w aplikacji dzięki generowanym podglądom widżetów.

Aby ulepszyć działanie selektora widżetów w aplikacji, podaj wygenerowany podgląd widżetu na urządzeniach z Androidem 15 i nowszym, pomniejszoną wersję podglądu widżetu (określając previewLayout) na urządzeniach z Androidem 12 do Androida 14 oraz previewImage na wcześniejszych wersjach.

Dodawanie wygenerowanych podglądów widżetów do selektora widżetów

Aplikacje muszą ustawić wartość compileSdk na 35 lub nowszą w pliku modułu build.gradle, aby mieć możliwość przekazywania parametru RemoteViews selektorowi widżetów na urządzeniach z Androidem 15 lub nowszym. Oznacza to, że aplikacje mogą aktualizować zawartość selektora, aby lepiej odzwierciedlała to, co widzi użytkownik.

Aplikacje mogą używać metod AppWidgetManager, setWidgetPreview i getWidgetPreview, aby aktualizować wygląd swoich widżetów, korzystając z aktualnych i spersonalizowanych informacji.

Generowanie zaktualizowanego podglądu za pomocą Jetpack Glance

Glance.compose uruchamia jedną kompozycję, dlatego w ciele elementu nie można używać funkcji zawieszania, przepływów ani podobnych wywołań asynchronicznych. Zamiast tego musisz użyć danych stałych.

W tym przykładzie do wygenerowania zaktualizowanego podglądu użyto Jetpack Glance. Aby compileSdk wyświetlał się jako metoda w tym fragmencie kodu, wymagane jest ustawienie wersji compileSdk na 35 lub nowszej.setWidgetPreview

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    ExampleAppWidget().compose(
        context = appContext
    ),
)

AppWidgetSnippets.kt

Generowanie zaktualizowanego podglądu bez Jetpack Glance

Możesz używać RemoteViews bez Glance. W tym przykładzie wczytujemy zasób układu widgeta XML i ustawiamy go jako podgląd. Aby funkcja setWidgetPreview była widoczna jako metoda w tym fragmencie kodu, wymagane jest ustawienie parametru compileSdk na wartość 35 lub nowszą.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    RemoteViews("com.example", R.layout.widget_preview)
)
AppWidgetSnippets.kt

Dodawanie skalowanych podglądów widżetów do selektora widżetów

Od Androida 12 w górę widżetu wyświetlaną w selektorze widżetów można skalować. Musisz go podać jako układ XML ustawiony na domyślny rozmiar widżetu. Wcześniej podgląd widżetu był statycznym zasobem graficznym, co w niektórych przypadkach powodowało, że podglądy nie odzwierciedlały prawidłowo wyglądu widżetów po dodaniu ich do ekranu głównego.

Aby wdrożyć skalowalne podglądy widżetów, użyj atrybutu previewLayout elementu appwidget-provider, aby zamiast tego podać układ XML:

<appwidget-provider
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

Zalecamy użycie takiego samego układu jak w przypadku rzeczywistego widżetu z realistycznymi wartościami domyślnymi lub testowymi. Większość aplikacji używa tych samych wartości previewLayout i initialLayout. Wskazówki dotyczące tworzenia dokładnych układów podglądu znajdziesz w następnej sekcji tej strony.

Zalecamy określenie atrybutów previewLayout i previewImage, aby aplikacja mogła użyć atrybutu previewImage, jeśli urządzenie użytkownika nie obsługuje atrybutu previewLayout. Atrybut previewLayout ma pierwszeństwo przed atrybutem previewImage.

Zalecane podejścia do tworzenia dokładnych podglądów

Aby wdrożyć skalowalne podglądy widżetów, użyj atrybutu previewLayout elementu appwidget-provider, aby podać układ XML:

<appwidget-provider
    ...
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
Obraz przedstawiający podgląd widżetu
Rysunek 3. Podgląd widżetu, który domyślnie wyświetla się w obszarze 3 x 3, ale może zmieścić się w obszarze 3 x 1 dzięki układowi XML.

Aby wyświetlić dokładny podgląd, możesz bezpośrednio podać rzeczywisty układ widżetu z wartościami domyślnymi, wykonując te czynności:

  • Ustawienie android:text="@string/my_widget_item_fake_1" dla elementów TextView.

  • Ustawienie obrazu lub ikony domyślnej lub zastępczej, na przykład android:src="@drawable/my_widget_icon", dla komponentów ImageView.

Bez wartości domyślnych podgląd może zawierać nieprawidłowe lub puste wartości. Ważną zaletą tego podejścia jest to, że możesz udostępnić zlokalizowane treści podglądu.

Więcej informacji o zalecanych podejściach do bardziej złożonych podglądów zawierających elementy ListView, GridView lub StackView znajdziesz w artykule Tworzenie dokładnych podglądów zawierających elementy dynamiczne.

Zgodność wsteczna z przewidywanymi przez użytkownika widgetami

Aby umożliwić selektorom widżetów na Androidzie 11 (poziom interfejsu API 30) lub starszym wyświetlanie podglądów widżetu, określ atrybut previewImage.

Jeśli zmienisz wygląd widżetu, zaktualizuj obraz podglądu.

Dodawanie nazwy do widżetu

Gdy widżety są wyświetlane w selektorze widżetów, muszą mieć unikalną nazwę.

Nazwy widżetów są ładowane z atrybutu label elementu receiverwidżetu w pliku AndroidManifest.xml.

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

Dodawanie opisu widżetu

Od Androida 12 możesz podać opis selektora widżetu, który będzie wyświetlany dla widżetu.

Obraz pokazujący selektor widżetów z widżetem i jego opisem
Rysunek 4. Przykład selektora widżetów pokazujący widżet i jego opis.

Podaj opis widżetu za pomocą atrybutu description elementu &lt;appwidget-provider&gt;:

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

W poprzednich wersjach Androida możesz używać atrybutu descriptionRes, ale selektor widżetów go ignoruje.

Włącz płynniejsze przejścia

Od Androida 12 uruchamianie aplikacji z widżetu jest płynniejsze.

Aby włączyć to ulepszone przejście, użyj @android:id/background lub android.R.id.background, aby zidentyfikować element tła:

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

Aplikacja może używać @android:id/background w poprzednich wersjach Androida, ale funkcja ta jest ignorowana.

Modyfikowanie widoku zdalnego w czasie wykonywania

Od Androida 12 możesz korzystać z kilku metod RemoteViews, które umożliwiają modyfikację atrybutów RemoteViews w czasie wykonywania. Pełną listę dodanych metod znajdziesz w dokumentacji interfejsu API RemoteViews.

Przykładowy kod poniżej pokazuje, jak używać kilku z tych metod.

Kotlin

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList())

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)

Java

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList());

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);