เพิ่มตัวอย่างที่สร้างขึ้นไปยังเครื่องมือเลือกวิดเจ็ต

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

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

หากต้องการปรับปรุงประสบการณ์การเลือกวิดเจ็ตของแอปสำหรับวิดเจ็ต Glance ให้ระบุ ตัวอย่างวิดเจ็ตที่สร้างขึ้นโดยใช้ GlanceAppWidget.providePreview ใน อุปกรณ์ Android 15 ขึ้นไป และระบุ previewImage สำหรับเวอร์ชันก่อนหน้า และเป็นตัวเลือกสำรองใน Android 15 ขึ้นไป หาก ตัวอย่างที่สร้างขึ้นไม่พร้อมใช้งาน

ดูข้อมูลเพิ่มเติมได้ที่เพิ่มคุณค่าให้แอปด้วยการอัปเดตแบบเรียลไทม์และวิดเจ็ตบน YouTube

ตั้งค่าแอปสำหรับการแสดงตัวอย่างวิดเจ็ตที่สร้างขึ้น

หากต้องการแสดงตัวอย่างวิดเจ็ตที่สร้างขึ้นในอุปกรณ์ Android 15 ขึ้นไป ให้ตั้งค่า compileSdk เป็น 35 ขึ้นไปในไฟล์ build.gradle ของโมดูลก่อน เพื่อให้มีความสามารถในการระบุ RemoteViews ให้กับเครื่องมือเลือกวิดเจ็ต

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

ความเข้ากันได้แบบย้อนหลังกับตัวอย่างวิดเจ็ต

หากต้องการให้ตัวเลือกวิดเจ็ตในอุปกรณ์ที่ใช้ Android เวอร์ชันต่ำกว่า 15 แสดงตัวอย่างวิดเจ็ต หรือใช้เป็นข้อมูลสำรองสำหรับตัวอย่างที่สร้างขึ้นใน Android 15 ขึ้นไป ให้ระบุแอตทริบิวต์ previewImage

หากเปลี่ยนลักษณะที่ปรากฏของวิดเจ็ต ให้อัปเดตรูปภาพตัวอย่าง

สร้างวิดเจ็ตแอปด้วย "ข้อมูลโดยย่อ"

ปักหมุดวิดเจ็ต Glance ในแอป