Versionsverwaltung für Ansichten

Auf Wear OS-Geräten werden Kacheln von zwei Hauptkomponenten mit unabhängiger Versionierung gerendert. Damit die App-Kacheln auf allen Geräten ordnungsgemäß funktionieren, ist es wichtig, diese zugrunde liegende Architektur zu verstehen.

  • Jetpack-Bibliotheken für Ansichten: Diese Bibliotheken (einschließlich Wear Tiles und Wear ProtoLayout) sind in Ihre App eingebettet und Sie als Entwickler steuern ihre Versionen. Ihre App verwendet diese Bibliotheken, um als Reaktion auf den onTileRequest()-Aufruf des Systems ein TileBuilder.Tile-Objekt (die Datenstruktur, die Ihre Kachel darstellt) zu erstellen.
  • ProtoLayout-Renderer:Diese Systemkomponente ist für das Rendern des Tile-Objekts auf dem Display und die Verarbeitung von Nutzerinteraktionen verantwortlich. Die Version des Renderers wird nicht vom App-Entwickler gesteuert und kann von Gerät zu Gerät variieren, auch bei identischer Hardware.

Das Aussehen oder Verhalten einer Kachel kann sowohl von den Jetpack Tiles-Bibliotheksversionen Ihrer App als auch von der ProtoLayout-Renderer-Version auf dem Gerät des Nutzers abhängen. So kann ein Gerät beispielsweise die Drehung oder die Anzeige von Herzfrequenzdaten unterstützen, ein anderes Gerät aber nicht.

In diesem Dokument wird beschrieben, wie Sie dafür sorgen, dass Ihre App mit verschiedenen Versionen der Tiles-Bibliothek und des ProtoLayout-Renderers kompatibel ist, und wie Sie zu höheren Versionen der Jetpack-Bibliothek migrieren.

Kompatibilität berücksichtigen

Wenn Sie eine Kachel erstellen möchten, die auf verschiedenen Geräten ordnungsgemäß funktioniert, sollten Sie Folgendes beachten:

Rendererversion erkennen

  • Verwenden Sie die Methode getRendererSchemaVersion() des DeviceParameters-Objekts, das an die Methode onTileRequest() übergeben wird. Diese Methode gibt die Haupt- und Nebenversionsnummern des ProtoLayout-Renderers auf dem Gerät zurück.
  • Sie können dann in Ihrer onTileRequest()-Implementierung bedingte Logik verwenden, um das Design oder Verhalten der Kachel basierend auf der erkannten Rendererversion anzupassen.
    • Wenn eine bestimmte Animation beispielsweise nicht unterstützt wird, können Sie stattdessen ein statisches Bild anzeigen.

Die @RequiresSchemaVersion-Anmerkung

  • Die @RequiresSchemaVersion-Anmerkung bei ProtoLayout-Methoden gibt die Mindestversion des Renderer-Schemas an, die erforderlich ist, damit sich diese Methode wie beschrieben verhält (Beispiel).
    • Wenn Sie eine Methode aufrufen, für die eine höhere Rendererversion erforderlich ist als auf dem Gerät verfügbar ist, stürzt Ihre App zwar nicht ab, aber es kann dazu führen, dass Inhalte nicht angezeigt oder die Funktion ignoriert wird.

Verwendungsbeispiele

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

Mit verschiedenen Rendererversionen testen

Wenn Sie Ihre Ansichten mit verschiedenen Rendererversionen testen möchten, müssen Sie sie in verschiedenen Versionen des Wear OS-Emulators bereitstellen. Auf physischen Geräten werden ProtoLayout-Renderer-Updates über den Play Store oder Systemupdates bereitgestellt. Es ist nicht möglich, die Installation einer bestimmten Rendererversion zu erzwingen.)

Die Funktion „Vorschau für Ansichten“ in Android Studio verwendet einen Renderer, der in der Jetpack ProtoLayout-Bibliothek eingebettet ist, von der Ihr Code abhängt. Ein anderer Ansatz besteht darin, beim Testen von Ansichten verschiedene Jetpack-Bibliotheksversionen zu verwenden.

Jetpack-Bibliotheken aktualisieren

Aktualisieren Sie Ihre Jetpack Tile-Bibliotheken, um die neuesten Verbesserungen zu nutzen, einschließlich UI-Änderungen, damit sich Ihre Kacheln nahtlos in das System einbinden lassen.

Zu Ansichten 1.2 / ProtoLayout 1.0 migrieren

Ab Version 1.2 befinden sich die meisten APIs für das Layout von Ansichten im Namespace androidx.wear.protolayout. Wenn Sie die neuesten APIs verwenden möchten, führen Sie die folgenden Migrationsschritte in Ihrem Code aus.

Abhängigkeiten aktualisieren

Nehmen Sie in der Build-Datei Ihres App-Moduls die folgenden Änderungen vor:

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

Namespaces aktualisieren

Nehmen Sie in den Kotlin- und Java-basierten Codedateien Ihrer App die folgenden Änderungen vor. Alternativ können Sie dieses Script zum Umbenennen von Namespaces ausführen.

  1. Ersetzen Sie alle androidx.wear.tiles.material.*-Importe durch androidx.wear.protolayout.material.*. Führen Sie diesen Schritt auch für die Bibliothek androidx.wear.tiles.material.layouts aus.

  2. Ersetzen Sie die meisten anderen androidx.wear.tiles.*-Importe durch androidx.wear.protolayout.*.

    Importe für androidx.wear.tiles.EventBuilders, androidx.wear.tiles.RequestBuilders, androidx.wear.tiles.TileBuilders und androidx.wear.tiles.TileService sollten unverändert bleiben.

  3. Einige veraltete Methoden aus den Klassen „TileService“ und „TileBuilder“ wurden umbenannt:

    1. TileBuilders: getTimeline() bis getTileTimeline() und setTimeline() bis setTileTimeline()
    2. TileService – alter Preis: onResourcesRequest(), neuer Preis: onTileResourcesRequest()
    3. RequestBuilders.TileRequest: getDeviceParameters() bis getDeviceConfiguration(), setDeviceParameters() bis setDeviceConfiguration(), getState() bis getCurrentState() und setState() bis setCurrentState()