Как использовать виджеты подборок

Как создать письмо
Jetpack Compose – это рекомендуемый набор инструментов для создания интерфейсов Android. Узнайте, как создавать виджеты с помощью API в стиле Compose.
Jetpack Glance →

Виджеты коллекций предназначены для отображения большого количества однотипных элементов, например фотографий из галереи, статей из новостного приложения или сообщений из приложения для общения. Обычно они используются в двух случаях: для просмотра коллекции и для открытия элемента коллекции в подробном представлении. Виджеты коллекций можно прокручивать по вертикали.

Эти виджеты используют RemoteViewsService для показа коллекций, которые основаны на удаленных данных, например от поставщика контента. Виджет представляет данные в одном из следующих типов представлений, которые называются представлениями коллекций:

ListView – представление, в котором элементы показываются в списке с вертикальной прокруткой.

GridView – представление, в котором элементы показываются в двумерной прокручиваемой сетке.

StackView – стопка карточек, похожая на ролодекс. Пользователь может сдвигать верхнюю карточку вверх или вниз, чтобы увидеть предыдущую или следующую карточку соответственно.

AdapterViewFlipper – ViewAnimator с поддержкой адаптера, который анимирует переход между двумя или более представлениями. За раз показывается только один ребенок.

Поскольку эти представления коллекций отображают коллекции, основанные на удаленных данных, они используют Adapter для связывания пользовательского интерфейса с данными. Adapter связывает отдельные элементы из набора данных с отдельными объектами View.

Поскольку эти представления коллекций поддерживаются адаптерами, фреймворк Android должен включать дополнительную архитектуру для поддержки их использования в виджетах. В контексте виджета Adapter заменяется на RemoteViewsFactory, который представляет собой тонкую оболочку вокруг интерфейса Adapter. Когда пользователь запрашивает определенный объект из коллекции, RemoteViewsFactory создает и возвращает объект коллекции в виде объекта RemoteViews. Чтобы добавить в виджет представление коллекции, реализуйте RemoteViewsService и RemoteViewsFactory.

RemoteViewsService – это сервис, который позволяет удаленному адаптеру запрашивать объекты RemoteViews. RemoteViewsFactory – это интерфейс для адаптера между представлением коллекции, например ListView, GridView и StackView, и базовыми данными для этого представления. Ниже приведен пример шаблонного кода для реализации этого сервиса и интерфейса на основе StackWidget образца:

class StackWidgetService : RemoteViewsService() {
    override fun onGetViewFactory(intent: Intent): RemoteViewsFactory =
        StackRemoteViewsFactory(this.applicationContext, intent)
}

class StackRemoteViewsFactory(
    private val context: Context, intent: Intent
) : RemoteViewsService.RemoteViewsFactory {

    // See the RemoteViewsFactory API reference for the full list of methods to implement.

}

Пример приложения

Фрагменты кода в этом разделе также взяты из StackWidget примера:

Виджет StackWidget, в котором показываются вертикально расположенные представления
Рисунок 1. A StackWidget.

Этот пример состоит из стека из десяти представлений, в которых отображаются значения от нуля до девяти. Пример виджета имеет следующие основные функции:

  • Пользователь может провести пальцем по верхнему представлению в виджете, чтобы показать следующее или предыдущее представление. Это встроенное поведение StackView.

  • Без каких-либо действий со стороны пользователя виджет автоматически переходит к следующему изображению, как слайд-шоу. Это связано с настройкой android:autoAdvanceViewId="@id/stack_view" в файле res/xml/stackwidgetinfo.xml. Этот параметр применяется к идентификатору представления, который в данном случае является идентификатором представления стека.

  • Если пользователь нажмет на верхнее представление, в виджете появится сообщение Toast "Нажато представление n", где n – индекс (позиция) представления, на которое было нажато. Подробнее о том, как реализовать поведение, рассказывается в разделе Как добавить поведение к отдельным элементам.

Как реализовать виджеты с подборками

Чтобы добавить в виджет коллекции, выполните инструкции по реализации любого виджета, а затем выполните несколько дополнительных действий: измените манифест, добавьте в макет виджета представление коллекции и измените подкласс AppWidgetProvider.

Манифест для виджетов с подборками

Помимо требований, перечисленных в разделе Как объявить виджет в файле манифеста, вам нужно сделать так, чтобы виджеты с коллекциями могли подключаться к приложению "RemoteViewsService". Для этого объявите сервис в файле манифеста с разрешением BIND_REMOTEVIEWS. Это не позволит другим приложениям свободно получать доступ к данным вашего виджета.

