Tworzenie prostego widżetu

Widżety aplikacji to miniaturowe widoki aplikacji, które można umieścić w innych takich jak ekran główny – i otrzymują okresowe aktualizacje. Te nazywa się w interfejsie widżetami. Możesz publikować z dostawcą widżetów aplikacji (lub dostawcą widżetów). Komponent aplikacji, który który zawiera inne widżety, jest nazywany hostem widżetu aplikacji (lub hostem widżetów). Rysunek 1 pokazuje widżet próbki muzyki:

W tym dokumencie opisujemy, jak opublikować widżet, korzystając z jego dostawcy. Dla: szczegółowe informacje o tworzeniu własnego zasobu AppWidgetHost w Więcej informacji o hostowaniu widżetów znajdziesz w artykule Tworzenie hosta widżetów.

Aby dowiedzieć się, jak zaprojektować widżet, zobacz Omówienie widżetów aplikacji.

Komponenty widżetów

Aby utworzyć widżet, potrzebujesz następujących podstawowych komponentów:

AppWidgetProviderInfo obiekt

Opisuje metadane widżetu, np. jego układ, aktualizację częstotliwość i AppWidgetProvider. AppWidgetProviderInfo jest zdefiniowany w pliku XML: opisane w tym dokumencie.

AppWidgetProvider zajęcia

Zdefiniuj podstawowe metody, które umożliwiają programowy interfejs widżet. Dzięki niemu możesz odbierać komunikaty o aktualizacjach widżetu, włączone, wyłączone lub usunięte. Deklarujesz AppWidgetProvider w pliku manifestu, a następnie wdróż go. opisane w tym dokumencie.

Wyświetl układ

Określa początkowy układ widżetu. Układ jest zdefiniowany w XML zgodnie z opisem w tym dokumencie.

Rysunek 2 pokazuje, w jaki sposób te komponenty wpasowują się w ogólny proces przetwarzania widżetów aplikacji przepływu danych.

Jeśli widżet wymaga konfiguracji użytkownika, wdróż konfigurację widżetu aplikacji działania. Ta aktywność pozwala użytkownikom modyfikować ustawienia widżetów, na przykład strefy czasowej w widżecie zegara.

• Począwszy od Androida 12 (poziom interfejsu API 31) możesz określić domyślną wartość i umożliwić użytkownikom ponowne skonfigurowanie widżetu. Patrz sekcja Korzystanie z domyślną konfigurację widżetu i opcję Włącz w celu zmiany konfiguracji umieszczonych widżetów .
• W Androidzie 11 (poziom interfejsu API 30) lub starszym ta aktywność jest uruchamiana za każdym razem doda widżet do ekranu głównego.

Zalecamy też wprowadzenie tych ulepszeń: elastyczne układy widżetów, inne ulepszenia, widżety zaawansowane, widżety kolekcji oraz tworzenie widżetów .

Zadeklarowanie pliku XML AppWidgetProviderInfo

Obiekt AppWidgetProviderInfo określa podstawowe cechy widżetu. Zdefiniuj obiekt AppWidgetProviderInfo w pliku zasobów XML za pomocą jednego <appwidget-provider> i zapisz go w folderze res/xml/ projektu.

Widać to w tym przykładzie:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/example_loading_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

Atrybuty rozmiaru widżetu

Domyślny ekran główny umieszcza widżety w oknie na podstawie siatki komórek o określonej wysokości i szerokości. Większość ekranów głównych pozwala jedynie widżetom rozmiary będące wielokrotnościami całkowitych wielokrotności komórek siatki, np. dwóch komórek. w poziomie o 3 komórki w pionie.

Atrybuty rozmiaru widżetu pozwalają określić domyślny rozmiar widżetu oraz określ dolne i górne granice rozmiaru widżetu. W tym kontekście domyślnym rozmiarem widżetu jest to, kiedy jest otwierany po raz pierwszy dodano do ekranu głównego.

W poniższej tabeli opisano atrybuty <appwidget-provider> dotyczące: do rozmiaru widżetu:

Przykład

Aby pokazać, jak atrybuty z poprzedniej tabeli wpływają na rozmiar widżetu, przy założeniu, że masz taką specyfikację:

• Komórka siatki ma szerokość 30 dp i wysokość 50 dp.
• Podana specyfikacja atrybutów:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

Od Androida 12:

Używaj atrybutów targetCellWidth i targetCellHeight jako domyślnych i wielkości widżetu.

Domyślny rozmiar widżetu to 2 x 2. Widżet można zmniejszyć do rozmiaru 2x1 lub do 4 x 3.

Android 11 i starsze wersje:

