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

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

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

ไทม์ไลน์ประกอบด้วยอินสแตนซ์ของ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สามารถกำหนดระยะเวลาที่ใช้ได้โดยไม่บังคับ ซึ่งจะช่วยให้ไทล์เปลี่ยนเลย์เอาต์ได้ในเวลาที่ทราบโดยไม่ต้องให้แอปพุชไทล์ใหม่

ตัวอย่างที่ชัดเจนคือการ์ดกำหนดการซึ่งไทม์ไลน์มีรายการ กิจกรรมที่กำลังจะเกิดขึ้น กิจกรรมที่กำลังจะจัดขึ้นแต่ละรายการจะมีระยะเวลาที่ใช้ได้เพื่อระบุเวลา ที่จะแสดง

API ไทล์อนุญาตให้มีระยะเวลาที่ถูกต้องที่ทับซ้อนกัน โดยหน้าจอที่มี ระยะเวลาที่เหลือที่สั้นที่สุดจะเป็นหน้าจอที่แสดง ระบบจะแสดงกิจกรรมครั้งละ 1 รายการเท่านั้น

นักพัฒนาแอปสามารถระบุรายการสำรองเริ่มต้นได้ ตัวอย่างเช่น การ์ดวาระ อาจมีการ์ดที่มีระยะเวลาที่ถูกต้องไม่สิ้นสุด ซึ่งจะใช้หากไม่มีรายการไทม์ไลน์ อื่นที่ถูกต้อง ดังที่แสดงในตัวอย่างโค้ดต่อไปนี้

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