Управление версиями плиток

На устройствах Wear OS плитки отображаются с помощью двух ключевых компонентов с независимым управлением версиями. Чтобы плитки ваших приложений работали правильно на всех устройствах, важно понимать эту базовую архитектуру.

  • Библиотеки, связанные с плитками Jetpack . Эти библиотеки (включая Wear Tiles и Wear ProtoLayout) встроены в ваше приложение, и вы, как разработчик, контролируете их версии. Ваше приложение использует эти библиотеки для создания объекта TileBuilder.Tile (структуры данных, представляющей ваш Tile) в ответ на системный вызов onTileRequest() .
  • ProtoLayout Renderer: этот системный компонент отвечает за отображение объекта Tile на дисплее и обработку взаимодействия с пользователем. Версия средства визуализации не контролируется разработчиком приложения и может различаться на разных устройствах, даже с одинаковым оборудованием.

Внешний вид или поведение плитки может различаться в зависимости от версии библиотеки Jetpack Tiles вашего приложения и версии средства визуализации ProtoLayout на устройстве пользователя. Например, одно устройство может поддерживать вращение или отображение данных о частоте пульса, а другое — нет.

В этом документе объясняется, как обеспечить совместимость вашего приложения с различными версиями библиотеки Tiles и ProtoLayout Renderer, а также как перейти на более высокие версии библиотеки Jetpack.

Учитывайте совместимость

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

Определить версию рендерера

  • Используйте метод getRendererSchemaVersion() объекта DeviceParameters , переданного в ваш метод onTileRequest() . Этот метод возвращает основной и дополнительный номера версий средства визуализации ProtoLayout на устройстве.
  • Затем вы можете использовать условную логику в реализации onTileRequest() чтобы адаптировать дизайн или поведение вашего Tile на основе обнаруженной версии средства визуализации.
    • Например, если определенная анимация не поддерживается, вместо нее можно отобразить статическое изображение.

Аннотация @RequiresSchemaVersion

  • Аннотация @RequiresSchemaVersion в методах ProtoLayout указывает минимальную версию схемы отрисовки, необходимую для того, чтобы этот метод вел себя как документировано ( пример ).
    • Хотя вызов метода, требующего более высокой версии средства визуализации, чем доступна на устройстве, не приведет к сбою вашего приложения, это может привести к тому, что контент не будет отображаться или функция будет проигнорирована.

Пример 

override fun onTileRequest(
    requestParams: TileService.TileRequest
): ListenableFuture<Tile> {
    val rendererVersion =
        requestParams.deviceConfiguration.rendererSchemaVersion
    val tile = Tile.Builder()

    if (
        rendererVersion.major > 1 ||
            (rendererVersion.major == 1 && rendererVersion.minor >= 300)
    ) {
        // Use a feature supported in renderer version 1.300 or later
        tile.setTileTimeline(/* ... */ )
    } else {
        // Provide fallback content for older renderers
        tile.setTileTimeline(/* ... */ )
    }

    return Futures.immediateFuture(tile.build())
}

Тестируйте разные версии рендеринга

Чтобы протестировать плитки на разных версиях средства визуализации, разверните их в разных версиях эмулятора Wear OS. (На физических устройствах обновления ProtoLayout Renderer доставляются из Play Store или системных обновлений. Невозможно принудительно установить определенную версию средства визуализации.)

Функция предварительного просмотра плитки в Android Studio использует средство рендеринга, встроенное в библиотеку Jetpack ProtoLayout, от которой зависит ваш код, поэтому другой подход — зависеть от разных версий библиотеки Jetpack при тестировании плиток.

Обновите библиотеки Jetpack

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

Переход на Tiles 1.2/ProtoLayout 1.0

Начиная с версии 1.2, большинство API макетов Tiles находятся в пространстве имен androidx.wear.protolayout . Чтобы использовать новейшие API, выполните следующие шаги миграции в своем коде.

Обновить зависимости

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

классный 

  // Remove
  implementation 'androidx.wear.tiles:tiles-material:version'

  // Include additional dependencies
  implementation "androidx.wear.protolayout:protolayout:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-material:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-expression:1.2.1"

  // Update
  implementation "androidx.wear.tiles:tiles:1.4.1"

Котлин 

  // Remove
  implementation("androidx.wear.tiles:tiles-material:version")

  // Include additional dependencies
  implementation("androidx.wear.protolayout:protolayout:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-material:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-expression:1.2.1")

  // Update
  implementation("androidx.wear.tiles:tiles:1.4.1")

Обновить пространства имен

В файлах кода вашего приложения на основе Kotlin и Java внесите следующие обновления. Альтернативно вы можете выполнить этот скрипт переименования пространства имен .

  1. Замените весь импорт androidx.wear.tiles.material.* на androidx.wear.protolayout.material.* . Выполните этот шаг и для библиотеки androidx.wear.tiles.material.layouts .

  2. Замените большую часть импорта androidx.wear.tiles.* на androidx.wear.protolayout.* .

    Импорт для androidx.wear.tiles.EventBuilders , androidx.wear.tiles.RequestBuilders , androidx.wear.tiles.TileBuilders и androidx.wear.tiles.TileService должен остаться прежним.

  3. Переименуйте несколько устаревших методов классов TileService и TileBuilder:

    1. TileBuilders : getTimeline() для getTileTimeline() и setTimeline() для setTileTimeline()
    2. TileService : onResourcesRequest() до onTileResourcesRequest()
    3. RequestBuilders.TileRequest : getDeviceParameters() для getDeviceConfiguration() , setDeviceParameters() для setDeviceConfiguration() , getState() для getCurrentState() и setState() для setCurrentState()
{% дословно %} {% дословно %}