จัดการและอัปเดต GlanceAppWidget

ส่วนต่อไปนี้จะอธิบายวิธีอัปเดต GlanceAppWidget และจัดการสถานะของแอป

จัดการสถานะ GlanceAppWidget

ระบบจะสร้างอินสแตนซ์คลาส GlanceAppWidget ที่ระบุเมื่อใดก็ตามที่มีการสร้างวิดเจ็ตหรือต้องมีการอัปเดต ดังนั้นคลาสจึงควรเป็นแบบไม่เก็บสถานะและเป็นแบบพาสซีฟ

แนวคิดเกี่ยวกับสถานะแบ่งออกได้ดังนี้

  • สถานะของแอปพลิเคชัน: สถานะหรือเนื้อหาของแอปที่วิดเจ็ตต้องใช้ เช่น รายการปลายทางที่จัดเก็บไว้ (เช่น ฐานข้อมูล) ที่ผู้ใช้กำหนด
  • สถานะ Glance: สถานะเฉพาะที่เกี่ยวข้องกับวิดเจ็ตแอปเท่านั้น และไม่จำเป็นต้องแก้ไขหรือส่งผลต่อสถานะของแอป เช่น มีการเลือกช่องทำเครื่องหมายในวิดเจ็ตหรือมีการเพิ่มตัวนับ

ใช้สถานะของแอปพลิเคชัน

วิดเจ็ตแอปควรเป็นแบบพาสซีฟ แต่ละแอปพลิเคชันมีหน้าที่จัดการชั้นข้อมูลและจัดการสถานะต่างๆ เช่น ไม่ทำงาน กำลังโหลด และข้อผิดพลาดที่แสดงใน UI ของวิดเจ็ต

ตัวอย่างเช่น โค้ดต่อไปนี้จะดึงข้อมูลปลายทางจากแคชหน่วยความจำจากเลเยอร์ที่เก็บข้อมูล แสดงรายการปลายทางที่จัดเก็บไว้ และแสดง UI ที่แตกต่างกันตามสถานะ

class DestinationAppWidget : GlanceAppWidget() {

    // ...

    @Composable
    fun MyContent() {
        val repository = remember { DestinationsRepository.getInstance() }
        // Retrieve the cache data everytime the content is refreshed
        val destinations by repository.destinations.collectAsState(State.Loading)

        when (destinations) {
            is State.Loading -> {
                // show loading content
            }

            is State.Error -> {
                // show widget error content
            }

            is State.Completed -> {
                // show the list of destinations
            }
        }
    }
}

เมื่อใดก็ตามที่สถานะหรือข้อมูลมีการเปลี่ยนแปลง แอปมีหน้าที่แจ้งเตือนและอัปเดตวิดเจ็ต ดูข้อมูลเพิ่มเติมได้ที่อัปเดต GlanceAppWidget

อัปเดต GlanceAppWidget

คุณขออัปเดตเนื้อหาวิดเจ็ตได้โดยใช้ GlanceAppWidget ตามที่อธิบายไว้ในส่วนจัดการสถานะ GlanceAppWidget วิดเจ็ตแอปจะโฮสต์ในกระบวนการอื่น Glance จะแปลเนื้อหาเป็น RemoteViews จริงและส่งไปยังโฮสต์ หากต้องการอัปเดตเนื้อหา Glance ต้องสร้าง RemoteViews ขึ้นมาใหม่และส่งอีกครั้ง

หากต้องการส่งการอัปเดต ให้เรียกใช้เมธอด update ของอินสแตนซ์ GlanceAppWidget โดยระบุ context และ glanceId ดังนี้

MyAppWidget().update(context, glanceId)

หากต้องการรับ glanceId ให้ค้นหา GlanceAppWidgetManager ดังนี้

val manager = GlanceAppWidgetManager(context)
val widget = GlanceSizeModeWidget()
val glanceIds = manager.getGlanceIds(widget.javaClass)
glanceIds.forEach { glanceId ->
    widget.update(context, glanceId)
}

หรือใช้ส่วนขยาย GlanceAppWidget update อย่างใดอย่างหนึ่งต่อไปนี้

// Updates all placed instances of MyAppWidget
MyAppWidget().updateAll(context)

// Iterate over all placed instances of MyAppWidget and update if the state of
// the instance matches the given predicate
MyAppWidget().updateIf<State>(context) { state ->
    state == State.Completed
}

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

class DataSyncWorker(
    val context: Context,
    val params: WorkerParameters,
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        // Fetch data or do some work and then update all instance of your widget
        MyAppWidget().updateAll(context)
        return Result.success()
    }
}

ดูรายละเอียดเพิ่มเติมเกี่ยวกับโครูทีนได้ที่โครูทีน Kotlin ใน Android

กรณีที่ควรอัปเดตวิดเจ็ต

อัปเดตวิดเจ็ตทันทีหรือเป็นระยะๆ

วิดเจ็ตจะอัปเดตทันทีเมื่อแอปทำงานอยู่ เช่น

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

ในกรณีเหล่านี้ ให้เรียกใช้เมธอด update ตามที่อธิบายไว้ในคู่มือนี้

วิดเจ็ตสามารถอัปเดตเป็นระยะๆ เมื่อแอปไม่ได้ทำงานอยู่ เช่น

  • ใช้ updatePeriodMillis เพื่ออัปเดตวิดเจ็ตได้สูงสุด 1 ครั้งทุกๆ 30 นาที
  • ใช้ WorkManager เพื่อกำหนดเวลาการอัปเดตที่บ่อยขึ้น เช่น ทุก 15 นาที
  • อัปเดตวิดเจ็ตเพื่อตอบสนองต่อการออกอากาศ

แหล่งข้อมูล

ก่อนหน้า
ติดตามเมตริกสำหรับวิดเจ็ต
ถัดไป
สร้าง UI ด้วยข้อมูลโดยย่อ