Za pomocą atrybutów minWidth i minHeight oblicz domyślny rozmiar w widżecie.

Domyślna szerokość = Math.ceil(80 / 30) = 3

Wysokość domyślna = Math.ceil(80 / 50) = 2

Domyślny rozmiar widżetu to 3 x 2. Widżet można zmniejszyć do rozmiaru 2x1 lub do pełnego ekranu.

Dodatkowe atrybuty widżetu

W poniższej tabeli opisano atrybuty <appwidget-provider> dotyczące: na wartości inne niż dostosowanie rozmiaru widżetu.

Użyj klasy AppWidgetProvider do obsługi komunikatów widżetów

Klasa AppWidgetProvider obsługuje transmisje widżetów i aktualizuje widżet w odpowiedzi na zdarzenia cyklu życia widżetu. W sekcjach poniżej dowiesz się, jak zadeklaruj w pliku manifestu element AppWidgetProvider, a następnie go zaimplementuj.

Zadeklarowanie widżetu w pliku manifestu

Najpierw zadeklaruj klasę AppWidgetProvider w elemencie AndroidManifest.xml aplikacji zgodnie z poniższym przykładem:

<receiver android:name="ExampleAppWidgetProvider"
                 android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />
</receiver>

Element <receiver> wymaga atrybutu android:name, który określa element AppWidgetProvider używany przez widżet. Nie można eksportować komponentu. chyba że do urządzenia AppWidgetProvider trzeba przesłać osobny proces, który zwykle nie jest prawdą.

Element <intent-filter> musi zawierać element <action> z parametrem android:name. Ten atrybut określa, że AppWidgetProvider akceptuje ACTION_APPWIDGET_UPDATE. transmisję. To jedyna transmisja, którą musisz wyraźnie zadeklarować. AppWidgetManager automatycznie wysyła wszystkie inne komunikaty widżetów do AppWidgetProvider jako niezbędną.

Element <meta-data> określa zasób AppWidgetProviderInfo i wymaga następujących atrybutów:

• android:name: określa nazwę metadanych. Używaj android.appwidget.provider, aby zidentyfikować dane jako Deskryptor AppWidgetProviderInfo.
• android:resource: określa zasób AppWidgetProviderInfo lokalizacji.

Implementowanie klasy AppWidgetProvider

Zajęcia AppWidgetProvider obejmują zakres BroadcastReceiver jako klasa wygody do obsługi komunikatów widżetów. Odbiera tylko zdarzenie komunikaty istotne dla widżetu, na przykład informacje o jego aktualizacji, usunięte, włączone i wyłączone. W przypadku wystąpienia tych transmisji: Metody typu AppWidgetProvider są wywoływane:

onUpdate()

Ta funkcja jest wywoływana, aby aktualizować widżet w odstępach określonych przez tag updatePeriodMillis w AppWidgetProviderInfo. Zobacz tabelę opisujących dodatkowe atrybuty widżetu na tej stronie dla znajdziesz więcej informacji.

.

Metoda ta jest również wywoływana, gdy użytkownik dodaje widżet, więc wykonuje niezbędnej konfiguracji, na przykład przez zdefiniowanie modułów obsługi zdarzeń, View lub uruchamianie zadań, do których mają być wczytywane dane wyświetlane w widżecie. Jeśli jednak zadeklarujesz aktywność związaną z konfiguracją bez flagę configuration_optional, ta metoda nie jest wywoływana, gdy użytkownik dodaje widżet, ale jest wymagany przy kolejnych aktualizacjach. Jest to działania konfiguracji za wykonanie pierwszej aktualizacji, gdy zakończono konfigurację. Więcej informacji znajdziesz w artykule Umożliwianie użytkownikom konfigurowania widżetów aplikacji.

.

Najważniejsze wywołanie zwrotne to onUpdate(). Zapoznaj się z sekcją Obsługiwanie zdarzeń za pomocą onUpdate() zajęcia na tej stronie, aby dowiedzieć się więcej.

onAppWidgetOptionsChanged()

Ta funkcja jest wywoływana przy pierwszym umieszczeniu widżetu i przy każdym zamieszczeniu widżetu rozmiar został zmieniony. Użyj tego wywołania zwrotnego, aby wyświetlić lub ukryć treść na podstawie rozmiaru widżetu zakresów. Sprawdź zakresy rozmiarów, a od Androida 12: listę możliwych rozmiarów instancji widżetu – przez wywołanie getAppWidgetOptions() , który zwraca Bundle zawierający :

