ตัวอย่างวิดเจ็ตที่สร้างขึ้นช่วยให้คุณสร้างตัวอย่างแบบไดนามิกและปรับเปลี่ยนในแบบของคุณสำหรับวิดเจ็ต ซึ่งแสดงให้เห็นอย่างถูกต้องว่าวิดเจ็ตจะปรากฏในหน้าจอหลักของผู้ใช้ อย่างไร โดยจะแสดงผ่าน Push API ซึ่งหมายความว่าแอปของคุณ จะแสดงตัวอย่างได้ทุกเมื่อในวงจรของแอปโดยไม่ต้องรับคำขอที่ชัดแจ้งจากโฮสต์วิดเจ็ต
คู่มือนี้ครอบคลุมวิธีแสดงตัวอย่างวิดเจ็ตที่อิงตาม Glance หากวิดเจ็ตของคุณใช้ RemoteViews โปรดดูเพิ่มตัวอย่างลงในเครื่องมือเลือกวิดเจ็ต
หากต้องการปรับปรุงประสบการณ์การใช้งานเครื่องมือเลือกวิดเจ็ตของแอปสำหรับวิดเจ็ต Glance ให้ระบุ
ตัวอย่างวิดเจ็ตที่สร้างขึ้นโดยใช้ GlanceAppWidget.providePreview บน
อุปกรณ์ Android 15 ขึ้นไป และระบุ previewImage
สำหรับเวอร์ชันที่ต่ำกว่า และเป็นตัวเลือกสำรองใน Android 15 ขึ้นไปหาก
ตัวอย่างที่สร้างขึ้นไม่พร้อมใช้งาน
ดูข้อมูลเพิ่มเติมได้ที่เพิ่มคุณค่าให้แอปด้วยการอัปเดตแบบเรียลไทม์และวิดเจ็ตบน YouTube
ตั้งค่าแอปสำหรับการแสดงตัวอย่างวิดเจ็ตที่สร้างขึ้น
หากต้องการแสดงตัวอย่างวิดเจ็ตที่สร้างขึ้นในอุปกรณ์ Android 15 ขึ้นไป ให้ตั้งค่า
compileSdk เป็น 35 ขึ้นไปในไฟล์ build.gradle ของโมดูลก่อนเพื่อเปิดใช้
ตัวอย่างที่สร้างขึ้นในเครื่องมือเลือกวิดเจ็ต
จากนั้นแอปจะใช้ setWidgetPreview ใน GlanceAppWidgetManager ได้ setWidgetPreview เป็น API ที่มีการจำกัดอัตราคำขอ
เพื่อป้องกันการละเมิดและลดความกังวลเกี่ยวกับประสิทธิภาพของระบบ ขีดจำกัดเริ่มต้นคือประมาณ 2 ครั้งต่อชั่วโมง
สร้างตัวอย่างที่อัปเดตแล้วด้วย Jetpack Glance
สำหรับวิดเจ็ตที่สร้างด้วย Jetpack Glance ให้ทำดังนี้
แทนที่ฟังก์ชัน
GlanceAppWidget.providePreviewเพื่อระบุเนื้อหาที่ใช้ร่วมกันได้สำหรับการแสดงตัวอย่าง เช่นเดียวกับในprovideGlanceให้โหลดข้อมูลของแอปและส่งไปยัง Composable ของเนื้อหาของวิดเจ็ต เพื่อให้ตัวอย่างแสดงข้อมูลที่ถูกต้อง ซึ่งต่างจากprovideGlanceตรงที่นี่เป็นองค์ประกอบเดียว ที่ไม่มีการประกอบใหม่หรือเอฟเฟกต์เรียกใช้
GlanceAppWidgetManager.setWidgetPreviewsเพื่อสร้างและเผยแพร่ ตัวอย่าง
ระบบไม่มีการเรียกกลับเพื่อแสดงตัวอย่าง ดังนั้นแอปของคุณจึงต้อง
ตัดสินใจว่าจะเรียกใช้ setWidgetPreviews เมื่อใด กลยุทธ์การอัปเดตจะขึ้นอยู่กับกรณีการใช้งานของวิดเจ็ต ดังนี้
- หากวิดเจ็ตมีข้อมูลแบบคงที่หรือเป็นการดำเนินการด่วน ให้ตั้งค่าตัวอย่าง เมื่อเปิดแอปเป็นครั้งแรก
- คุณตั้งค่าตัวอย่างได้เมื่อแอปมีข้อมูลแล้ว เช่น หลังจากผู้ใช้ ลงชื่อเข้าใช้หรือตั้งค่าเริ่มต้น
- คุณตั้งค่างานเป็นระยะเพื่ออัปเดตตัวอย่างตามจังหวะที่เลือกได้
แก้ปัญหาตัวอย่างที่สร้างขึ้น
ปัญหาที่พบบ่อยคือหลังจากสร้างตัวอย่างแล้ว รูปภาพ ไอคอน หรือ Composable อื่นๆ
อาจหายไปจากรูปภาพตัวอย่างเมื่อเทียบกับขนาดการวางของวิดเจ็ต
ขนาดการวางนี้กำหนดโดย targetCellWidth และ
targetCellHeight หากระบุ หรือโดย minWidth และ minHeight ใน
ไฟล์ข้อมูลผู้ให้บริการวิดเจ็ตแอป
ซึ่งเกิดขึ้นเนื่องจาก Android จะแสดงผลเฉพาะ Composable ที่มองเห็นได้ที่ขนาดขั้นต่ำของวิดเจ็ตโดยค่าเริ่มต้น
กล่าวคือ Android จะตั้งค่า previewSizeMode เป็น
SizeMode.Single โดยค่าเริ่มต้น โดยจะใช้ android:minHeight และ android:minWidth
ใน XML ข้อมูลผู้ให้บริการวิดเจ็ตแอปเพื่อกำหนด Composable ที่จะวาด
หากต้องการแก้ไขปัญหานี้ ให้ลบล้าง previewSizeMode ใน GlanceAppWidget และตั้งค่าเป็น
SizeMode.Responsive โดยระบุชุดค่า DpSize ซึ่งจะบอก Android
ถึงขนาดเลย์เอาต์ทั้งหมดที่ต้องแสดงตัวอย่าง เพื่อให้มั่นใจว่าองค์ประกอบทั้งหมด
จะแสดงอย่างถูกต้อง
เพิ่มประสิทธิภาพสำหรับรูปแบบอุปกรณ์ที่เฉพาะเจาะจง ระบุขนาด 1 หรือ 2 ขนาดโดยเริ่มจาก
ขนาดต่ำสุดและทำตามเบรกพอยท์ของวิดเจ็ต ระบุอย่างน้อย 1 รายการpreviewImage เพื่อรองรับ Android เวอร์ชันที่ต่ำกว่า คุณดูค่า DP ขั้นต่ำที่เหมาะสมสำหรับขนาดกริดต่างๆ ได้ในคำแนะนำการออกแบบวิดเจ็ต
รองรับ Android เวอร์ชันที่ต่ำกว่า
หากต้องการแสดงตัวอย่างวิดเจ็ตในอุปกรณ์ที่ใช้ Android 14 ลงไป
หรือเมื่อตัวอย่างที่สร้างขึ้นไม่พร้อมใช้งานใน Android 15 ขึ้นไป
ให้ระบุแอตทริบิวต์ previewImage
หากเปลี่ยนลักษณะที่ปรากฏของวิดเจ็ต ให้อัปเดตรูปภาพตัวอย่าง