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

ลองใช้วิธีแบบ 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ในเอกสารประกอบของ Glance

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

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

ดูวิธีลงทะเบียนตัวรับสัญญาณในไฟล์ Manifest และติดตั้งใช้งาน การลบล้างวงจรชีวิตที่เข้ากันได้กับ Hilt ได้ที่ส่วนใช้คลาส AppWidgetProvider เพื่อจัดการการออกอากาศในเอกสารประกอบของ Glance

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

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

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

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

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

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-first คุณสามารถตั้งค่านี้แบบไดนามิกใน Kotlin พร้อมกับทรัพยากรธีมที่กำหนดเองได้

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