• OPTION_APPWIDGET_MIN_WIDTH: zawiera dolną granicę szerokości instancji widżetu (w jednostkach dp).
• OPTION_APPWIDGET_MIN_HEIGHT: zawiera dolną granicę wysokości instancji widżetu (w jednostkach dp).
• OPTION_APPWIDGET_MAX_WIDTH: zawiera górną granicę szerokości instancji widżetu (w jednostkach dp).
• OPTION_APPWIDGET_MAX_HEIGHT: zawiera górną granicę wysokości instancji widżetu (w jednostkach dp).
• OPTION_APPWIDGET_SIZES: zawiera listę możliwych rozmiarów (List<SizeF>) w jednostkach dp, które jak w przypadku instancji widżetu. Wprowadzone w Androidzie 12.

onDeleted(Context, int[])

Ta funkcja jest wywoływana za każdym razem, gdy widżet jest usuwany z hosta widżetu.

onEnabled(Context)

Ta funkcja jest wywoływana, gdy wystąpienie widżetu jest tworzone po raz pierwszy. Jeśli na przykład użytkownik doda dwa wystąpienia widżetu, zostanie ona wywołana tylko za pierwszym razem. Jeśli musisz otworzyć nową bazę danych lub przeprowadzić inną konfigurację, musi wystąpić tylko raz dla wszystkich instancji widżetu. Teraz warto aby to zrobić.

onDisabled(Context)

Ta funkcja jest wywoływana, gdy ostatnie wystąpienie widżetu zostanie usunięte z hosta widżetu. Tutaj robisz porządki w aplikacji onEnabled(Context), na przykład przez usunięcie tymczasowej bazy danych.

onReceive(Context, Intent)

Jest ono wywoływane w przypadku każdej transmisji i przed każdym poprzednim wywołaniem zwrotnym . Zwykle nie musisz implementować tej metody, ponieważ domyślna Implementacja AppWidgetProvider filtruje wszystkie komunikaty widżetów i wywołuje metodę poprzednich metod.

Musisz zadeklarować implementację klasy AppWidgetProvider jako transmisję odbiornika za pomocą elementu <receiver> w tabeli AndroidManifest. Przeczytaj sekcję Deklarowanie w pliku manifestu na tej stronie, by dowiedzieć się więcej.

Obsługuj zdarzenia za pomocą klasy onUpdate()

Najważniejsze wywołanie zwrotne AppWidgetProvider to onUpdate(), ponieważ jest jest wywoływana, gdy każdy widżet zostanie dodany do hosta, chyba że zastosujesz konfigurację aktywność bez flagi configuration_optional. Jeśli widżet akceptuje poniższe zdarzenia interakcji użytkownika, a następnie zarejestruj moduły obsługi zdarzeń w tym wywołaniu zwrotnym. Jeśli widżet nie tworzy plików tymczasowych ani baz danych, nie wykonuje też innych działań które wymaga wyczyszczenia, onUpdate() może być jedyną metodą wywołania zwrotnego, do zdefiniowania.

Jeśli na przykład potrzebujesz widżetu z przyciskiem uruchamiającym aktywność, gdy: możesz użyć tej implementacji obiektu AppWidgetProvider:

class ExampleAppWidgetProvider : AppWidgetProvider() {

    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray
    ) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        appWidgetIds.forEach { appWidgetId ->
            // Create an Intent to launch ExampleActivity.
            val pendingIntent: PendingIntent = PendingIntent.getActivity(
                    /* context = */ context,
                    /* requestCode = */  0,
                    /* intent = */ Intent(context, ExampleActivity::class.java),
                    /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
            )

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            val views: RemoteViews = RemoteViews(
                    context.packageName,
                    R.layout.appwidget_provider_layout
            ).apply {
                setOnClickPendingIntent(R.id.button, pendingIntent)
            }

            // Tell the AppWidgetManager to perform an update on the current
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views)
        }
    }
}

public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        for (int i=0; i < appWidgetIds.length; i++) {
            int appWidgetId = appWidgetIds[i];
            // Create an Intent to launch ExampleActivity
            Intent intent = new Intent(context, ExampleActivity.class);
            PendingIntent pendingIntent = PendingIntent.getActivity(
                /* context = */ context,
                /* requestCode = */ 0,
                /* intent = */ intent,
                /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
            );

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget_layout);
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // Tell the AppWidgetManager to perform an update on the current app
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}

