สร้างวิดเจ็ตแบบง่าย

ลองใช้วิธีแบบ 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 ทรัพยากรเลย์เอาต์แบบ Lazy ได้ในรันไทม์

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

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

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

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

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

Kotlin

// 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)
)

Java

// 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