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

Aby ulepszyć selektor widżetów w aplikacji, udostępnij wygenerowany podgląd widżetu na urządzeniach z Androidem 15 lub nowszym, przeskalowany podgląd widżetu (przez określenie previewLayout) na urządzeniach z Androidem 12–14 oraz previewImage na urządzeniach z wcześniejszymi wersjami.

Wygenerowane podglądy widżetów umożliwiają tworzenie dynamicznych, spersonalizowanych podglądów widżetów, które dokładnie odzwierciedlają ich wygląd na ekranie głównym użytkownika. W przypadku Androida 15 i nowszych są one udostępniane przez interfejs push API, co oznacza, że aplikacja udostępnia podgląd w dowolnym momencie cyklu życia bez otrzymywania wyraźnego żądania od hosta widżetu.

Więcej informacji znajdziesz w filmie Enrich your app with aktualizacje na żywo and widżety na YouTube.

Dodaj wygenerowane podglądy

Aby wyświetlać wygenerowane podglądy widżetów na urządzeniu z Androidem 15 lub nowszym, najpierw ustaw wartość compileSdk na 35 lub wyższą w pliku modułu build.gradle, aby móc przekazywać RemoteViews do selektora widżetów.

Aplikacje mogą używać setWidgetPreview w AppWidgetManager. Aby zapobiegać nadużyciom i ograniczać problemy ze stanem systemu, interfejs API setWidgetPreview ma ograniczenie liczby żądań. Domyślny limit to około 2 połączenia na godzinę.

System nie udostępnia wywołania zwrotnego do wyświetlania podglądów, więc aplikacja musi zdecydować, kiedy wywołać setWidgetPreviews. Strategia aktualizacji zależy od przypadku użycia widżetu:

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

Ten przykład wczytuje zasób układu widżetu XML i ustawia go jako podgląd. Aby metoda setWidgetPreview była widoczna 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)
)

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

Od Androida 12 podgląd widżetu wyświetlany w selektorze widżetów jest skalowalny. Udostępniasz go jako układ XML ustawiony na domyślny rozmiar widżetu. Wcześniej podgląd widżetu był statycznym obiektem 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 udostępnić układ XML:

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

Zalecamy użycie tego samego układu co w przypadku rzeczywistego widżetu, 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 artykule Tworzenie dokładnych podglądów zawierających elementy dynamiczne.

Zalecamy określenie obu atrybutów (previewLayout i previewImage), aby aplikacja mogła używać atrybutu previewImage, jeśli urządzenie użytkownika nie obsługuje atrybutu previewLayout. Atrybut previewLayout ma pierwszeństwo przed atrybutem previewImage.

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

Aby umożliwić selektorom widżetów na Androidzie 11 (poziom API 30) lub starszym wyświetlanie podglądu widżetu, lub jako kreację zastępczą 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 ustawiono go za pomocą setWidgetPreview.

tworzyć dokładne podglądy zawierające 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 używa ListView, GridView lub StackView. Dotyczy to podglądów widżetów skalowalnych, a nie podglądów wygenerowanych.

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ć wrażenia użytkownika, 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 zachowanie osobnego pliku układu przeznaczonego tylko do podglądu. Ten osobny plik układu powinien zawierać:

  • Rzeczywisty układ widżetu.
  • Widok kolekcji obiektów zastępczych z fałszywymi elementami. Możesz na przykład naśladować ListView, podając obiekt zastępczy LinearLayout z kilkoma fałszywymi elementami listy.

Aby zilustrować przykład dla elementu 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>

Podaj 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

Przykład w poprzedniej sekcji zawiera fałszywe elementy listy, ponieważ elementy listy są obiektami TextView. Jeśli elementy mają złożone układy, dostarczanie fałszywych elementów może być bardziej skomplikowane.

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 wielokrotnie uwzględnić układ, 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. Użyj tych atrybutów, aby ustawić tekst:

    <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 potrzebujesz 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 elementów zastępczych 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>