Как начать работу с виджетами

Предварительные требования и настройка

Прежде чем начать, убедитесь, что ваша среда соответствует перечисленным ниже требованиям.

Требования к среде выполнения

Для виджетов Wear OS на целевом устройстве требуется APK-файл com.google.android.wearable.protolayout.renderer версии 1.6.1 или более поздней.

Получите совместимую версию средства визуализации одним из следующих способов:

  • Эмулятор Wear OS 7. Используйте образ эмулятора Wear OS 7. Версии ниже 7 не подходят. Инструкции по настройке приведены в разделе Как настроить эмулятор Wear OS 7.
  • Физическое устройство. Используйте физическое устройство Wear OS, которое автоматически получает обновления из Google Play, или устройство разработчика, на котором выполнен вход в Google Play.

Чтобы узнать, какая версия установлена на вашем устройстве, используйте следующую команду:

adb shell dumpsys package com.google.android.wearable.protolayout.renderer | \
  grep -m 1 versionName | \
  awk -F= '{print $2}'

Конфигурация Gradle

Библиотеки виджетов Wear доступны в Google Maven.

1. Настроить версию SDK

Убедитесь, что для compileSdk и targetSdk задано значение 37 или выше.

android {
    compileSdk = 37
    // ...
    defaultConfig {
        targetSdk = 37
        // ...
    }
}

2. Добавить зависимости

Добавьте в файл build.gradle.kts своего приложения следующие зависимости:

Яркий

dependencies {
    // Core Wear Widget and Remote Compose libraries
    implementation "androidx.compose.remote:remote-creation-compose:1.0.0-alpha21"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha21"
    implementation "androidx.glance.wear:wear:1.0.0-alpha20"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha20"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha13"

    // Tooling for previews (optional, but recommended)
    implementation "androidx.compose.remote:remote-tooling-preview:1.0.0-alpha21"
    implementation "androidx.wear.compose:compose-ui-tooling:1.7.1"
    implementation "androidx.wear.tiles:tiles-tooling-preview:1.6.2"
    debugImplementation "androidx.wear.tiles:tiles-renderer:1.6.2"
}

Kotlin

dependencies {
    // Core Wear Widget and Remote Compose libraries
    implementation("androidx.compose.remote:remote-creation-compose:1.0.0-alpha21")
    implementation("androidx.compose.remote:remote-core:1.0.0-alpha21")
    implementation("androidx.glance.wear:wear:1.0.0-alpha20")
    implementation("androidx.glance.wear:wear-core:1.0.0-alpha20")
    implementation("androidx.wear.compose.remote:remote-material3:1.0.0-alpha13")

    // Tooling for previews (optional, but recommended)
    implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha21")
    implementation("androidx.wear.compose:compose-ui-tooling:1.7.1")
    implementation("androidx.wear.tiles:tiles-tooling-preview:1.6.2")
    debugImplementation("androidx.wear.tiles:tiles-renderer:1.6.2")
}

Как создать виджет Hello World

Виджет Wear состоит из сервиса, расширяющего GlanceWearWidgetService, и класса виджета, расширяющего GlanceWearWidget. Интерфейс определяется с помощью функций @RemoteComposable.

Определите сервис

Сервис – это точка входа, к которой привязывается система.

Чтобы определить виджет, создайте сервис, который расширяет GlanceWearWidgetService, и добавьте к нему аннотацию @AssociateWithGlanceWearWidget, чтобы связать сервис с нужным классом GlanceWearWidget.

@AssociateWithGlanceWearWidget(HelloWidget::class)
class HelloWidgetService : GlanceWearWidgetService() {
    override val widget: GlanceWearWidget = HelloWidget()
}

Определите виджет

Класс виджета предоставляет данные и макет для виджета.

class HelloWidget : GlanceWearWidget() {
    override suspend fun provideWidgetData(
        context: Context,
        params: WearWidgetParams,
    ): WearWidgetData {
        return WearWidgetDocument(
            background = WearWidgetBrush.color(Color.Blue.rc),
        ) {
            HelloWidgetContent()
        }
    }
}

Определите контент

Контент создается с помощью компонентов Remote Compose.

@RemoteComposable
@Composable
fun HelloWidgetContent() {
    RemoteBox(
        modifier = RemoteModifier.fillMaxSize(),
        contentAlignment = RemoteAlignment.Center,
    ) {
        RemoteText(
            text = "Hello World".rs,
            color = Color.White.rc,
        )
    }
}

Как посмотреть виджет в Android Studio

Вы можете посмотреть макеты виджетов прямо на панели Design (Дизайн) в Android Studio, используя androidx.glance.wear:wear-tooling-preview.

Стандартные наборы для предварительного просмотра

Библиотека wear-tooling-preview предоставляет предопределенные наборы PreviewParameterProvider для тестирования макетов в различных формах контейнеров и конфигурациях устройств:

  • Squircle Suite (SquircleAllWidgetPreviewParams): контейнеры в виде прямоугольников со скругленными углами.
  • Round Suite (RoundAllWidgetPreviewParams): контейнеры в форме таблетки.
  • Прямоугольные (RectangularAllWidgetPreviewParams). Прямоугольные контейнеры без кадрирования с безопасными полями. Изображения, созданные с помощью этой конфигурации, подходят для использования в качестве встроенных в APK изображений предварительного просмотра, используемых средством выбора виджетов (см. раздел Создание объектов изображений предварительного просмотра).

