ตัวอย่างวิดเจ็ตที่สร้างขึ้นช่วยให้คุณสร้างตัวอย่างแบบไดนามิกที่ปรับเปลี่ยนในแบบของคุณสำหรับวิดเจ็ต ซึ่งแสดงลักษณะที่วิดเจ็ตจะปรากฏบนหน้าจอหลักของผู้ใช้อย่างถูกต้อง โดยจะแสดงผ่าน 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ซึ่งต่างจากprovideGlanceตรงที่นี่เป็นองค์ประกอบเดียวที่ไม่มีการจัดองค์ประกอบใหม่หรือเอฟเฟกต์เรียกใช้
GlanceAppWidgetManager.setWidgetPreviewsเพื่อสร้างและเผยแพร่ตัวอย่าง
ระบบไม่มี Callback เพื่อแสดงตัวอย่าง ดังนั้นแอปของคุณต้องตัดสินใจว่าจะเรียกใช้ setWidgetPreviews เมื่อใด กลยุทธ์การอัปเดตขึ้นอยู่กับกรณีการใช้งานของวิดเจ็ต ดังนี้
- หากวิดเจ็ตมีข้อมูลคงที่หรือเป็นการใช้งานแบบลัด ให้ตั้งค่าตัวอย่างเมื่อเปิดแอปเป็นครั้งแรก
- คุณสามารถตั้งค่าตัวอย่างได้เมื่อแอปมีข้อมูล เช่น หลังจากที่ผู้ใช้ลงชื่อเข้าใช้หรือตั้งค่าเริ่มต้น
- คุณสามารถตั้งค่างานเป็นระยะเพื่ออัปเดตตัวอย่างตามจังหวะที่เลือกได้
แก้ปัญหาตัวอย่างที่สร้างขึ้น
ปัญหาที่พบได้ทั่วไปคือหลังจากสร้างตัวอย่างแล้ว รูปภาพ ไอคอน หรือ Composable อื่นๆ อาจหายไปจากรูปภาพตัวอย่าง โดยขึ้นอยู่กับขนาดการวางของวิดเจ็ต ขนาดการวางนี้กำหนดโดย targetCellWidth และ targetCellHeight หากระบุไว้ หรือกำหนดโดย minWidth และ minHeight ในไฟล์ข้อมูลผู้ให้บริการวิดเจ็ตแอป
ปัญหานี้เกิดขึ้นเนื่องจากโดยค่าเริ่มต้น Android จะแสดงผลเฉพาะคอมโพสิเบิลที่มองเห็นได้ที่ขนาดขั้นต่ำของวิดเจ็ต กล่าวคือ Android จะตั้งค่า previewSizeMode เป็น SizeMode.Single โดยค่าเริ่มต้น โดยจะใช้ android:minHeight และ android:minWidth ใน XML ข้อมูลผู้ให้บริการวิดเจ็ตแอปเพื่อกำหนด Composable ที่จะวาด
หากต้องการแก้ไขปัญหานี้ ให้ลบล้าง previewSizeMode ใน GlanceAppWidget และตั้งค่าเป็น SizeMode.Responsive โดยระบุชุดค่า DpSize ซึ่งจะบอก Android ถึงขนาดเลย์เอาต์ทั้งหมดที่ต้องแสดงผลสำหรับตัวอย่าง เพื่อให้มั่นใจว่าองค์ประกอบทั้งหมดจะแสดงอย่างถูกต้อง
เพิ่มประสิทธิภาพสำหรับอุปกรณ์รูปแบบที่เฉพาะเจาะจง ระบุ 1 หรือ 2 ขนาดโดยเริ่มจากขนาดต่ำสุดและเป็นไปตามเบรกพอยต์ของวิดเจ็ต ระบุ previewImage อย่างน้อย 1 รายการเพื่อรองรับ Android เวอร์ชันที่ต่ำกว่า คุณสามารถดูค่า DP ขั้นต่ำที่เหมาะสมสำหรับขนาดตารางกริดต่างๆ ได้ในคำแนะนำในการออกแบบวิดเจ็ต
รองรับ Android เวอร์ชันที่ต่ำกว่า
หากต้องการแสดงตัวอย่างวิดเจ็ตในอุปกรณ์ที่ใช้ Android 14 และต่ำกว่า หรือเมื่อตัวอย่างที่สร้างขึ้นไม่พร้อมใช้งานใน Android 15 ขึ้นไป ให้ระบุแอตทริบิวต์ previewImage
หากคุณเปลี่ยนลักษณะที่ปรากฏของวิดเจ็ต ให้อัปเดตรูปภาพตัวอย่าง