Ulepsz swój widżet

Na tej stronie znajdziesz szczegółowe informacje o opcjonalnych ulepszeniach widżetów dostępnych w Androidzie 12 (poziom interfejsu API 31). Te funkcje są opcjonalne, ale można w prosty sposób zaimplementować i ulepszyć widżety użytkowników.

Użyj kolorów dynamicznych

Począwszy 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ść między różnymi widżetami.

Dynamiczne kolory można uzyskać na dwa 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 Komponenty na Androida (dostępnej od Material Material na Androida w wersji 1.6.0).

Po ustawieniu motywu w układzie głównym możesz użyć popularnych atrybutów kolorów w katalogu głównym lub dowolnym z jego elementów podrzędnych, aby pobrać kolory dynamiczne.

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

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

W przykładzie poniżej z motywem Material 3 kolor motywu urządzenia to „fioletowy”. Kolor uzupełniający i tło widżetu dostosowują się do trybów jasnego i ciemnego, jak widać na ilustracji 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>

Zgodność wsteczna w przypadku kolorów dynamicznych

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

Oto przykład z wykorzystaniem motywu Material 3:

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

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

<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 pozwalają Asystentowi Google wyświetlać widżety w odpowiedzi na odpowiednie polecenia głosowe użytkownika. Gdy skonfigurujesz widżet reagowania na intencje wbudowane, aplikacja może aktywnie wyświetlać widżety na platformach Asystenta, takich jak Android i Android Auto. Użytkownicy mogą przypinać widżety wyświetlane przez Asystenta do programu uruchamiającego, co pozwala zwiększyć zaangażowanie w przyszłości.

Możesz na przykład skonfigurować widżet podsumowania treningów dla aplikacji Ćwiczenie tak, aby wydawał polecenia głosowe użytkownika, które uruchamiają GET_EXERCISE_OBSERVATION BII. Gdy użytkownicy aktywują ten BII, Asystent aktywnie wyświetla Twój widżet, np. mówiąc „OK Google, ile kilometrów udało mi się przebiec w tym tygodniu w ExampleApp?”

Istnieją dziesiątki BII, które obejmują kilka kategorii interakcji użytkowników. Dzięki temu prawie każda aplikacja na Androida ulepsza swoje widżety pod kątem głosu. Więcej informacji znajdziesz w artykule o integrowaniu 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 opisów widżetów.

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

W Androidzie 12 podgląd widżetu wyświetlanego w selektorze widżetów jest skalowalny. Podajesz go jako układ XML z domyślnym rozmiarem widżetu. Wcześniej podgląd widżetu był statycznym zasobem rysowalnym, przez co w niektórych przypadkach podgląd widżetu niedokładnie odzwierciedlał sposób wyświetlania widżetów po dodaniu ich do ekranu głównego.

Aby zaimplementować skalowalne podglądy widżetów, użyj atrybutu previewLayout elementu appwidget-provider, aby udostępnić układ XML:

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

Zalecamy użycie tego samego układu co w widżecie, z realistycznymi wartościami domyślnymi lub testowymi. Większość aplikacji ma te same wartości previewLayout i initialLayout. Wskazówki dotyczące tworzenia precyzyjnych układów podglądu znajdziesz w kolejnej części tej strony.

Zalecamy określenie zarówno atrybutów previewLayout, jak i previewImage, aby aplikacja mogła wrócić do korzystania z 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ądu

Aby zaimplementować 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>

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:

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

• Ustawienie domyślnego lub zastępczego obrazu bądź ikony, np. android:src="@drawable/my_widget_icon", w komponentach 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ć zlokalizowane podglądy.

Zalecane metody w przypadku bardziej złożonych podglądów, które zawierają atrybuty ListView, GridView lub StackView, znajdziesz w artykule Tworzenie dokładnych podglądów zawierających elementy dynamiczne.

Zgodność wsteczna ze skalowalnymi podglądami widżetów

Aby umożliwić selektorom widżetów na Androidzie 11 (poziom interfejsu API 30) lub niższym wyświetlanie podglądu 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 selektora widżetów, które będzie wyświetlane w widżecie.

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

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

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 program uruchamiający zapewnia płynniejsze przejście, gdy użytkownik uruchamia aplikację z widżetu.

Aby włączyć to ulepszone przejście, zidentyfikuj element tła za pomocą @android:id/background lub android.R.id.background:

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

Twoja aplikacja może używać @android:id/background w poprzednich wersjach Androida bez awarii, ale jest ignorowana.

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

Począwszy od Androida 12, można korzystać z kilku metod RemoteViews, które umożliwiają modyfikowanie 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 korzystać z kilku z tych metod.

// 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)

// 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);