แสดงการอัปเดตเป็นระยะในการ์ด

สร้างการ์ดที่มีเนื้อหาที่เปลี่ยนแปลงไปตามกาลเวลา

ทำงานกับไทม์ไลน์

ไทม์ไลน์ประกอบด้วยอินสแตนซ์ TimelineEntry อย่างน้อย 1 รายการ โดยแต่ละรายการจะมีเลย์เอาต์ที่แสดงในช่วงเวลาที่เจาะจง การ์ดทั้งหมดต้องมีไทม์ไลน์

แผนภาพไทม์ไลน์ของการ์ด

ไทล์แบบรายการเดียว

บ่อยครั้งที่การ์ดอธิบายได้ด้วย 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()

ไทล์อาจหมดอายุเนื่องจากเหตุการณ์ภายนอกด้วย เช่น ผู้ใช้อาจนำการประชุมออกจากปฏิทิน และหากไม่ได้รีเฟรชการ์ด การ์ดจะยังคงแสดงการประชุมที่ลบไปแล้ว ในกรณีนี้ ให้ขอการรีเฟรชจากตำแหน่งใดก็ได้ในโค้ดแอปพลิเคชัน ดังที่แสดงในตัวอย่างโค้ดต่อไปนี้

Kotlin

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

Java

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

เลือกเวิร์กโฟลว์การอัปเดต

ใช้แนวทางปฏิบัติแนะนำต่อไปนี้เพื่อกำหนดวิธีกำหนดค่าการอัปเดตการ์ด

  • หากการอัปเดตคาดการณ์ได้ เช่น เป็นการอัปเดตสำหรับกิจกรรมถัดไปในปฏิทินของผู้ใช้ ให้ใช้ไทม์ไลน์
  • เมื่อดึงข้อมูลแพลตฟอร์ม ให้ใช้การเชื่อมโยงข้อมูลเพื่อให้ระบบอัปเดตข้อมูลโดยอัตโนมัติ

  • หากคำนวณการอัปเดตในอุปกรณ์ได้ในเวลาอันสั้น เช่น การอัปเดตตำแหน่งของรูปภาพในการ์ดภาพพระอาทิตย์ขึ้น ให้ใช้ onTileRequest()

    ซึ่งจะเป็นประโยชน์อย่างยิ่งเมื่อคุณต้องสร้างรูปภาพทั้งหมดล่วงหน้า หากต้องการสร้างรูปภาพใหม่ในอนาคต ให้โทรไปที่ setFreshnessIntervalMillis()

  • หากคุณทํางานเบื้องหลังที่เข้มข้นมากขึ้นซ้ำๆ เช่น การสอบถามข้อมูลสภาพอากาศ ให้ใช้ WorkManager และพุชการอัปเดตไปยังการ์ด

  • หากการอัปเดตเป็นการตอบสนองต่อเหตุการณ์ภายนอก เช่น การเปิดไฟ การรับอีเมล หรือการอัปเดตโน้ต ให้ส่งข้อความ Firebase Cloud Messaging (FCM) เพื่อทำให้แอปทำงานอีกครั้ง จากนั้นจึงพุชการอัปเดตไปยังการ์ด

  • หากกระบวนการซิงค์ข้อมูลแผนที่จะเสียค่าใช้จ่ายสูง ให้ทำดังนี้

    1. กำหนดเวลาการซิงค์ข้อมูล
    2. เริ่มจับเวลา 1-2 วินาที
    3. หากคุณได้รับการอัปเดตจากแหล่งข้อมูลระยะไกลก่อนที่เวลาจะหมด ให้แสดงค่าที่อัปเดตจากการซิงค์ข้อมูล มิฉะนั้น ระบบจะแสดงค่าที่แคชไว้