สร้างวิดเจ็ตพื้นฐาน

ลองใช้วิธีแบบ Compose
Jetpack Compose เป็นชุดเครื่องมือ UI ที่แนะนำสำหรับ Android ดูวิธีสร้างวิดเจ็ตโดยใช้ API รูปแบบ Compose
Jetpack Glance →

วิดเจ็ตแอปคือมุมมองแอปขนาดเล็กที่คุณฝังในแอปอื่นๆ ได้ เช่น หน้าจอหลัก และรับการอัปเดตเป็นระยะ มุมมองเหล่านี้เรียกว่าวิดเจ็ตในอินเทอร์เฟซผู้ใช้ และคุณสามารถเผยแพร่วิดเจ็ตด้วยผู้ให้บริการวิดเจ็ตแอป (หรือผู้ให้บริการวิดเจ็ต) คอมโพเนนต์แอปที่เก็บวิดเจ็ตอื่นๆ เรียกว่าโฮสต์วิดเจ็ตแอป (หรือโฮสต์วิดเจ็ต) รูปที่ 1 แสดงตัวอย่างวิดเจ็ตเพลง

ตัวอย่างวิดเจ็ตเพลง
รูปที่ 1 ตัวอย่างวิดเจ็ตเพลง

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

ดูข้อมูลเกี่ยวกับวิธีออกแบบวิดเจ็ตได้ที่ภาพรวมวิดเจ็ตแอป

คอมโพเนนต์วิดเจ็ต

หากต้องการสร้างวิดเจ็ต คุณต้องมีคอมโพเนนต์พื้นฐานต่อไปนี้

ออบเจ็กต์ AppWidgetProviderInfo
อธิบายข้อมูลเมตาสำหรับวิดเจ็ต เช่น เลย์เอาต์ของวิดเจ็ต ความถี่ในการอัปเดต และคลาส AppWidgetProvider AppWidgetProviderInfo กำหนดไว้ใน XML ตามที่อธิบายไว้ในเอกสารนี้
คลาส AppWidgetProvider
กำหนดวิธีการพื้นฐานที่ช่วยให้คุณเชื่อมต่อกับวิดเจ็ตแบบเป็นโปรแกรมได้ คุณจะได้รับการออกอากาศผ่านคลาสนี้เมื่อวิดเจ็ตได้รับการอัปเดต เปิดใช้ ปิดใช้ หรือลบ คุณประกาศ AppWidgetProvider ในไฟล์ Manifest แล้วติดตั้งใช้งานตามที่อธิบายไว้ในเอกสารนี้
ดูเลย์เอาต์
กำหนดเลย์เอาต์เริ่มต้นสำหรับวิดเจ็ต เลย์เอาต์จะกำหนดไว้ใน XML ตามที่อธิบายไว้ในเอกสารนี้

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

ขั้นตอนการประมวลผลวิดเจ็ตของแอป
รูปที่ 2 ขั้นตอนการประมวลผลวิดเจ็ตของแอป

หากวิดเจ็ตต้องมีการกำหนดค่าของผู้ใช้ ให้ใช้กิจกรรมการกำหนดค่าวิดเจ็ตแอป กิจกรรมนี้ช่วยให้ผู้ใช้แก้ไขการตั้งค่าวิดเจ็ตได้ เช่น เขตเวลาสำหรับวิดเจ็ตนาฬิกา

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

ประกาศ XML ของ AppWidgetProviderInfo

การกำหนดการตั้งค่าข้อมูลเมตา (เช่น ขนาดเซลล์เริ่มต้น ข้อจำกัดในการปรับขนาด และความถี่ในการอัปเดต) จะเหมือนกันทุกประการทั้งในมุมมองแบบดั้งเดิมและวิดเจ็ตที่อิงตาม Glance

ดูวิธีระบุและกำหนดค่าไฟล์ XML ของข้อมูลเมตาได้ที่ส่วนประกาศ XML ของ AppWidgetProviderInfo แบบ Compose-first ในเอกสารประกอบของ Glance

ใช้คลาส AppWidgetProvider เพื่อจัดการการออกอากาศวิดเจ็ต

กลไก Broadcast Receiver, ตัวกรองการประกาศไฟล์ Manifest และวนรอบเหตุการณ์ในวงจรของแพลตฟอร์มจะรวมอยู่ภายใต้แพลตฟอร์ม ในการพัฒนาที่เน้น Compose เป็นหลัก ระบบจะจัดการการออกอากาศเหล่านี้โดยใช้ Wrapper GlanceAppWidgetReceiver

หากต้องการทำความเข้าใจวิธีลงทะเบียน Receiver ในไฟล์ Manifest และใช้การลบล้างวงจรที่เข้ากันได้กับ Hilt โปรดดูส่วนใช้คลาส AppWidgetProvider เพื่อจัดการการออกอากาศในเอกสารประกอบของ Glance ซึ่งเน้น Compose เป็นหลัก

สร้างเลย์เอาต์วิดเจ็ต

คุณต้องกำหนดเลย์เอาต์เริ่มต้นสำหรับวิดเจ็ตใน XML และบันทึกไว้ในไดเรกทอรี res/layout/ ของโปรเจ็กต์ ดูรายละเอียดได้ที่หลักเกณฑ์การออกแบบ

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

RemoteViews ยังรองรับ ViewStub ซึ่งเป็น View ที่มองไม่เห็นและมีขนาดเป็นศูนย์ที่คุณสามารถใช้เพื่อขยายทรัพยากรเลย์เอาต์แบบ Lazy ในรันไทม์ได้

การรองรับลักษณะการทำงานแบบเก็บสถานะ

Android 12 เพิ่มการรองรับลักษณะการทำงานแบบเก็บสถานะโดยใช้คอมโพเนนต์ที่มีอยู่ต่อไปนี้

วิดเจ็ตยังคงไม่มีสถานะ แอปต้องจัดเก็บสถานะและลงทะเบียนสำหรับเหตุการณ์การเปลี่ยนแปลงสถานะ

ตัวอย่างวิดเจ็ตรายการช็อปปิ้งที่แสดงลักษณะการทำงานแบบเก็บสถานะ
รูปที่ 3 ตัวอย่างลักษณะการทำงานแบบเก็บสถานะ

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีใช้คอมโพเนนต์เหล่านี้

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

จัดเตรียมเลย์เอาต์ 2 แบบ ได้แก่ เลย์เอาต์หนึ่งที่กำหนดเป้าหมายเป็นอุปกรณ์เป้าหมายที่ใช้ Android 12 ขึ้นไปใน res/layout-v31 และอีกเลย์เอาต์หนึ่งที่กำหนดเป้าหมายเป็น Android 11 หรือต่ำกว่าในโฟลเดอร์ res/layout เริ่มต้น

ใช้มุมโค้งมน

การคำนวณรัศมีพื้นหลังด้านนอกและรัศมีตามสัดส่วนด้านในเป็นแบบมาตรฐานและใช้ร่วมกัน ในการพัฒนาที่เน้น Compose เป็นหลัก คุณสามารถตั้งค่านี้แบบไดนามิกใน Kotlin ควบคู่ไปกับทรัพยากรธีมที่กำหนดเอง

หากต้องการใช้รัศมีมุมหรือตั้งค่าสไตล์แบบไดนามิกสำหรับอุปกรณ์ Android รุ่นเก่า โปรดดูส่วนใช้มุมมนที่เน้น Compose เป็นหลักในเอกสารประกอบของ Glance