Например, при создании виджета, который использует RemoteViewsService для заполнения представления коллекции, запись в манифесте может выглядеть следующим образом:

<service android:name="MyWidgetService"
    android:permission="android.permission.BIND_REMOTEVIEWS" />

В этом примере android:name="MyWidgetService" относится к вашему подклассу RemoteViewsService.

Макет для виджетов с подборками

Основное требование к XML-файлу макета виджета – наличие одного из представлений коллекции: ListView, GridView, StackView или AdapterViewFlipper. Вот файл widget_layout.xml для примера StackWidget sample:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <StackView
        android:id="@+id/stack_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:gravity="center"
        android:loopViews="true" />
    <TextView
        android:id="@+id/empty_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:gravity="center"
        android:background="@drawable/widget_item_background"
        android:textColor="#ffffff"
        android:textStyle="bold"
        android:text="@string/empty_view_text"
        android:textSize="20sp" />
</FrameLayout>

Обратите внимание, что пустые представления должны быть дочерними элементами представления коллекции, для которого они представляют пустое состояние.

Помимо файла макета для всего виджета, создайте ещё один файл макета, в котором будет задан макет для каждого элемента коллекции, например для каждой книги в коллекции книг. В примере StackWidget есть только один файл макета элемента, widget_item.xml, поскольку все элементы используют один и тот же макет.

Класс AppWidgetProvider для виджетов с коллекциями

Как и в случае с обычными виджетами, большая часть кода в подклассе AppWidgetProvider обычно находится в onUpdate(). Основное отличие при создании виджета с коллекциями для onUpdate() заключается в том, что вам нужно вызвать setRemoteAdapter(). Это позволяет представлению коллекции получать данные. После этого RemoteViewsService может вернуть вашу реализацию RemoteViewsFactory, и виджет сможет показывать нужные данные. При вызове этого метода передайте намерение, указывающее на реализацию RemoteViewsService, и идентификатор виджета, который нужно обновить.

Например, в приведенном ниже фрагменте кода показано, как в образце StackWidget реализован метод обратного вызова onUpdate() для настройки RemoteViewsService в качестве удаленного адаптера для коллекции виджетов:

override fun onUpdate(
    context: Context, appWidgetManager: AppWidgetManager, appWidgetIds: IntArray
) {
    // Update each of the widgets with the remote adapter.
    appWidgetIds.forEach { appWidgetId ->

        // Set up the intent that starts the StackViewService, which
        // provides the views for this collection.
        val intent = Intent(context, StackWidgetService::class.java).apply {
            // Add the widget ID to the intent extras.
            putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
            data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME))
        }
        // Instantiate the RemoteViews object for the widget layout.
        val views = RemoteViews(context.packageName, R.layout.widget_layout).apply {
            // Set up the RemoteViews object to use a RemoteViews adapter.
            // This adapter connects to a RemoteViewsService through the
            // specified intent.
            // This is how you populate the data.
            setRemoteAdapter(R.id.stack_view, intent)

            // The empty view is displayed when the collection has no items.
            // It must be in the same layout used to instantiate the
            // RemoteViews object.
            setEmptyView(R.id.stack_view, R.id.empty_view)
        }

        // Do additional processing specific to this widget.

        appWidgetManager.updateAppWidget(appWidgetId, views)
    }
    super.onUpdate(context, appWidgetManager, appWidgetIds)
}

Как сохранять данные

Как описано на этой странице, подкласс RemoteViewsService предоставляет RemoteViewsFactory, используемый для заполнения представления удаленной коллекции.

Выполните следующие действия:

  1. Подкласс RemoteViewsService. RemoteViewsService – это сервис, через который удаленный адаптер может запросить RemoteViews.

  2. В подкласс RemoteViewsService включите класс, реализующий интерфейс RemoteViewsFactory. RemoteViewsFactory – это интерфейс для адаптера между удаленным представлением коллекции, например ListView, GridView, StackView, и базовыми данными для этого представления. Ваша реализация должна создавать объект RemoteViews для каждого элемента набора данных. Этот интерфейс представляет собой тонкую оболочку вокруг Adapter.

