Создайте простой виджет

Попробуйте способ создания композиций.

Jetpack Compose — рекомендуемый набор инструментов для создания пользовательского интерфейса для Android. Узнайте, как создавать виджеты, используя API в стиле Compose.

Взгляд с реактивного ранца →

Виджеты приложений — это миниатюрные представления приложений, которые можно встраивать в другие приложения, например, на главный экран, и получать периодические обновления. В пользовательском интерфейсе эти представления называются виджетами , и вы можете опубликовать один из них с помощью поставщика виджетов приложения (или поставщика виджетов ). Компонент приложения, содержащий другие виджеты, называется хостом виджетов приложения (или хостом виджетов ). На рисунке 1 показан пример музыкального виджета:

Рисунок 1. Пример музыкального виджета.

В этом документе описывается, как опубликовать виджет с помощью поставщика виджетов. Подробную информацию о создании собственного AppWidgetHost для размещения виджетов приложения см. в разделе «Создание хоста виджетов» .

Информацию о том, как создать виджет, см. в разделе «Обзор виджетов приложений» .

Компоненты виджетов

Для создания виджета вам потребуются следующие основные компоненты:

Объект AppWidgetProviderInfo

Описывает метаданные виджета, такие как макет виджета, частота обновления и класс AppWidgetProvider . AppWidgetProviderInfo определяется в XML , как описано в этом документе.

класс AppWidgetProvider

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

Просмотреть макет

Определяет начальную компоновку виджета. Компоновка задается в формате XML , как описано в этом документе.

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

Рисунок 2. Схема обработки виджета приложения.

Примечание: Android Studio может автоматически создать набор файлов AppWidgetProviderInfo , AppWidgetProvider и макета представления. Выберите New > Widget > App Widget .

Если вашему виджету требуется настройка пользователем, реализуйте действие настройки виджета приложения. Это действие позволяет пользователям изменять параметры виджета — например, часовой пояс для виджета часов.

• Начиная с Android 12 (уровень API 31), вы можете задать конфигурацию по умолчанию и позволить пользователям изменить конфигурацию виджета позже. Дополнительные сведения см. в разделах «Использование конфигурации виджета по умолчанию» и «Предоставление пользователям возможности изменять конфигурацию размещенных виджетов» .
• В Android 11 (уровень API 30) или более ранних версиях это действие запускается каждый раз, когда пользователь добавляет виджет на главный экран.

Мы также рекомендуем следующие улучшения: гибкая компоновка виджетов , различные усовершенствования , расширенные виджеты , виджеты-коллекции и создание хоста для виджетов .

Объявите XML-файл AppWidgetProviderInfo.

Настройка параметров метаданных (таких как размеры ячеек по умолчанию, ограничения на изменение размера и частота обновления) абсолютно одинакова как для традиционных виджетов Views, так и для виджетов на основе Glance.

Чтобы узнать, как определить и настроить XML-файл метаданных, см. раздел «Объявление XML-файла AppWidgetProviderInfo в Compose-first» в документации Glance.

Для обработки широковещательных сообщений виджетов используйте класс AppWidgetProvider.

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

Чтобы понять, как зарегистрировать приемник в манифесте и реализовать переопределения жизненного цикла, совместимые с Hilt, см. раздел «Использование класса AppWidgetProvider для обработки широковещательных сообщений» в документации Glance, посвященный подходу Compose-first.

Создайте макет виджета

Необходимо задать начальный макет для вашего виджета в формате XML и сохранить его в каталоге res/layout/ проекта. Подробности см. в разделе «Рекомендации по дизайну» .

Создание макета виджета не представляет сложности, если вы знакомы с макетами . Однако имейте в виду, что макеты виджетов основаны на RemoteViews , который не поддерживает все типы макетов или виджетов представления. Вы не можете использовать пользовательские представления или подклассы представлений, поддерживаемых RemoteViews .

RemoteViews также поддерживает ViewStub , который представляет собой невидимый View нулевого размера, который можно использовать для отложенного создания ресурсов макета во время выполнения.

Поддержка поведения, сохраняющего состояние

В Android 12 добавлена ​​поддержка управления состоянием с использованием следующих существующих компонентов:

• CheckBox

• Switch

• RadioButton

Виджет по-прежнему не имеет состояния. Ваше приложение должно хранить состояние и регистрироваться для событий изменения состояния.

Рисунок 3. Пример поведения, сохраняющего состояние.

Примечание: Всегда явно устанавливайте текущее состояние флажка с помощью RemoteViews.setCompoundButtonChecked , иначе вы можете столкнуться с неожиданными результатами при перетаскивании или изменении размера виджета.

В следующем примере кода показано, как реализовать эти компоненты.

Котлин

// 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)
)

Java

// 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));

Предоставьте два варианта оформления: один для устройств под управлением Android 12 или выше (папка res/layout-v31 , а другой для устройств под управлением Android 11 или ниже (папка res/layout по умолчанию).

Примените закругленные углы.

Расчет внешнего фонового и внутреннего пропорциональных радиусов является стандартным и общим. В разработке с использованием Compose-first это можно динамически задавать в Kotlin вместе с пользовательскими ресурсами темы.

Чтобы реализовать скругленные углы или настроить динамические стили для старых устройств Android, см. раздел «Реализация скругленных углов в Compose-first» в документации Glance.