نمایش به‌روزرسانی‌های دوره‌ای در کاشی‌ها

کاشی‌هایی با محتوایی که با گذشت زمان تغییر می‌کند ایجاد کنید.

کار با خطوط زمان

خط زمان از یک یا چند نمونه 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 می‌تواند به‌صورت اختیاری دوره اعتبار را تعریف کند و به کاشی اجازه دهد چیدمانش را در زمان مشخصی تغییر دهد بدون اینکه برنامه نیاز به ارسال کاشی جدید داشته باشد.

نمونه متعارف کاشی دستور جلسه است که خط زمان آن حاوی فهرستی از رویدادهای آتی است. هر رویداد آتی حاوی دوره اعتبار است که نشان می‌دهد چه زمانی باید نمایش داده شود.

میانای برنامه‌سازی کاربردی کاشی‌ها امکان دوره‌های اعتبار هم‌پوشانی را فراهم می‌کند، به‌طوری‌که صفحه‌نمایش با کوتاه‌ترین دوره زمانی باقی‌مانده نمایش داده می‌شود. هر بار فقط یک رویداد نمایش داده می‌شود.

توسعه‌دهندگان می‌توانند ورودی برگشت پیش‌فرضی ارائه دهند. برای مثال، کاشی دستور کار می‌تواند کاشی‌ای با دوره اعتبار نامحدود داشته باشد که اگر هیچ ورودی خط زمان دیگری معتبر نباشد استفاده می‌شود، همان‌طور که در نمونه کد زیر نشان داده شده است:

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 (FCM) ارسال کنید تا برنامه دوباره فعال شود، سپس به‌روزرسانی‌ها را به کاشی ارسال کنید.

• اگر فرایند همگام‌سازی داده‌های کاشی ممکن است پرهزینه باشد، این کارها را انجام دهید:

  1. همگام‌سازی داده‌ها را زمان‌بندی کنید.
  2. زمان‌سنج را برای ۱ تا ۲ ثانیه شروع کنید.
  3. اگر قبل‌از اتمام زمان، به‌روزرسانی‌ای از منبع داده از دور دریافت کردید، مقدار به‌روزشده را از همگام‌سازی داده نشان دهید. درغیراین‌صورت، مقدار محلی ذخیره‌شده‌ای را نشان دهید.