Чтобы посмотреть, как виджет будет выглядеть в Android Studio, используйте @WearWidgetPreview:

@Preview
@Composable
fun HelloWidgetPreview(
    @PreviewParameter(SquircleAllWidgetPreviewParams::class) params: WearWidgetParams,
) {
    WearWidgetPreview(
        widget = HelloWidget(),
        params = params,
    )
}

Создайте XML-файл конфигурации виджета

Создайте файл res/xml/hello_widget_info.xml, чтобы определить свойства виджета и поддерживаемые размеры. Полный список поддерживаемых атрибутов XML в теге <wearwidget-provider> приведен в документации по WearWidgetProviderInfo.

<wearwidget-provider
    description="@string/hello_widget_description"
    icon="@mipmap/ic_launcher"
    label="@string/hello_widget_label"
    preferredType="SMALL">

    <container
        type="SMALL"
        previewImage="@drawable/widget_preview_small" />
    <container
        type="LARGE"
        previewImage="@drawable/widget_preview_large" />
</wearwidget-provider>

Создать объекты изображений для предварительного просмотра

Атрибут previewImage элемента <container> ссылается на графический объект, который показывается в системном виджете выбора. Чтобы сгенерировать объекты для Google Play с правильными границами и плотностью, используйте предварительный просмотр в Android Studio с RectangularAllWidgetPreviewParams (генерирует варианты для маленьких и больших контейнеров) и укажите плотность экрана умных часов 320 DPI:

@Preview(
    name = "Widget Preview Asset",
    device = "spec:width=1000dp,height=1000dp,dpi=320",
)
@Composable
fun HelloWidgetCatalogPreview(
    @PreviewParameter(RectangularAllWidgetPreviewParams::class) params: WearWidgetParams,
) {
    WearWidgetPreview(
        widget = HelloWidget(),
        params = params,
    )
}

Чтобы извлечь обработанные изображения для предварительного просмотра, выполните следующие действия:

  1. В Android Studio откройте область Design (Дизайн) для предварительного просмотра composable-функции.
  2. В окне предварительного просмотра нажмите правой кнопкой мыши на обработанное изображение или выберите Копировать изображение на панели инструментов предварительного просмотра или сохраните изображение. Вы также можете использовать инструменты CLI или автоматизированные скрипты для извлечения предварительных версий Compose.
  3. Сохраните небольшие и большие графические файлы в каталоге res/drawable-nodpi/ вашего приложения, например res/drawable-nodpi/widget_preview_small.png и res/drawable-nodpi/widget_preview_large.png.

Регистрация в AndroidManifest.xml

Зарегистрируйте сервис в файле AndroidManifest.xml с необходимыми фильтрами интентов и метаданными.

<service
    android:name=".snippets.widget.HelloWidgetService"
    android:exported="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/hello_widget_label"
    android:permission="com.google.android.wearable.permission.BIND_TILE_PROVIDER">

    <intent-filter>
        <action android:name="androidx.glance.wear.action.BIND_WIDGET_PROVIDER" />
        <!-- If you already have a Tile, omit the following line. -->
        <action android:name="androidx.wear.tiles.action.BIND_TILE_PROVIDER" />
    </intent-filter>

    <meta-data
        android:name="androidx.glance.wear.widget.provider"
        android:resource="@xml/hello_widget_info" />

    <meta-data
        android:name="androidx.wear.tiles.PREVIEW"
        android:resource="@drawable/tile_preview" />
</service>

Сборка и развертывание

После определения сервиса и виджета вы можете создать проект и развернуть его на устройстве или в эмуляторе.

Сборка и установка

Скомпилируйте проект и установите отладочный APK-файл на подключенное устройство или эмулятор:

./gradlew :app:installDebug

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

После установки приложения используйте adb, чтобы программно добавить виджет в карусель и показать его на экране.

Примечание. Виджеты Wear используют базовую инфраструктуру карточек для отладки. В результате для команд adb требуются операции add-tile и show-tile.

1. Добавьте виджет в карусель:

adb shell am broadcast \
  -a com.google.android.wearable.app.DEBUG_SURFACE \
  --es operation add-tile \
  --ecn component <your_package_name>/.HelloWidgetService

2. Показать виджет.

adb shell am broadcast \
  -a com.google.android.wearable.app.DEBUG_SYSUI \
  --es operation show-tile \
  --ei index 0

Как программно обновлять контент виджета

Когда данные приложения меняются (например, при синхронизации, получении push-уведомления или действии пользователя), сообщите системе, что нужно обновить контент виджета.

Чтобы запросить обновление для всех активных экземпляров виджета, вызовите triggerUpdateAll в классе виджета:

// Request a content update for all active HelloWidget instances
HelloWidget().triggerUpdateAll(context)

Чтобы обновить определенный экземпляр виджета, не обновляя все активные экземпляры, вызовите triggerUpdate с идентификатором целевого экземпляра.