หน้าจอหลักของ Android ที่พร้อมใช้งานบนอุปกรณ์ที่ใช้ Android ส่วนใหญ่ จะช่วยให้
วิดเจ็ตแอปของผู้ใช้ (หรือวิดเจ็ต) สำหรับ
เข้าถึงเนื้อหาได้อย่างรวดเร็ว หากคุณกำลังสร้างอุปกรณ์ทดแทนหน้าจอหลักหรือ
ที่คล้ายกัน คุณสามารถ ให้ผู้ใช้ฝังวิดเจ็ต โดยใช้
AppWidgetHost
นี่ไม่ใช่
ที่แอปส่วนใหญ่ต้องทำ แต่ถ้าคุณจะสร้างโฮสต์ของตัวเอง
เราต้องเข้าใจภาระหน้าที่ตามสัญญาที่ผู้จัดตกลงรับโดยปริยาย
หน้าเว็บนี้มุ่งเน้นที่ความรับผิดชอบที่เกี่ยวข้องกับการใช้
AppWidgetHost
สำหรับตัวอย่างที่เจาะจงเกี่ยวกับวิธีใช้ AppWidgetHost
ให้ดูที่ซอร์สโค้ดสำหรับหน้าจอหลักของ Android
LauncherAppWidgetHost
ต่อไปนี้เป็นภาพรวมของชั้นเรียนหลักและแนวคิดที่เกี่ยวข้องกับการนำ
AppWidgetHost
ที่กำหนดเอง:
โฮสต์วิดเจ็ตแอป:
AppWidgetHost
จะระบุการโต้ตอบกับ บริการ AppWidget สำหรับแอปที่ฝังวิดเจ็ตใน UIAppWidgetHost
ต้องมีรหัสที่ไม่ซ้ำกันในแพ็กเกจของโฮสต์เอง รหัสนี้ยังคงอยู่ ในการใช้งานโฮสต์ทั้งหมด ปกติแล้วรหัสจะเป็นค่าฮาร์ดโค้ดที่คุณ กำหนดในแอปรหัสวิดเจ็ตแอป: ระบบจะกำหนดรหัสที่ไม่ซ้ำกันให้กับอินสแตนซ์วิดเจ็ตแต่ละรายการ ณ เวลานั้น ของการผูก โปรดดู
bindAppWidgetIdIfAllowed()
และดูรายละเอียดเพิ่มเติมได้ในส่วนการเชื่อมโยงวิดเจ็ตที่ตามมา โฮสต์จะได้รับรหัสที่ไม่ซ้ำกันโดยใช้allocateAppWidgetId()
รหัสนี้จะคงอยู่ตลอดอายุการใช้งานของวิดเจ็ตจนกว่าจะลบออกจากวิดเจ็ต เป็นโฮสต์ สถานะใดๆ ของโฮสต์ เช่น ขนาดและตำแหน่งของไฟล์ ต้องอยู่ในแพ็กเกจโฮสติ้งและเชื่อมโยงกับ รหัสวิดเจ็ตของแอปมุมมองโฮสต์วิดเจ็ตแอป: นึกถึง
AppWidgetHostView
เป็นเฟรม การรวมวิดเจ็ตนั้นไว้ตลอดเวลาที่ต้องการแสดง วิดเจ็ตคือ ที่เชื่อมโยงกับAppWidgetHostView
ทุกครั้งที่มีการขยายวิดเจ็ต เป็นโฮสต์- ระบบจะสร้าง
AppWidgetHostView
โดยค่าเริ่มต้น แต่โฮสต์สามารถสร้าง สร้างคลาสย่อยของตัวเองของAppWidgetHostView
โดยการขยาย - เริ่มตั้งแต่ Android 12 (API ระดับ 31) เป็นต้นไป
AppWidgetHostView
จะเปิดตัว เวลาsetColorResources()
และresetColorResources()
วิธีจัดการสีที่มีการโหลดมากเกินไปแบบไดนามิก ผู้จัดคือ มีหน้าที่ระบุสีให้กับวิธีการเหล่านี้
- ระบบจะสร้าง
กลุ่มตัวเลือก:
AppWidgetHost
จะใช้กลุ่มตัวเลือกเพื่อ สื่อสารข้อมูลไปยังAppWidgetProvider
เกี่ยวกับวิธีแสดงวิดเจ็ต เช่น รายการช่วงขนาด และตรวจสอบว่า อยู่บนหน้าจอล็อกหรือหน้าจอหลัก ข้อมูลนี้ช่วยให้AppWidgetProvider
ปรับแต่งเนื้อหาและรูปลักษณ์ของวิดเจ็ตตามวิธีการและ ในตำแหน่งที่แสดง คุณสามารถใช้updateAppWidgetOptions()
และupdateAppWidgetSize()
เพื่อแก้ไข Bundle ของวิดเจ็ต ทั้ง 2 วิธีนี้เรียกใช้เมธอดonAppWidgetOptionsChanged()
โทรกลับไปยังAppWidgetProvider
การเชื่อมโยงวิดเจ็ต
เมื่อผู้ใช้เพิ่มวิดเจ็ตไปยังโฮสต์ กระบวนการที่เรียกว่าการเชื่อมโยงจะเกิดขึ้น การเชื่อมโยง
หมายถึงการเชื่อมโยงรหัสวิดเจ็ตแอปหนึ่งๆ กับโฮสต์ที่ระบุและ
AppWidgetProvider
ที่ต้องการ
Binding API ยังทำให้โฮสต์มี UI ที่กำหนดเองสำหรับ
การผูก หากต้องการใช้กระบวนการนี้ แอปของคุณต้องประกาศ
BIND_APPWIDGET
สิทธิ์ในไฟล์ Manifest ของโฮสต์
<uses-permission android:name="android.permission.BIND_APPWIDGET" />
แต่นี่เป็นเพียงขั้นตอนแรกเท่านั้น ขณะรันไทม์ ผู้ใช้ต้องให้สิทธิ์
สิทธิ์ของแอปเพื่อให้แอปเพิ่มวิดเจ็ตไปยังโฮสต์ได้ เพื่อทดสอบว่า
แอปมีสิทธิ์ในการเพิ่มวิดเจ็ต ให้ใช้
bindAppWidgetIdIfAllowed()
หาก bindAppWidgetIdIfAllowed()
แสดงผล false
แอปของคุณต้องแสดง
กล่องโต้ตอบที่แจ้งให้ผู้ใช้อนุญาต: "อนุญาต" สำหรับวิดเจ็ตปัจจุบัน
หรือ "อนุญาตเสมอ" เพื่อให้ครอบคลุมการเพิ่มวิดเจ็ตทั้งหมดในอนาคต
ข้อมูลโค้ดนี้แสดงตัวอย่างวิธีแสดงกล่องโต้ตอบ
Kotlin
val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply { putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName) // This is the options bundle described in the preceding section. putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options) } startActivityForResult(intent, REQUEST_BIND_APPWIDGET)
Java
Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND); intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName); // This is the options bundle described in the preceding section. intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options); startActivityForResult(intent, REQUEST_BIND_APPWIDGET);
โฮสต์ต้องตรวจสอบว่าวิดเจ็ตที่ผู้ใช้เพิ่มต้องมีการกำหนดค่าหรือไม่ สำหรับ โปรดดูข้อมูลเพิ่มเติมที่อนุญาตให้ผู้ใช้กำหนดค่าแอป วิดเจ็ต
ความรับผิดชอบของผู้จัด
คุณสามารถระบุจำนวนการตั้งค่าการกำหนดค่าสำหรับวิดเจ็ตโดยใช้
ข้อมูลเมตา AppWidgetProviderInfo
คุณสามารถเรียกดูตัวเลือกการกำหนดค่าเหล่านี้ได้ ซึ่งจะมีรายละเอียดเพิ่มเติมใน
ต่อไปนี้ จาก
AppWidgetProviderInfo
ที่เชื่อมโยงกับผู้ให้บริการวิดเจ็ต
ไม่ว่าคุณจะกำหนดเป้าหมาย Android เวอร์ชันใด โฮสต์ทั้งหมดจะมี
เมื่อเพิ่มวิดเจ็ต ให้จัดสรรรหัสวิดเจ็ตตามที่อธิบายไว้ก่อนหน้านี้ เมื่อ วิดเจ็ตถูกนำออกจากโฮสต์, เรียก
deleteAppWidgetId()
เพื่อหารหัสวิดเจ็ตเมื่อเพิ่มวิดเจ็ต ให้ตรวจสอบว่ากิจกรรมการกำหนดค่าต้อง เปิดตัว โดยปกติแล้ว โฮสต์จะต้องเปิดการกำหนดค่าของวิดเจ็ต กิจกรรมที่มีอยู่ (หากมี) และไม่ได้ทำเครื่องหมายว่าไม่บังคับโดยการระบุทั้ง แฟล็ก
configuration_optional
และreconfigurable
โปรดดู อัปเดตวิดเจ็ตจากกิจกรรมการกำหนดค่า เพื่อดูรายละเอียด การดำเนินการนี้เป็นขั้นตอนที่จำเป็นสำหรับวิดเจ็ตจำนวนมากก่อนที่จะแสดงได้วิดเจ็ตระบุความกว้างและความสูงเริ่มต้นใน
AppWidgetProviderInfo
ข้อมูลเมตา ค่าเหล่านี้จะกำหนดไว้ในเซลล์ โดยเริ่มตั้งแต่ Android 12 หากtargetCellWidth
และtargetCellHeight
เป็น ที่ระบุ หรือ dps หากระบุเฉพาะminWidth
และminHeight
โปรดดู แอตทริบิวต์การปรับขนาดวิดเจ็ตตรวจสอบว่าวิดเจ็ตมี dps อย่างน้อยเท่านี้ สำหรับ ตัวอย่างเช่น หลายรายมีโฮสต์ให้จัดไอคอนและวิดเจ็ตให้อยู่ในเส้นตาราง ในกรณีนี้ โดย ค่าเริ่มต้นโฮสต์จะเพิ่มวิดเจ็ตโดยใช้จำนวนเซลล์ต่ำสุดที่ เป็นไปตามข้อจำกัด
minWidth
และminHeight
นอกเหนือจากข้อกำหนดที่แสดงในส่วนก่อนหน้านี้แล้ว ของแพลตฟอร์ม เป็นโฮสต์
กำหนดแนวทางโดยอิงตามเวอร์ชัน Android เป้าหมาย
Android 12
Android 12 (API ระดับ 31) รวม List<SizeF>
เพิ่มเติมที่มีในลิสต์ดังกล่าว
ของขนาดที่เป็นไปได้ในหน่วย dps ที่อินสแตนซ์วิดเจ็ตสามารถใช้ในกลุ่มตัวเลือก
จำนวนขนาดที่ระบุจะขึ้นอยู่กับการใช้งานโฮสต์ โฮสต์โดยทั่วไป
มี 2 ขนาดสำหรับโทรศัพท์ ได้แก่ แนวตั้งและแนวนอน และ 4 ขนาด
สำหรับอุปกรณ์แบบพับได้
มีการจำกัดจำนวนMAX_INIT_VIEW_COUNT
RemoteViews
ที่ AppWidgetProvider
สามารถให้ได้
RemoteViews
เนื่องจากออบเจ็กต์ AppWidgetProvider
จะแมปวัตถุ RemoteViews
กับแต่ละขนาดในองค์ประกอบ
List<SizeF>
อย่าใส่เกิน MAX_INIT_VIEW_COUNT
ขนาด
Android 12 ยังเปิดตัว
maxResizeWidth
และ
maxResizeHeight
หน่วยเป็น dps เราขอแนะนำว่าวิดเจ็ตที่ใช้
ไม่เกินขนาดที่แอตทริบิวต์ระบุ
แหล่งข้อมูลเพิ่มเติม
- ดูเอกสารอ้างอิงเกี่ยวกับ
Glance