Pokazuj okresowe aktualizacje w kafelkach

Twórz kafelki z treścią, która zmienia się z upływem czasu.

Praca z osiami czasu

Oś czasu składa się z co najmniej 1 TimelineEntry instancji, z których każda zawiera układ wyświetlany w określonym przedziale czasu. Wszystkie kafelki wymagają osi czasu.

Kafelki z 1 wpisem

Często kafelek można opisać za pomocą 1 instancji TimelineEntry. Układ jest stały, a zmieniają się tylko informacje w nim. Na przykład kafelek, który pokazuje postępy w fitnessie w danym dniu, zawsze wyświetla ten sam układ postępów, chociaż możesz go dostosować, aby wyświetlać inne wartości. W takich przypadkach nie wiesz z góry, kiedy treść może się zmienić.

Oto przykład kafelka z 1 instancją 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

Wpisy na osi czasu ograniczone czasowo

Instancja TimelineEntry może opcjonalnie definiować okres ważności, co pozwala kafelkowi zmieniać układ w znanym czasie bez konieczności wysyłania przez aplikację nowego kafelka.

Typowym przykładem jest kafelek kalendarza, którego oś czasu zawiera listę nadchodzących wydarzeń. Każde nadchodzące wydarzenie zawiera okres ważności, który wskazuje, kiedy ma się wyświetlać.

Interfejs API kafelków umożliwia nakładanie się okresów ważności. W takim przypadku wyświetlany jest ekran z najkrótszym pozostałym okresem ważności. W danym momencie wyświetlane jest tylko 1 wydarzenie.

Deweloperzy mogą podać domyślny wpis rezerwowy. Na przykład kafelek kalendarza może mieć kafelek z nieskończonym okresem ważności, który jest używany, jeśli żaden inny wpis na osi czasu nie jest ważny. Pokazuje to ten przykładowy kod:

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

Odświeżanie kafelka

Informacje wyświetlane na kafelku mogą po pewnym czasie wygasnąć. Na przykład kafelek z pogodą, który przez cały dzień pokazuje tę samą temperaturę, nie jest dokładny.

Aby poradzić sobie z wygasającymi danymi, podczas tworzenia kafelka ustaw interwał odświeżania, który określa, jak długo kafelek jest ważny. W przypadku kafelka z pogodą możesz aktualizować jego zawartość co godzinę, jak pokazano w tym przykładowym kodzie:

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

Gdy ustawisz interwał odświeżania, system wywoła onTileRequest() krótko po jego zakończeniu. Jeśli nie ustawisz interwału odświeżania, system nie wywoła onTileRequest().

Kafelek może też wygasnąć z powodu zdarzenia zewnętrznego. Na przykład użytkownik może usunąć spotkanie z kalendarza, a jeśli kafelek nie zostanie odświeżony, nadal będzie wyświetlać usunięte spotkanie. W takim przypadku poproś o odświeżenie z dowolnego miejsca w kodzie aplikacji, jak pokazano w tym przykładowym kodzie:

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

Wybieranie przepływu pracy aktualizacji

Aby określić, jak skonfigurować aktualizacje kafelków, stosuj te sprawdzone metody:

• Jeśli aktualizacja jest przewidywalna – np. dotyczy następnego wydarzenia w kalendarzu użytkownika – użyj osi czasu.
• Gdy pobierasz dane platformy, używaj powiązania danych, aby system automatycznie aktualizował dane.

• Jeśli aktualizację można obliczyć na urządzeniu w krótkim czasie – np. zaktualizować położenie obrazu na kafelku wschodu słońca – użyj onTileRequest().

  Jest to szczególnie przydatne, gdy musisz wygenerować wszystkie obrazy z wyprzedzeniem. Jeśli musisz wygenerować nowy obraz w przyszłości, wywołaj setFreshnessIntervalMillis().

• Jeśli wykonujesz intensywną pracę w tle, np. sprawdzasz dane pogodowe, użyj WorkManager i wysyłaj aktualizacje do kafelka.

• Jeśli aktualizacja jest odpowiedzią na zdarzenie zewnętrzne – np. włączenie świateł lub otrzymanie e-maila lub zaktualizowanie notatki – wyślij wiadomość z Komunikacji w chmurze Firebase (FCM), aby ponownie aktywować aplikację, a następnie wysłać aktualizacje do kafelka.

• Jeśli proces synchronizacji danych kafelka może być kosztowny, wykonaj te czynności:

  1. Zaplanuj synchronizację danych.
  2. Ustaw timer na 1–2 sekundy.
  3. Jeśli przed upływem czasu otrzymasz aktualizację ze zdalnego źródła danych, wyświetl zaktualizowaną wartość z synchronizacji danych. W przeciwnym razie wyświetl wartość lokalną z pamięci podręcznej.