Dodawanie podglądów do selektora 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.

Wygenerowane podglądy widżetów umożliwiają tworzenie dynamicznych, spersonalizowanych podglądów widżetów, które dokładnie odzwierciedlają sposób, w jaki będą one wyświetlane na ekranie głównym użytkownika. W przypadku Androida 15 i nowszych są one udostępniane za pomocą interfejsu Push API, co oznacza, że aplikacja udostępnia podgląd w dowolnym momencie swojego cyklu życia bez otrzymywania wyraźnego żądania od hosta widżetu.

Więcej informacji znajdziesz w filmie Wzbogać aplikację o aktualizacje na żywo i widżety w YouTube.

Dodawanie wygenerowanych podglądów

Aby wyświetlać podglądy wygenerowanych widżetów na urządzeniu z Androidem 15 lub nowszym, najpierw ustaw wartość compileSdk na 35 lub nowszą w pliku modułu build.gradle, aby mieć możliwość przekazywania wartości RemoteViews do selektora widżetów.

Aplikacje mogą używać setWidgetPreview w AppWidgetManager. Aby zapobiegać nadużyciom i ograniczać problemy ze stanem systemu, setWidgetPreview jest interfejsem API z ograniczeniem liczby żądań. Domyślny limit to około 2 rozmowy na godzinę.

System nie wywołuje zwrotnego wywołania, aby udostępnić podgląd, więc aplikacja musi zdecydować, kiedy wywołać funkcję setWidgetPreviews. Strategia aktualizacji zależy od przypadku użycia widżetu:

  • Jeśli widżet zawiera statyczne informacje lub jest skrótem, ustaw podgląd przy pierwszym uruchomieniu aplikacji.
  • Podgląd możesz ustawić, gdy aplikacja będzie zawierać dane, np. po zalogowaniu się użytkownika lub po początkowej konfiguracji.
  • Możesz skonfigurować okresowe zadanie, aby aktualizować podglądy z wybraną częstotliwością.

Poniższy przykład wczytuje zasób layoutu widżetu XML i ustawia go 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 podglądów widżetów o skalowalnych rozmiarach

Od Androida 12 podgląd widżetu wyświetlany w selektorze widżetów można skalować. Udostępniasz 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ż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 previewLayout i initialLayout. Wskazówki dotyczące tworzenia dokładnych układów podglądu znajdziesz w artykule Tworzenie dokładnych podglądów zawierających elementy dynamiczne.

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.

Dodawanie statycznych podglądów widżetów w celu zapewnienia zgodności wstecznej

Aby selektory widżetów na Androidzie 11 (API na poziomie 30) lub starszym wyświetlały podgląd widżetu lub jako rezerwę dla skalowalnych podglądów, określ atrybut previewImage.

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

Ten atrybut jest też używany jako zastępczy w przypadku wygenerowanych podglądów, jeśli nie ustawisz go za pomocą atrybutu setWidgetPreview.

Tworzenie dokładnych podglądów zawierających elementy dynamiczne

Ilustracja 1. Podgląd widżetu bez elementów listy.

W tej sekcji opisujemy zalecane podejście do wyświetlania wielu elementów w podglądzie widżetu z widokiem kolekcji, czyli widżetu, który korzysta z ListView, GridView lub StackView. Dotyczy to podglądów widżetów skalowalnych, a nie wygenerowanych podglądów.

Jeśli widżet korzysta z jednego z tych widoków, utworzenie skalowalnego podglądu przez podanie rzeczywistego układu widżetu bezpośrednio w previewLayout może pogorszyć komfort użytkowania, gdy podgląd widżetu nie wyświetla żadnych elementów. Dzieje się tak, ponieważ dane widoku kolekcji są ustawiane dynamicznie w czasie działania i wyglądają podobnie do obrazu pokazanego na rysunku 1.

Aby podglądy widżetów z widokami kolekcji wyświetlały się prawidłowo w selektorze widżetów, zalecamy używanie osobnego pliku układu przeznaczonego tylko do podglądu. Ten oddzielny plik układu powinien zawierać:

  • Rzeczywisty układ widżetu.
  • Widok kolekcji z obiektami zastępczymi zawierający przykładowe elementy. Możesz na przykład naśladować ListView, podając obiekt zastępczy LinearLayout z kilkoma fałszywymi elementami listy.

Aby zilustrować przykład ListView, zacznij od osobnego pliku układu:

// res/layout/widget_preview.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
   android:layout_width="match_parent"
   android:layout_height="wrap_content"
   android:background="@drawable/widget_background"
   android:orientation="vertical">

    // Include the actual widget layout that contains ListView.
    <include
        layout="@layout/widget_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    // The number of fake items you include depends on the values you provide
    // for minHeight or targetCellHeight in the AppWidgetProviderInfo
    // definition.

    <TextView android:text="@string/fake_item1"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

    <TextView android:text="@string/fake_item2"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

</LinearLayout>

Określ plik układu podglądu, podając atrybut previewLayout metadanych AppWidgetProviderInfo. Nadal określasz rzeczywisty układ widżetu dla atrybutu initialLayout i używasz rzeczywistego układu widżetu podczas tworzenia RemoteViews w czasie działania.

<appwidget-provider
    previewLayout="@layout/widget_preview"
    initialLayout="@layout/widget_view" />

Złożone elementy listy

W przykładzie w poprzedniej sekcji podano przykładowe elementy listy, ponieważ elementy listy są obiektami TextView. W przypadku złożonych układów dostarczanie fałszywych elementów może być trudniejsze.

Rozważmy element listy zdefiniowany w widget_list_item.xml, który składa się z 2 obiektów TextView:

<LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">

    <TextView android:id="@id/title"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/fake_title" />

    <TextView android:id="@id/content"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/fake_content" />
</LinearLayout>

Aby podać fałszywe elementy listy, możesz uwzględnić układ wiele razy, ale spowoduje to, że każdy element listy będzie identyczny. Aby podać unikalne elementy listy, wykonaj te czynności:

  1. Utwórz zestaw atrybutów dla wartości tekstowych:

    <resources>
    <attr name="widgetTitle" format="string" />
    <attr name="widgetContent" format="string" />
</resources>

  2. Aby ustawić tekst, użyj tych atrybutów:

    <LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">

    <TextView android:id="@id/title"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="?widgetTitle" />

    <TextView android:id="@id/content"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="?widgetContent" />
</LinearLayout>

  3. Utwórz tyle stylów, ile jest potrzebnych do podglądu. Zdefiniuj ponownie wartości w każdym stylu:

    <resources>

    <style name="Theme.Widget.ListItem">
        <item name="widgetTitle"></item>
        <item name="widgetContent"></item>
    </style>
    <style name="Theme.Widget.ListItem.Preview1">
        <item name="widgetTitle">Fake Title 1</item>
        <item name="widgetContent">Fake content 1</item>
    </style>
    <style name="Theme.Widget.ListItem.Preview2">
        <item name="widgetTitle">Fake title 2</item>
        <item name="widgetContent">Fake content 2</item>
    </style>

</resources>

  4. Zastosuj style do fałszywych produktów w układzie podglądu:

    <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
   android:layout_width="match_parent"
   android:layout_height="wrap_content" ...>

    <include layout="@layout/widget_view" ... />

    <include layout="@layout/widget_list_item"
        android:theme="@style/Theme.Widget.ListItem.Preview1" />

    <include layout="@layout/widget_list_item"
        android:theme="@style/Theme.Widget.ListItem.Preview2" />

</LinearLayout>