הצגת עדכונים תקופתיים במשבצות

ליצור רכיבים מוטמעים עם תוכן שמשתנה ככל שעובר הזמן.

עבודה עם ציר זמן

ציר זמן מורכב ממופע אחד או יותר של TimelineEntry, שכל אחד מהם מכיל פריסה שמוצגת במהלך מרווח זמן ספציפי. כל כרטיסי המידע צריכים להיות ממוקמים על ציר זמן.

משבצות עם כניסה יחידה

לרוב אפשר לתאר משבצת שידור באמצעות TimelineEntry אחד. הפריסה קבועה, ורק המידע בתוך הפריסה משתנה. לדוגמה, אם יש לכם כרטיס שמציג את התקדמות הכושר שלכם באותו היום, הוא תמיד יציג את אותו פריסת התקדמות, למרות שאתם יכולים לשנות את הפריסה כדי להציג ערכים שונים. במקרים האלה, אי אפשר לדעת מראש מתי התוכן עשוי להשתנות.

לדוגמה, אריח עם 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

אירועים בציר הזמן עם שעות התחלה וסיום

אפשר להגדיר TimelineEntry עם תקופת תוקף, כך שהפריסה של המשבצת תשתנה בזמן ידוע בלי שהאפליקציה תצטרך לשלוח משבצת חדשה.

הדוגמה הקנונית היא משבצת של סדר יום שציר הזמן שלה מכיל רשימה של אירועים קרובים. כל אירוע קרוב מכיל תקופת תוקף שמציינת מתי להציג אותו.

ממשק ה-API של המשבצות מאפשר תקופות תוקף חופפות, והמסך עם התקופה הקצרה ביותר שנותרה הוא זה שמוצג. רק אירוע אחד מוצג בכל פעם.

מפתחים יכולים לספק רשומת ברירת מחדל לגיבוי. לדוגמה, יכול להיות שלמשבצת של סדר היום יש משבצת עם תקופת תוקף אינסופית, שמשמשת אם אין רשומה אחרת בציר הזמן שתקפה, כמו שמוצג בדוגמת הקוד הבאה:

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

רענון של כרטיס מידע

יכול להיות שהתוקף של המידע שמוצג במשבצת יפוג אחרי פרק זמן מסוים. לדוגמה, משבצת מזג אוויר שמציגה את אותה טמפרטורה לאורך כל היום לא מדויקת.

כדי לטפל בנתונים שתוקפם פג, צריך להגדיר מרווח עדכון כשיוצרים את המשבצת. המרווח הזה מציין כמה זמן המשבצת תקפה. בדוגמה של משבצת מזג האוויר, יכול להיות שתעדכנו את התוכן שלה כל שעה, כמו שמוצג בדוגמת הקוד הבאה:

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

כשמגדירים מרווח רענון, המערכת קוראת ל-onTileRequest() זמן קצר אחרי שהמרווח מסתיים. אם לא מגדירים מרווח רענון, המערכת לא קוראת ל-onTileRequest().

התוקף של משבצת יכול לפוג גם בגלל אירוע חיצוני. לדוגמה, משתמש יכול להסיר פגישה מהיומן שלו, ואם המשבצת לא תרענן, הפגישה שהוסרה עדיין תופיע בה. במקרה כזה, אפשר לבקש רענון מכל מקום בקוד האפליקציה, כמו בדוגמת הקוד הבאה:

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

בחירת תהליך עבודה לעדכון

השיטות המומלצות הבאות יעזרו לכם להבין איך להגדיר את העדכונים של המשבצות:

• אם העדכון צפוי – לדוגמה, אם הוא מתייחס לאירוע הבא ביומן של המשתמש – כדאי להשתמש בציר זמן.
• כשמאחזרים נתוני פלטפורמה, כדאי להשתמש בקישור נתונים כדי שהמערכת תעדכן את הנתונים באופן אוטומטי.

• אם אפשר לחשב את העדכון במכשיר תוך זמן קצר – למשל, עדכון המיקום של תמונה במשבצת של זריחת השמש – צריך להשתמש ב-onTileRequest().

  האפשרות הזו שימושית במיוחד כשצריך ליצור את כל התמונות מראש. אם תצטרכו ליצור תמונה חדשה בעתיד, תוכלו להתקשר אל setFreshnessIntervalMillis().

• אם אתם מבצעים שוב ושוב עבודת רקע אינטנסיבית יותר, כמו שליחת שאילתות לנתוני מזג האוויר, השתמשו ב-WorkManager ודחפו עדכונים לאריח.

• אם העדכון הוא בתגובה לאירוע חיצוני – כמו הדלקת האורות, קבלת אימייל או עדכון של הערה – שולחים הודעה של Firebase Cloud Messaging ‏ (FCM) כדי להפעיל מחדש את האפליקציה, ואז דוחפים עדכונים לאריח.

• אם תהליך סנכרון הנתונים של האריח עלול להיות יקר, כדאי לבצע את הפעולות הבאות:

  1. לתזמן סנכרון נתונים.
  2. מפעילים טיימר למשך שנייה אחת או שתיים.
  3. אם מתקבל עדכון ממקור נתונים מרוחק לפני שהזמן הקצוב לתפוגה מסתיים, הערך המעודכן מוצג מסנכרון הנתונים. אחרת, יוצג ערך מקומי שנשמר במטמון.