Начните работу с виджетами

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

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

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

Для работы Wear Widgets на целевом устройстве требуется версия 1.6.1 или выше APK-файла com.google.android.wearable.protolayout.renderer .

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

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

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

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

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

Библиотеки Wear Widget доступны в 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-alpha18"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha18"
    implementation "androidx.glance.wear:wear:1.0.0-alpha17"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha17"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha10"

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

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

    // Tooling for previews (optional, but recommended)
    implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha18")
    implementation("androidx.wear.compose:compose-ui-tooling:1.6.2")
    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(HelloWidget::class)
class HelloWidgetService : GlanceWearWidgetService() {
    override val widget: GlanceWearWidget = HelloWidget()
}
GetStarted.kt

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

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

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

Определите содержание

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

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

Предварительный просмотр виджета в Android Studio

Вы можете предварительно просмотреть макеты виджетов непосредственно на панели «Дизайн» в 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,
    )
}
GetStarted.kt

Создайте 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>
hello_widget_info.xml

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

Атрибут previewImage элемента <container> ссылается на ресурс drawable, отображаемый в системном средстве выбора виджетов. Для генерации ресурсов предварительного просмотра с правильными границами и плотностью используйте Android Studio Previews с параметром 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,
    )
}
GetStarted.kt

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

1. В Android Studio откройте панель дизайна для элемента предварительного просмотра.
2. В окне предварительного просмотра щелкните правой кнопкой мыши по полученному изображению или воспользуйтесь панелью инструментов предварительного просмотра, чтобы выбрать «Копировать изображение» или сохранить изображение. В качестве альтернативы, используйте инструменты командной строки или автоматизированные скрипты для извлечения изображений из окна 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>
AndroidManifest.xml

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

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

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

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

./gradlew :app:installDebug

Добавьте и просмотрите свой виджет.

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

Примечание: Wear Widgets используют базовую инфраструктуру тайлов для целей отладки. В результате команды 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