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

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

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

ציר זמן מורכב ממופעים אחדים של 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 תקופת תוקף, כדי לאפשר לפריסה של המשבצת להשתנות במועד ידוע, בלי שהאפליקציה תצטרך לדחוף משבצת חדשה.

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

ב-Tiles 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)
}

public void eventDeletedCallback() {
   TileService.getUpdater(context)
           .requestUpdate(MyTileService.class);
}

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

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

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

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

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

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

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

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

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