Нельзя полагаться на то, что отдельный экземпляр сервиса или содержащиеся в нем данные будут сохранены. Не храните в RemoteViewsService данные, которые могут измениться. Если вы хотите, чтобы данные виджета сохранялись, лучше всего использовать ContentProvider, данные которого сохраняются после завершения процесса. Например, виджет продуктового магазина может хранить состояние каждого элемента списка покупок в постоянном месте, таком как база данных SQL.

Основное содержимое реализации RemoteViewsService – это RemoteViewsFactory, описанный в следующем разделе.

Интерфейс RemoteViewsFactory

Ваш специальный класс, реализующий интерфейс RemoteViewsFactory, предоставляет виджету данные для элементов в его коллекции. Для этого он объединяет XML-файл макета элемента виджета с источником данных. Источник данных может быть любым, от базы данных до массива. В StackWidgetпримере источник данных представляет собой массив WidgetItems. Функция RemoteViewsFactory выступает в качестве адаптера, который связывает данные с удаленным представлением коллекции.

Два самых важных метода, которые необходимо реализовать для подкласса RemoteViewsFactory, – это onCreate() и getViewAt().

Система вызывает onCreate() при первом создании фабрики. Здесь вы можете настроить подключения или курсоры к источнику данных. Например, в образце StackWidget используется onCreate() для инициализации массива объектов WidgetItem. Когда виджет активен, система получает доступ к этим объектам, используя их индекс в массиве, и показывает содержащийся в них текст.

Ниже приведен фрагмент реализации метода onCreate() из примера StackWidget RemoteViewsFactory:

private const val REMOTE_VIEW_COUNT: Int = 10

class StackRemoteViewsFactory(
    private val context: Context
) : RemoteViewsService.RemoteViewsFactory {

    private lateinit var widgetItems: List<WidgetItem>

    override fun onCreate() {
        // In onCreate(), set up any connections or cursors to your data
        // source. Heavy lifting, such as downloading or creating content,
        // must be deferred to onDataSetChanged() or getViewAt(). Taking
        // more than 20 seconds on this call results in an ANR.
        widgetItems = List(REMOTE_VIEW_COUNT) { index -> WidgetItem("$index!") }
    }

}

Метод RemoteViewsFactory getViewAt() возвращает объект RemoteViews, соответствующий данным в указанном position набора данных. Ниже приведен фрагмент кода из примера StackWidget, в котором реализован тег RemoteViewsFactory:

override fun getViewAt(position: Int): RemoteViews {
    // Construct a remote views item based on the widget item XML file
    // and set the text based on the position.
    return RemoteViews(context.packageName, R.layout.widget_item).apply {
        setTextViewText(R.id.widget_item, widgetItems[position].text)
    }
}

Как добавить поведение для отдельных объектов

В предыдущих разделах рассказывается, как привязать данные к коллекции виджетов. Но что, если вы хотите добавить динамическое поведение отдельным элементам в представлении коллекции?

Как описано в разделе Обработка событий с помощью класса onUpdate(), обычно для настройки поведения объекта при нажатии, например для того, чтобы кнопка запускала Activity, используется setOnClickPendingIntent(). Однако такой подход не допускается для дочерних представлений в отдельном элементе коллекции. Например, с помощью setOnClickPendingIntent() можно настроить глобальную кнопку в виджете Gmail, которая запускает приложение, но не отдельные элементы списка.

Чтобы добавить поведение при клике на отдельные объекты в коллекции, используйте setOnClickFillInIntent(). Настройте шаблон отложенного намерения для представления коллекции и задайте намерение заполнения для каждого элемента коллекции, используя RemoteViewsFactory.

В этом разделе на примере StackWidget показано, как добавить поведение к отдельным элементам. В примере StackWidget, если пользователь коснется верхнего представления, виджет отобразит сообщение Toast "Коснулись представления n", где n – это индекс (позиция) представления, которого коснулся пользователь. Вот как это работает.

  • Класс StackWidgetProvider, являющийся подклассом AppWidgetProvider, создает отложенное намерение с пользовательским действием TOAST_ACTION.

  • Когда пользователь нажимает на представление, запускается намерение и транслируется TOAST_ACTION.

  • Этот широковещательный запрос перехватывается методом onReceive() класса StackWidgetProvider, и виджет отображает сообщение Toast для представления, к которому было совершено прикосновение. Данные для элементов коллекции предоставляются RemoteViewsFactory через RemoteViewsService.

Как настроить шаблон незавершенного действия