Ten element AppWidgetProvider definiuje tylko metodę onUpdate(), wykorzystującą go do utwórz PendingIntent, który uruchamia Activity i dołącza go do widżetu za pomocą przycisku setOnClickPendingIntent(int, PendingIntent). Zawiera pętlę, która powtarza procedurę dla każdego wpisu w funkcji appWidgetIds, która jest tablicą identyfikatorów identyfikujących każdy widżet utworzony przez u tego dostawcy. Jeśli użytkownik utworzy więcej niż jedno wystąpienie widżetu, wszystkie są aktualizowane jednocześnie. Jednak tylko 1 harmonogram updatePeriodMillis jest zarządzana w przypadku wszystkich instancji widżetu. Jeśli na przykład harmonogram aktualizacji jest zdefiniowana co dwie godziny i zostaje dodane drugie wystąpienie widżetu godzinę po pierwszej, są one aktualizowane w okresie określonym przez pierwszy, a drugi jest ignorowany. Obie aktualizują się co 2 razy godzin, a nie co godzinę.

Zobacz ExampleAppWidgetProvider.java przykładową klasę, aby dowiedzieć się więcej.

Odbieranie intencji transmisji widżetu

AppWidgetProvider to zajęcia wygodne. Jeśli chcesz otrzymać widżet bezpośrednio, możesz wdrożyć własne BroadcastReceiver lub zastąpić onReceive(Context,Intent) oddzwanianie. Intencje, na których musisz się skupić, to :

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

Tworzenie układu widżetu

Musisz zdefiniować początkowy układ widżetu w formacie XML i zapisać go w katalogu res/layout/ projektu. Przeczytaj artykuł Projektowanie wytycznych.

Tworzenie układu widżetu jest proste, jeśli znasz układy. Pamiętaj jednak, że ten widżet układy oparte na: RemoteViews, który nie obsługuje wszystkich rodzajów układów lub widżetów. Nie możesz używać niestandardowych ustawień lub podklasy widoków obsługiwanych przez funkcję RemoteViews.

RemoteViews obsługuje też ViewStub, czyli niewidoczny element View o zerowym rozmiarze, którego można używać do leniwego rozszerzania układu zasobów w czasie działania.

Obsługa zachowania stanowego

Android 12 obsługuje zachowania stanowe z użyciem tych elementów: istniejące komponenty:

• CheckBox

• Switch

• RadioButton

Widżet pozostaje bezstanowy. Aplikacja musi przechowywać informacje o stanie i zarejestrować się w usłudze zdarzenia zmiany stanu.

Poniższy przykładowy kod pokazuje, jak wdrożyć te komponenty.

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
        R.id.my_checkbox,
        RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));

Udostępnij 2 układy: 1 kierowanie na urządzenia z Androidem 12 lub wyższy w grupie res/layout-v31, a drugie kierowanie obejmuje poprzednie Android 11 lub starszy w domyślnym folderze res/layout.

Stosuj zaokrąglone rogi.

Android 12 wprowadza te parametry systemowe, aby ustawić promienie zaokrąglonych rogów widżetu:

• system_app_widget_background_radius: promień narożnika tła widżetu, który nigdy nie jest większy niż 28 dp.

• system_app_widget_inner_radius: promienia narożnika dowolnego widoku w widżecie. To dokładnie 8 dp mniejszy niż promień tła, aby zapewnić ładne wyrównanie przy zastosowaniu 8 dp dopełnienie.

Poniższy przykład przedstawia widżet, który używa funkcji system_app_widget_background_radius w rogu widżetu oraz system_app_widget_inner_radius – widoki w widżecie.

1 Róg widżetu.

2 Róg widoku w widżecie.

Ważne informacje o zaokrąglonych rogach

• Programy uruchamiające innych firm oraz producenci urządzeń mogą zastąpić system_app_widget_background_radius parametr musi być mniejszy niż 28 dp. Parametr system_app_widget_inner_radius ma zawsze wartość 8 dp mniejszą niż wartość system_app_widget_background_radius.
• Jeśli widżet nie używa języka @android:id/background lub ma zdefiniowany tło który pozwala wycinać treści na podstawie konspektu – przy użyciu android:clipToOutline ustawiona na true – program uruchamiający automatycznie identyfikuje tło przycina widżet za pomocą prostokąta z zaokrąglonymi rogami do 16 dp. Zapoznaj się z artykułem Sprawdzanie, czy widżet jest zgodny z Android 12.

Aby zapewnić zgodność widżetów z poprzednimi wersjami Androida, zalecamy definiowanie atrybutów niestandardowych i ich zastępowania za pomocą motywu niestandardowego. Androida 12 na przykład w tych przykładowych plikach XML:

<resources>
  <attr name="backgroundRadius" format="dimension" />
</resources>

<resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
</resources>

<resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
</resources>

<shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  ...
</shape>

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:background="@drawable/my_widget_background" />