Ulepsz swój widżet

Ta strona zawiera 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 dynamicznych kolorów

Od Androida 12 widżet może używać kolorów motywu urządzenia w przypadku przycisków, tła i innych komponentów. Zapewnia to płynniejsze przejścia i spójność różnych widżetów.

Istnieją dwa sposoby na uzyskanie dynamicznych kolorów:

• 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 Komponenty na Androida, dostępnej od Material Komponenty na Androida w wersji 1.6.0.

Po ustawieniu motywu w układzie głównym możesz użyć typowych atrybutów koloru w katalogu głównym lub jego elementach podrzędnych, aby wybrać kolory dynamiczne.

Oto kilka przykładów atrybutów koloru:

• ?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

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

Oto przykład z wykorzystaniem 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: w sekcji Style i motywy znajdziesz szczegółowy przewodnik po obsłudze różnych stylów, kolorów, atrybutów i motywów.

Włącz pomoc 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 intencje wbudowane (BII), aplikacja będzie mogła aktywnie wyświetlać widżety na platformach Asystenta takich jak Android czy 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ć w aplikacji do ćwiczeń widżet z podsumowaniem treningów, aby wykonywał polecenia głosowe użytkownika, które uruchamiają wskaźnik GET_EXERCISE_OBSERVATION BII. Asystent aktywnie wyświetla Twój widżet, gdy użytkownik aktywuje tę BII, wysyłając prośby w rodzaju: „OK Google, ile kilometrów udało mi się przebiec w tym tygodniu w przykładowej aplikacji?”.

Istnieją dziesiątki BII obejmujących kilka kategorii interakcji, dzięki czemu niemal każda aplikacja na Androida będzie ulepszać swoje widżety głosowe. Zanim zaczniesz, przeczytaj artykuł Integrowanie akcji w aplikacji z widżetami na Androida.

Usprawnij selektor widżetów aplikacji

Android 12 umożliwia ulepszenie selektora widżetów aplikacji przez dodanie dynamicznych podglądów widżetów i ich opisów.

Dodaj podglądy skalowalnych widżetów do selektora widżetów

Od wersji Androida 12 podgląd widżetu wyświetlany w selektorze widżetów jest skalowalny. Podajesz go jako układ XML ustawiony na domyślny rozmiar widżetu. Wcześniej podgląd widżetu był statycznym zasobem rysowanym, dlatego w niektórych przypadkach podgląd mógł niedokładnie odzwierciedlać sposób wyświetlania widżetów po dodaniu 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 funkcji 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 atrybutów 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 metody 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 dzięki swojemu układowi XML może zmieścić się w obszarze 3 x 1.

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, takie jak tools:text="@string/my_wdiget_item_fake_1", nie są wyświetlane na podglądzie.

• Ustawianie domyślnego lub zastępczego obrazu bądź ikony, np. android:src="@drawable/my_widget_icon", dla komponentów ImageView.

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

Zalecane metody wyświetlania bardziej złożonych podglądów zawierających obiekty ListView, GridView lub StackView znajdziesz w artykule Tworzenie dokładnych podglądów z uwzględnieniem elementów dynamicznych.

Wcześniejsza zgodność ze skalowalnymi podglądami widżetów

Aby selektory widżetów na Androidzie 11 (poziom interfejsu API 30) lub niższym mogły wyświetlać podgląd widżetu, określ atrybut previewImage.

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

Dodaj opis widżetu

Począwszy od Androida 12 podaj opis widżetu, który będzie wyświetlany dla Twojego widżetu.

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

Podaj opis widżetu, używając atrybutu description elementu <appwidget-provider>:

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

Uwaga: tekst powinien być 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.

Możesz używać atrybutu descriptionRes w poprzednich wersjach Androida, ale jest on ignorowany przez selektor widżetów.

Włącz płynniejsze przejścia

Począwszy od Androida 12 programy uruchamiające zapewniają płynniejsze przejście, gdy użytkownik uruchamia aplikację z poziomu widżetu.

Aby umożliwić to ulepszone przejście, użyj właściwości @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 trampolinów do transmisji na żywo. Począwszy od Androida 12 aplikacja nadal może uruchamiać aktywność odbiornika lub usługi, jeśli została ona zainicjowana z kliknięcia PendingIntent widżetu. Nowe animacje nie są jednak używane w przypadku aplikacji uruchamianych przez odbiornik lub usługę, co pogarsza wrażenia użytkowników.

Twoja aplikacja może używać @android:id/background w poprzednich wersjach Androida bez awarii, ale jest ona 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.

Poniższy przykładowy kod 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);