Ulepsz swój widżet

Wypróbuj Compose

Jetpack Compose to zalecany zestaw narzędzi interfejsu na Androida. Dowiedz się, jak tworzyć widżety za pomocą interfejsów API w stylu Compose.

Jetpack Glance →

Na tej stronie znajdziesz 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 łatwo je wdrożyć i zwiększają wygodę użytkowników widżetu.

Używanie kolorów dynamicznych

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ść w różnych widżetach.

Kolory dynamiczne 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, która jest dostępna od wersji 1.6.0.

Po ustawieniu motywu w układzie głównym możesz używać typowych atrybutów koloru w układzie głównym lub w dowolnym z jego elementów podrzędnych, aby pobierać dynamiczne kolory.

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

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

W tym przykładzie, w którym użyto motywu Material 3, kolor motywu urządzenia to „purpurowy”. Kolor akcentu i tło widżetu dostosowują się do trybów jasnego i ciemnego, jak pokazano na ilustracjach 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 dynamicznych kolorów

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

Oto przykład użycia 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łączanie obsługi głosowej

Działania w aplikacji umożliwiają Asystentowi Google wyświetlanie widżetów w odpowiedzi na odpowiednie polecenia głosowe użytkownika. Konfigurując widżet tak, aby reagował na wbudowane intencje, możesz sprawić, że Twoja aplikacja będzie 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 launchera, co zachęca do dalszego korzystania z tej funkcji.

Możesz na przykład skonfigurować widżet podsumowania treningu w aplikacji do ćwiczeń, aby realizować polecenia głosowe użytkownika, które wywołują interfejs GET_EXERCISE_OBSERVATION BII. Asystent aktywnie wyświetla widżet, gdy użytkownicy wywołują tę wbudowaną intencję, przesyłając żądania takie jak „OK Google, ile kilometrów przebiegłem w tym tygodniu w aplikacji ExampleApp?”.

Istnieją dziesiątki wbudowanych intencji, które obejmują kilka kategorii interakcji użytkownika, dzięki czemu niemal każda aplikacja na Androida może ulepszyć swoje widżety pod kątem obsługi głosowej. Aby rozpocząć, zapoznaj się z artykułem Integrowanie działań w aplikacji z widgetami na Androida.

Ulepszanie selektora widżetów aplikacji

Android 12 umożliwia dodawanie skalowanych podglądów widżetów i ich opisów. Android 15 umożliwia ulepszenie selektora widżetów w aplikacji dzięki wygenerowanym podglądom widżetów.

Aby ulepszyć wybieranie widżetów w aplikacji, udostępnij wygenerowaną podgląd widżetu na urządzeniach z Androidem 15 i nowszym, skalowany podgląd widżetu (określając previewLayout) na urządzeniach z Androidem w wersji od 12 do 14 oraz previewImage w przypadku starszych wersji.

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

Aby aplikacje mogły udostępniać RemoteViews selektorowi widżetów na urządzeniach z Androidem 15 lub nowszym, muszą ustawić wartość compileSdk na 35 lub nowszą w pliku modułu build.gradle. 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 widżetów za pomocą aktualnych i spersonalizowanych informacji.

Generowanie zaktualizowanego podglądu za pomocą Jetpack Glance

Glance.compose wykonuje jedną kompozycję, więc w treści funkcji kompozycyjnej nie są używane funkcje zawieszania, przepływy ani podobne wywołania asynchroniczne. Zamiast tego musisz użyć stałych danych.

W poniższym przykładzie do wygenerowania zaktualizowanego podglądu użyto Jetpack Glance. Aby setWidgetPreview wyświetlało się w tym fragmencie kodu jako metoda, wymagane jest compileSdk ustawienie kompilacji o wartości 35 lub wyższej.

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 korzystać z RemoteViews bez funkcji Glance. W tym przykładzie wczytywany jest zasób układu widżetu XML i ustawiany jako podgląd. Aby setWidgetPreview było widoczne jako metoda w tym fragmencie kodu, ustawienie kompilacji compileSdk musi mieć wartość 35 lub wyższą.

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

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

Od 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 rysowalnym, co w niektórych przypadkach powodowało, że podgląd nie odzwierciedlał dokładnie 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żywanie tego samego układu co rzeczywisty widżet, z realistycznymi wartościami domyślnymi lub testowymi. Większość aplikacji używa tych samych previewLayout i initialLayout. Wskazówki dotyczące tworzenia dokładnych układów podglądu znajdziesz w następnej sekcji na tej stronie.

Zalecamy podanie atrybutów previewLayout i previewImage, aby w przypadku, gdy urządzenie użytkownika nie obsługuje atrybutu previewLayout, aplikacja mogła użyć atrybutu previewImage. 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>

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.

• Ustawianie domyślnego obrazu, ikony lub obrazu zastępczego, 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 możliwość udostępniania zlokalizowanych treści podglądu.

Zalecane podejścia do bardziej złożonych podglądów, które zawierają 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 selektory widżetów na Androidzie 11 (API na poziomie 30) lub starszym wyświetlały podgląd widżetu, określ atrybut previewImage.

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

Dodawanie nazwy widżetu

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

Nazwy widżetów są wczytywane z atrybutu label elementu receiver w pliku AndroidManifest.xml.

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

Dodawanie opisu widżetu

Od Androida 12 podaj opis selektora widżetów, który ma być wyświetlany w przypadku Twojego widżetu.

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

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

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

Włącz płynniejsze przejścia

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

Aby włączyć 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ć uprawnienia @android:id/background w starszych wersjach Androida bez powodowania problemów, ale jest ono ignorowane.

Używanie modyfikacji RemoteViews w czasie działania

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

Poniższy przykładowy kod pokazuje, jak używać niektórych 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);