Regelmäßige Updates in Kacheln anzeigen

Erstellen Sie Kacheln mit Inhalten, die sich im Laufe der Zeit ändern.

Mit Zeitachsen arbeiten

Eine Zeitachse besteht aus einer oder mehreren TimelineEntry -Instanzen, die jeweils ein Layout enthalten, das in einem bestimmten Zeitintervall angezeigt wird. Alle Kacheln benötigen eine Zeitachse.

Kacheln mit einem Eintrag

Oft kann eine Kachel mit einem einzelnen TimelineEntry beschrieben werden. Das Layout ist festgelegt und nur die Informationen im Layout ändern sich. Eine Kachel, die beispielsweise Ihren Fitnessfortschritt des Tages anzeigt, verwendet immer dasselbe Layout. Sie können dieses Layout jedoch so anpassen, dass unterschiedliche Werte angezeigt werden. In diesen Fällen wissen Sie nicht im Voraus, wann sich der Inhalt ändern kann.

Hier sehen Sie ein Beispiel für eine Kachel mit einem einzelnen TimelineEntry:

override fun onTileRequest(
    requestParams: RequestBuilders.TileRequest
): ListenableFuture<Tile?> {
    val tile =
        Tile.Builder()
            .setResourcesVersion(RESOURCES_VERSION)
            // We add a single timeline entry when our layout is fixed, and
            // we don't know in advance when its contents might change.
            .setTileTimeline(Timeline.fromLayoutElement(simpleLayout(this)))
            .build()
    return Futures.immediateFuture(tile)
}
Tile.kt

Zeitgebundene Zeitachseneinträge

Für einen TimelineEntry kann optional ein Gültigkeitszeitraum definiert werden. So kann eine Kachel ihr Layout zu einem bekannten Zeitpunkt ändern, ohne dass die App eine neue Kachel senden muss.

Ein typisches Beispiel ist eine Terminkachel, deren Zeitachse eine Liste anstehender Termine enthält. Jeder anstehende Termin hat einen Gültigkeitszeitraum, der angibt, wann er angezeigt werden soll.

Die Tiles API ermöglicht überlappende Gültigkeitszeiträume. Der Bildschirm mit dem kürzesten verbleibenden Zeitraum wird angezeigt. Es wird immer nur ein Termin angezeigt.

Entwickler können einen Standard-Fallback-Eintrag angeben. Die Terminkachel könnte beispielsweise eine Kachel mit einem unbegrenzten Gültigkeitszeitraum haben, die verwendet wird, wenn kein anderer Zeitachseneintrag gültig ist. Das folgende Codebeispiel zeigt, wie das aussehen kann:

override fun onTileRequest(
    requestParams: RequestBuilders.TileRequest
): ListenableFuture<Tile?> {
    val timeline = Timeline.Builder()

    // Add fallback "no meetings" entry
    // Use the version of TimelineEntry that's in androidx.wear.protolayout.
    timeline.addTimelineEntry(
        TimelineBuilders.TimelineEntry.Builder().setLayout(getNoMeetingsLayout()).build()
    )

    // Retrieve a list of scheduled meetings
    val meetings = MeetingsRepo.getMeetings()
    // Add a timeline entry for each meeting
    meetings.forEach { meeting ->
        timeline.addTimelineEntry(
            TimelineBuilders.TimelineEntry.Builder()
                .setLayout(getMeetingLayout(meeting))
                .setValidity(
                    // The tile should disappear when the meeting begins
                    // Use the version of TimeInterval that's in
                    // androidx.wear.protolayout.
                    TimelineBuilders.TimeInterval.Builder()
                        .setEndMillis(meeting.dateTimeMillis)
                        .build()
                )
                .build()
        )
    }

    val tile =
        Tile.Builder()
            .setResourcesVersion(RESOURCES_VERSION)
            .setTileTimeline(timeline.build())
            .build()
    return Futures.immediateFuture(tile)
}
Tile.kt

