Obsługa wersji płytek

Na urządzeniach z Wear OS kafelki są renderowane przez 2 kluczowe komponenty z niezależnym wersjonowaniem. Aby mieć pewność, że kafelki aplikacji działają prawidłowo na wszystkich urządzeniach, musisz zrozumieć tę podstawową architekturę.

  • Biblioteki związane z kafelkami Jetpacka: te biblioteki (w tym Wear Tiles i Wear ProtoLayout) są osadzone w aplikacji, a Ty jako deweloper kontrolujesz ich wersje. Aplikacja używa tych bibliotek do tworzenia obiektu TileBuilder.Tile (struktury danych reprezentującej kartę) w odpowiedzi na wywołanie onTileRequest() systemu.
  • ProtoLayout Renderer: ten komponent systemu odpowiada za renderowanie obiektu Tile na ekranie i zarządzanie interakcjami użytkownika. Wersja renderera nie jest kontrolowana przez dewelopera aplikacji i może się różnić na różnych urządzeniach, nawet tych z identycznym sprzętem.

Wygląd i zachowanie kafelka mogą się różnić w zależności od wersji biblioteki Jetpack Tiles w aplikacji oraz wersji interfejsu ProtoLayout Renderer na urządzeniu użytkownika. Na przykład jedno urządzenie może obsługiwać obrót lub wyświetlanie danych o tętnie, a drugie nie.

Z tego dokumentu dowiesz się, jak zapewnić zgodność aplikacji z różnymi wersjami biblioteki Tiles i renderowania ProtoLayout oraz jak przejść na nowsze wersje biblioteki Jetpack.

Zgodność

Aby utworzyć kafelek, który działa prawidłowo na różnych urządzeniach, weź pod uwagę te kwestie.

Wykrywanie wersji renderera

  • Użyj metody getRendererSchemaVersion() obiektu DeviceParameters przekazanego do metody onTileRequest(). Ta metoda zwraca główne i mniejsze numery wersji interfejsu API ProtoLayout na urządzeniu.
  • Następnie możesz użyć logiki warunkowej w implementacji onTileRequest(), aby dostosować wygląd lub działanie kafelka na podstawie wykrytej wersji renderera.
    • Jeśli na przykład dana animacja nie jest obsługiwana, możesz wyświetlić obraz statyczny.

Adnotacja @RequiresSchemaVersion

  • Adnotacja @RequiresSchemaVersion przy metodzie ProtoLayout wskazuje minimalną wersję schematu renderera wymaganą, aby ta metoda działała zgodnie z opisem (przykład).
    • Mimo że wywołanie metody, która wymaga nowszej wersji renderera niż ta dostępna na urządzeniu, nie spowoduje awarii aplikacji, może spowodować, że treści nie będą wyświetlane lub funkcja zostanie zignorowana.

Przykład

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())
}

Testowanie z różnymi wersjami silnika

Aby przetestować kafelki w różnych wersjach silnika renderowania, wdrocz je w różnych wersjach emulatora Wear OS. (Na urządzeniach fizycznych aktualizacje biblioteki ProtoLayout Renderer są dostarczane przez Sklep Play lub aktualizacje systemu. Nie można wymusić instalacji konkretnej wersji silnika.

Funkcja podglądu kafelków w Android Studio korzysta z renderowania wbudowanego w bibliotece Jetpack ProtoLayout, na której opiera się kod. Innym podejściem jest korzystanie z różnych wersji biblioteki Jetpack podczas testowania kafelków.

Uaktualnianie bibliotek Jetpacka

Zaktualizuj biblioteki Jetpack Tile, aby korzystać z najnowszych ulepszeń, w tym zmian interfejsu, które umożliwiają płynną integrację kafelków z systemem.

Migracja do wersji 1.2 usługi Tiles lub ProtoLayout 1.0

Od wersji 1.2 większość interfejsów API układu kafelków znajduje się w przestrzeni nazw androidx.wear.protolayout. Aby korzystać z najnowszych interfejsów API, wykonaj w kodu te czynności związane z migracją.

Aktualizowanie zależności

W pliku kompilacji modułu aplikacji wprowadź te zmiany:

Groovy

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

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

Aktualizowanie przestrzeni nazw

W plikach kodu Kotlina i Javę w aplikacji wprowadź te zmiany. Możesz też uruchomić ten skrypt do zmiany nazwy przestrzeni nazw.

  1. Zastąp wszystkie importowane dane androidx.wear.tiles.material.* elementem androidx.wear.protolayout.material.*. Wykonaj ten krok również w przypadku biblioteki androidx.wear.tiles.material.layouts.

  2. Zastąp większość innych importowanych ontologii androidx.wear.tiles.* ontologią androidx.wear.protolayout.*.

    Importy dotyczące zasad androidx.wear.tiles.EventBuilders, androidx.wear.tiles.RequestBuilders, androidx.wear.tiles.TileBuilders i androidx.wear.tiles.TileService powinny pozostać bez zmian.

  3. Zmieniono nazwy kilku przestarzałych metod z klas TileService i TileBuilder:

    1. TileBuilders: getTimeline() to getTileTimeline(), a setTimeline() to setTileTimeline()
    2. TileService: z onResourcesRequest() na onTileResourcesRequest()
    3. RequestBuilders.TileRequest: getDeviceParameters() zmieni się na getDeviceConfiguration(), setDeviceParameters() na setDeviceConfiguration(), getState() na getCurrentState(), a setState() na setCurrentState()