Класс StackWidgetProvider (подкласс AppWidgetProvider) создает ожидающее намерение. Отдельные элементы коллекции не могут настраивать собственные ожидающие намерения. Вместо этого коллекция в целом задает шаблон отложенного намерения, а отдельные элементы задают намерение заполнения, чтобы создать уникальное поведение для каждого элемента.

Этот класс также получает широковещательное сообщение, отправленное, когда пользователь касается представления. Он обрабатывает это событие в своем методе onReceive(). Если действие намерения – TOAST_ACTION, виджет показывает сообщение Toast для текущего представления.

const val TOAST_ACTION = "com.example.android.stackwidget.TOAST_ACTION"
const val EXTRA_ITEM = "com.example.android.stackwidget.EXTRA_ITEM"

class StackWidgetProvider : AppWidgetProvider() {

    // ...

    // Called when the BroadcastReceiver receives an Intent broadcast.
    // Checks whether the intent's action is TOAST_ACTION. If it is, the
    // widget displays a Toast message for the current item.
    override fun onReceive(context: Context, intent: Intent) {
        val mgr: AppWidgetManager = AppWidgetManager.getInstance(context)
        if (intent.action == TOAST_ACTION) {
            val appWidgetId: Int = intent.getIntExtra(
                AppWidgetManager.EXTRA_APPWIDGET_ID,
                AppWidgetManager.INVALID_APPWIDGET_ID
            )
            // EXTRA_ITEM represents a custom value provided by the Intent
            // passed to the setOnClickFillInIntent() method to indicate the
            // position of the clicked item. See StackRemoteViewsFactory in
            // Set the fill-in Intent for details.
            val viewIndex: Int = intent.getIntExtra(EXTRA_ITEM, 0)
            Toast.makeText(context, "Touched view $viewIndex", Toast.LENGTH_SHORT).show()
        }
        super.onReceive(context, intent)
    }

    override fun onUpdate(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetIds: IntArray
    ) {
        // Update each of the widgets with the remote adapter.
        appWidgetIds.forEach { appWidgetId ->

            // Sets up the intent that points to the StackViewService that
            // provides the views for this collection.
            val intent = Intent(context, StackWidgetService::class.java).apply {
                putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
                // When intents are compared, the extras are ignored, so embed
                // the extra sinto the data so that the extras are not ignored.
                data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME))
            }
            val rv = RemoteViews(context.packageName, R.layout.widget_layout).apply {
                setRemoteAdapter(R.id.stack_view, intent)

                // The empty view is displayed when the collection has no items.
                // It must be a sibling of the collection view.
                setEmptyView(R.id.stack_view, R.id.empty_view)
            }

            // This section makes it possible for items to have individualized
            // behavior. It does this by setting up a pending intent template.
            // Individuals items of a collection can't set up their own pending
            // intents. Instead, the collection as a whole sets up a pending
            // intent template, and the individual items set a fillInIntent
            // to create unique behavior on an item-by-item basis.
            val toastPendingIntent: PendingIntent = Intent(
                context,
                StackWidgetProvider::class.java
            ).run {
                // Set the action for the intent.
                // When the user touches a particular view, it has the effect of
                // broadcasting TOAST_ACTION.
                action = TOAST_ACTION
                putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
                data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME))

                // The template must be mutable, because each item fills in its
                // own extras through setOnClickFillInIntent().
                PendingIntent.getBroadcast(
                    context, 0, this,
                    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_MUTABLE
                )
            }
            rv.setPendingIntentTemplate(R.id.stack_view, toastPendingIntent)

            appWidgetManager.updateAppWidget(appWidgetId, rv)
        }
        super.onUpdate(context, appWidgetManager, appWidgetIds)
    }
}

Как задать намерение для заполнения

Ваш RemoteViewsFactory должен задать намерение заполнения для каждого элемента коллекции. Это позволяет различать отдельные действия, выполняемые при нажатии на определенный элемент. Затем заполненное намерение объединяется с шаблоном PendingIntent, чтобы определить окончательное намерение, которое будет выполнено при нажатии на элемент.

private const val REMOTE_VIEW_COUNT: Int = 10

