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 można je łatwo wdrożyć i ulepszyć w obsłudze widżetó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. Zapewnia to płynniejsze przejścia i spójność różnych widżetów.

Dynamiczne kolory możesz uzyskać na 2 sposoby:

• Użyj domyślnego motywu systemu (@android:style/Theme.DeviceDefault.DayNight) w układzie głównym.

• Użyj motywu Material 3 (Theme.Material3.DynamicColors.DayNight) z biblioteki Material Components for Android, dostępnej od wersji Material Components for Android w wersji 1.6.0.

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 przykładzie poniżej z użyciem motywu Material 3 motyw urządzenia jest kolorem fioletowym. Kolor uzupełniający i tło widżetu dostosowują się do trybu jasnego i ciemnego, co widać 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>

Rysunek 1. Widżet w jasnym motywie.

Rysunek 2. Widżet w ciemnym motywie.

Wskazówka: zalecamy używanie motywu Material 3 w celu zachowania zgodności z wytycznymi Material Design, aby zapewnić spójność między urządzeniami i zgodność wsteczną.

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>

Uwaga: aby uzyskać szczegółowe informacje o obsługiwaniu różnych stylów, kolorów, atrybutów i motywów, zapoznaj się z artykułem Style i motywy.

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

Działania w aplikacji pozwalają Asystentowi Google wyświetlać widżety 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ć widżety wyświetlane przez Asystenta do programu uruchamiającego, co zwiększa zaangażowanie użytkowników w przyszłości.

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ę funkcję, 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 skalowanych podglądów widżetów i opisów widżetów. Android 15 umożliwia ulepszenie selektora widżetów aplikacji za pomocą wygenerowanych podglądów widżetów.

Aby ulepszyć selektor widżetów aplikacji, udostępnij wygenerowany podgląd widżetu na urządzeniach z Androidem 15 i nowszym, skalowany podgląd widżetu (podając previewLayout) w przypadku urządzeń z Androidem 12–14 oraz previewImage – w przypadku starszych wersji.

Dodaj wygenerowane podglądy 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 kompozytowalnej nie są używane żadne zawieszone funkcje, przepływy ani podobne asynchroniczne wywołania. Zamiast tego musisz użyć danych stałych.

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

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

Generuj zaktualizowany podgląd bez Jetpack Glance

Możesz używać aplikacji RemoteViews bez Wglądu. 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 podać układ XML:

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

Zalecamy użycie tego samego układu co widżet, 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 zarówno atrybutu previewLayout, jak i previewImage, aby aplikacja mogła ponownie używać elementu previewImage, jeśli urządzenie użytkownika nie obsługuje 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 określić układ XML:

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

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.

  Uwaga: wartości ustawione za pomocą tagu tools, np. tools:text="@string/my_wdiget_item_fake_1", nie są wyświetlane w podglądzie.

• 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ć zlokalizowaną treść 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>

Dodaj opis widżetu

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

Rysunek 4. Przykład selektora widżetów pokazujący widżet i jego opis.

Podaj opis widżetu za pomocą atrybutu description elementu <appwidget-provider>:

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

Uwaga: bądź zwięzły. Nie ma limitu znaków, ale prezentacja i dostępne miejsce na opis mogą się różnić w zależności od urządzenia.

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 zapewnia płynniejsze przejście.

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>

Ostrzeżenie: unikaj korzystania z przesyłania trampolinowego. Od Androida 12 aplikacja może nadal uruchamiać aktywność z odbiornika lub usługi przesyłania strumieniowego, jeśli jest to wywoływane przez kliknięcie widgetu PendingIntent. Jednak nowa animacja aplikacji nie jest używana w przypadku aplikacji uruchamianych przez odbiornik lub usługę przesyłania strumieniowego, co powoduje problemy z wygodą użytkowania.

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

Używaj modyfikacji czasu działania obiektów RemoteView

Począwszy od Androida 12 można korzystać z kilku metod RemoteViews do modyfikowania atrybutów RemoteViews w czasie działania. 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);