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

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

کار با جدول‌های زمانی

یک جدول زمانی (timeline) شامل یک یا چند نمونه TimelineEntry است که هر کدام شامل یک طرح‌بندی (layout) هستند که در یک بازه زمانی خاص نمایش داده می‌شود. همه کاشی‌ها به یک جدول زمانی نیاز دارند.

کاشی‌های تک ورودی

اغلب می‌توان یک کاشی را با یک 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. اگر قبل از اتمام زمان، به‌روزرسانی از یک منبع داده‌ی راه دور دریافت کردید، مقدار به‌روزرسانی‌شده از همگام‌سازی داده‌ها را نمایش دهید. در غیر این صورت، یک مقدار محلی ذخیره‌شده در حافظه‌ی پنهان را نمایش دهید.