class StackRemoteViewsFactory(
    private val context: Context,
    intent: Intent
) : RemoteViewsService.RemoteViewsFactory {

    private lateinit var widgetItems: List<WidgetItem>
    private val appWidgetId: Int = intent.getIntExtra(
        AppWidgetManager.EXTRA_APPWIDGET_ID,
        AppWidgetManager.INVALID_APPWIDGET_ID
    )

    override fun onCreate() {
        // In onCreate(), set up any connections or cursors to your data source.
        // Heavy lifting, such as downloading or creating content, must be
        // deferred to onDataSetChanged() or getViewAt(). Taking more than 20
        // seconds on this call results in an ANR.
        widgetItems = List(REMOTE_VIEW_COUNT) { index -> WidgetItem("$index!") }
        // ...
    }

    // ...

    override fun getViewAt(position: Int): RemoteViews {
        // Construct a remote views item based on the widget item XML file
        // and set the text based on the position.
        return RemoteViews(context.packageName, R.layout.widget_item).apply {
            setTextViewText(R.id.widget_item, widgetItems[position].text)

            // Set a fill-intent to fill in the pending intent template.
            // that is set on the collection view in StackWidgetProvider.
            val fillInIntent = Intent().apply {
                Bundle().also { extras ->
                    extras.putInt(EXTRA_ITEM, position)
                    putExtras(extras)
                }
            }
            // Make it possible to distinguish the individual on-click
            // action of a given item.
            setOnClickFillInIntent(R.id.widget_item, fillInIntent)
            // ...
        }
    }
    // ...
}

Как поддерживать актуальность данных в подборках

На рисунке 2 показан процесс обновления в виджете, который использует коллекции. На ней показано, как код виджета взаимодействует с RemoteViewsFactory и как можно запускать обновления:

Взаимодействие с RemoteViewsFactory во время обновлений
Рисунок 2. Взаимодействие с RemoteViewsFactory во время обновлений.

Виджеты, использующие подборки, могут предоставлять пользователям актуальный контент. Например, виджет Gmail позволяет пользователям просматривать содержимое почтового ящика. Чтобы это стало возможным, активируйте RemoteViewsFactory и представление коллекции, чтобы получить и отобразить новые данные.

Для этого вместо метода AppWidgetManager вызовите метод notifyAppWidgetViewDataChanged(). Этот вызов приводит к обратному вызову метода onDataSetChanged() объекта RemoteViewsFactory, который позволяет получить новые данные.

Вы можете выполнять ресурсоемкие операции синхронно в функции обратного вызова onDataSetChanged(). Этот вызов завершается до того, как метаданные или данные представления будут получены из RemoteViewsFactory. Вы также можете выполнять ресурсоемкие операции в методе getViewAt(). Если этот вызов занимает много времени, в соответствующей позиции представления коллекции отображается представление загрузки, заданное методом getLoadingView() объекта RemoteViewsFactory, пока не будет получен ответ.

Используйте RemoteCollectionItems, чтобы передавать коллекции напрямую.

В Android 12 (уровень API 31) добавлен метод setRemoteAdapter(int viewId, RemoteViews.RemoteCollectionItems items), который позволяет приложению передавать коллекцию напрямую при заполнении представления коллекции. Если вы настроили адаптер этим способом, вам не нужно реализовывать RemoteViewsFactory и вызывать notifyAppWidgetViewDataChanged().

Этот подход не только упрощает заполнение адаптера, но и устраняет задержку при добавлении новых элементов, когда пользователь прокручивает список. Этот способ настройки адаптера предпочтительнее, если у вас относительно небольшой набор элементов коллекции. Однако такой подход не подойдет, если в вашей коллекции много объектов Bitmaps, которые передаются в setImageViewBitmap.

Если в коллекции не используется постоянный набор макетов, то есть некоторые элементы присутствуют не всегда, используйте параметр setViewTypeCount, чтобы указать максимальное количество уникальных макетов, которые могут быть в коллекции. Это позволяет повторно использовать адаптер при обновлении виджета приложения.

Ниже приведен пример того, как реализовать упрощенные коллекции RemoteViews.

val itemLayouts = listOf(
    R.layout.item_type_1,
    R.layout.item_type_2,
    // ...
)

remoteView.setRemoteAdapter(
    R.id.list_view,
    RemoteViews.RemoteCollectionItems.Builder()
        .addItem(/* id= */ ID_1, RemoteViews(context.packageName, R.layout.item_type_1))
        .addItem(/* id= */ ID_2, RemoteViews(context.packageName, R.layout.item_type_2))
        // ...
        .setViewTypeCount(itemLayouts.count())
        .build()
)