Kachel aktualisieren

Die auf einer Kachel angezeigten Informationen können nach einiger Zeit ablaufen. Eine Wetterkachel, die beispielsweise den ganzen Tag über dieselbe Temperatur anzeigt, ist nicht genau.

Um mit ablaufenden Daten umzugehen, legen Sie beim Erstellen einer Kachel ein Aktualisierungsintervall fest, das angibt, wie lange die Kachel gültig ist. Im Beispiel der Wetterkachel können Sie den Inhalt beispielsweise stündlich aktualisieren, wie im folgenden Codebeispiel gezeigt:

override fun onTileRequest(
    requestParams: RequestBuilders.TileRequest
): ListenableFuture<Tile?> =
    Futures.immediateFuture(
        Tile.Builder()
            .setResourcesVersion(RESOURCES_VERSION)
            .setFreshnessIntervalMillis(60 * 60 * 1000) // 60 minutes
            .setTileTimeline(Timeline.fromLayoutElement(getWeatherLayout()))
            .build()
    )
Tile.kt

Wenn Sie ein Aktualisierungsintervall festlegen, ruft das System onTileRequest() kurz nach Ablauf des Intervalls auf. Wenn Sie kein Aktualisierungsintervall festlegen, ruft das System onTileRequest() nicht auf.

Eine Kachel kann auch aufgrund eines externen Ereignisses ablaufen. Ein Nutzer kann beispielsweise einen Termin aus seinem Kalender entfernen. Wenn die Kachel nicht aktualisiert wurde, wird der gelöschte Termin weiterhin angezeigt. In diesem Fall können Sie eine Aktualisierung von einer beliebigen Stelle im Anwendungscode anfordern, wie im folgenden Codebeispiel gezeigt:

fun eventDeletedCallback() {
     TileService.getUpdater(context)
             .requestUpdate(MyTileService::class.java)
}

Aktualisierungs-Workflow auswählen

Beachten Sie diese Best Practices, um zu bestimmen, wie Sie Ihre Kachelaktualisierungen konfigurieren:

• Wenn die Aktualisierung vorhersehbar ist, z. B. für den nächsten Termin im Kalender des Nutzers, verwenden Sie eine Zeitachse.
• Wenn Sie Plattformdaten abrufen, verwenden Sie die Datenbindung, damit das System die Daten automatisch aktualisiert.

• Wenn die Aktualisierung auf dem Gerät in kurzer Zeit berechnet werden kann, z. B. um die Position eines Bildes auf einer Kachel mit Sonnenaufgang zu aktualisieren, verwenden Sie onTileRequest().

  Das ist besonders nützlich, wenn Sie alle Bilder im Voraus generieren müssen. Wenn Sie zu einem späteren Zeitpunkt ein neues Bild generieren müssen, rufen Sie setFreshnessIntervalMillis() auf.

• Wenn Sie wiederholt intensivere Hintergrundaufgaben ausführen, z. B. um Wetterdaten abzurufen , verwenden Sie WorkManager und senden Sie Aktualisierungen an Ihre Kachel.

• Wenn die Aktualisierung als Reaktion auf ein externes Ereignis erfolgt, z. B. wenn das Licht eingeschaltet wird, eine E-Mail eingeht oder eine Notiz aktualisiert wird, senden Sie eine Firebase Cloud Messaging-Nachricht (FCM), um Ihre App wieder zu aktivieren, und senden Sie dann Aktualisierungen an die Kachel.

• Wenn die Synchronisierung von Kacheldaten aufwendig sein kann, gehen Sie so vor:

  1. Planen Sie eine Datensynchronisierung.
  2. Starten Sie einen Timer für 1–2 Sekunden.
  3. Wenn Sie vor Ablauf der Zeit eine Aktualisierung von einer Remote-Datenquelle erhalten, zeigen Sie den aktualisierten Wert aus der Datensynchronisierung an. Andernfalls zeigen Sie einen im Cache gespeicherten lokalen Wert an.