สร้างโฮสต์วิดเจ็ต

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

หน้านี้จะมุ่งเน้นที่ความรับผิดชอบที่เกี่ยวข้องกับการติดตั้งใช้งาน AppWidgetHost ที่กำหนดเอง ดูตัวอย่างที่เฉพาะเจาะจงเกี่ยวกับวิธีติดตั้งใช้งาน AppWidgetHost ได้ที่ซอร์สโค้ดสำหรับหน้าจอหลักของ Android LauncherAppWidgetHost

ต่อไปนี้คือภาพรวมของคลาสและแนวคิดหลักที่เกี่ยวข้องกับการติดตั้งใช้งาน AppWidgetHost ที่กำหนดเอง

• โฮสต์วิดเจ็ตแอป: AppWidgetHost มีการโต้ตอบกับบริการ AppWidget สำหรับแอปที่ฝังวิดเจ็ตไว้ใน UI AppWidgetHost ต้องมีรหัสที่ไม่ซ้ำกันภายในแพ็กเกจของโฮสต์เอง รหัสนี้จะยังคงอยู่ในการใช้งานโฮสต์ทั้งหมด โดยปกติแล้ว รหัสจะเป็นค่าที่ฮาร์ดโค้ดซึ่งคุณกำหนดในแอป

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

• มุมมองโฮสต์วิดเจ็ตแอป: ให้คิดว่า AppWidgetHostView เป็นเฟรมที่วิดเจ็ตจะถูกรวมไว้เมื่อใดก็ตามที่ต้องแสดง วิดเจ็ตจะเชื่อมโยงกับ AppWidgetHostView ทุกครั้งที่โฮสต์ขยายวิดเจ็ต

  • โดยค่าเริ่มต้น ระบบจะสร้าง AppWidgetHostView แต่โฮสต์สามารถสร้างคลาสย่อยของ AppWidgetHostView ของตนเองได้โดยการขยายคลาส
  • ตั้งแต่ Android 12 (API ระดับ 31) เป็นต้นไป AppWidgetHostView จะเปิดตัวเมธอด setColorResources() และ resetColorResources() สำหรับจัดการสีที่โอเวอร์โหลดแบบไดนามิก โฮสต์มีหน้าที่รับผิดชอบในการระบุสีให้กับเมธอดเหล่านี้

• แพ็กเกจตัวเลือก: AppWidgetHost ใช้แพ็กเกจตัวเลือกเพื่อสื่อสารข้อมูลกับ AppWidgetProvider เกี่ยวกับวิธีแสดงวิดเจ็ต เช่น รายการช่วงขนาด และวิดเจ็ตอยู่บนหน้าจอล็อกหรือหน้าจอหลัก ข้อมูลนี้ช่วยให้ AppWidgetProvider ปรับแต่งเนื้อหาและลักษณะที่ปรากฏของวิดเจ็ตตามวิธีและตำแหน่งที่แสดงได้ คุณสามารถใช้ updateAppWidgetOptions() และ updateAppWidgetSize() เพื่อแก้ไข Bundle ของวิดเจ็ตได้ ทั้ง 2 วิธีนี้จะทริกเกอร์ Callback onAppWidgetOptionsChanged() ไปยัง AppWidgetProvider

วิดเจ็ตการเชื่อมโยง

เมื่อผู้ใช้เพิ่มวิดเจ็ตลงในโฮสต์ กระบวนการที่เรียกว่าการเชื่อมโยงจะเกิดขึ้น การเชื่อมโยงหมายถึงการเชื่อมโยงรหัสวิดเจ็ตแอปหนึ่งๆ กับโฮสต์ที่เฉพาะเจาะจงและ AppWidgetProvider ที่เฉพาะเจาะจง

นอกจากนี้ Binding API ยังช่วยให้โฮสต์สามารถจัดเตรียม UI ที่กำหนดเองสำหรับการเชื่อมโยงได้ด้วย หากต้องการใช้กระบวนการนี้ แอปของคุณต้องประกาศสิทธิ์ BIND_APPWIDGET ในไฟล์ Manifest ของโฮสต์ ดังนี้

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

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

ข้อมูลโค้ดนี้แสดงตัวอย่างวิธีแสดงกล่องโต้ตอบ

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.provider)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)
Host.kt

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

ความรับผิดชอบของผู้จัด

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

ผู้จัดทุกคนมีหน้าที่รับผิดชอบต่อไปนี้

• เมื่อเพิ่มวิดเจ็ต ให้จัดสรรรหัสวิดเจ็ตตามที่อธิบายไว้ก่อนหน้านี้ เมื่อนำวิดเจ็ตออกจากโฮสต์ ให้เรียกใช้ deleteAppWidgetId() เพื่อยกเลิกการจัดสรรรหัสวิดเจ็ต

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

  หมายเหตุ: จัดการกรณีที่ผิดปกติซึ่งกิจกรรมการกำหนดค่าไม่แสดงผลหรือดำเนินการเสร็จสิ้นโดยมีข้อผิดพลาด

• วิดเจ็ตจะระบุความกว้างและความสูงเริ่มต้นในข้อมูลเมตา AppWidgetProviderInfo ค่าเหล่านี้จะกำหนดเป็นเซลล์ โดยเริ่มตั้งแต่ Android 12 หากมีการระบุ targetCellWidth และ targetCellHeight หรือเป็น dp หากระบุเฉพาะ minWidth และ minHeight ดูแอตทริบิวต์การปรับขนาดวิดเจ็ต

  ตรวจสอบว่าวิดเจ็ตมีเลย์เอาต์ที่มี dp อย่างน้อยเท่านี้ เช่น โฮสต์จำนวนมากจัดไอคอนและวิดเจ็ตในตารางกริด ในสถานการณ์นี้ โดยค่าเริ่มต้นโฮสต์จะเพิ่มวิดเจ็ตโดยใช้จำนวนเซลล์ขั้นต่ำที่ตรงตามข้อจำกัด minWidth และ minHeight

เคล็ดลับเกี่ยวกับแนวทางของคุณ

นอกเหนือจากข้อกำหนดที่ระบุไว้ในส่วนก่อนหน้าแล้ว โปรดคำนึงถึงเคล็ดลับต่อไปนี้ด้วย

แพ็กเกจตัวเลือกอาจมี List<SizeF> ซึ่งมีรายการขนาดที่เป็นไปได้ในหน่วย dp ที่อินสแตนซ์วิดเจ็ตใช้ได้ จำนวนขนาดที่ระบุจะขึ้นอยู่กับการใช้งานโฮสต์ โดยปกติแล้ว โฮสต์จะจัดเตรียมขนาด 2 ขนาดสำหรับโทรศัพท์ ได้แก่ แนวตั้งและแนวนอน และ 4 ขนาดสำหรับอุปกรณ์แบบพับได้

RemoteViews ที่ AppWidgetProvider สามารถระบุให้กับ RemoteViews มีจำนวนจำกัดอยู่ที่ MAX_INIT_VIEW_COUNT (16) รายการ เนื่องจากออบเจ็กต์ AppWidgetProvider จะแมปออบเจ็กต์ RemoteViews กับแต่ละขนาดใน List<SizeF> โปรดอย่าระบุขนาดเกิน MAX_INIT_VIEW_COUNT ขนาด

เมื่อวิดเจ็ตระบุแอตทริบิวต์ maxResizeWidth และ maxResizeHeight ในหน่วย dp เราขอแนะนำว่าวิดเจ็ตที่ใช้แอตทริบิวต์เหล่านี้อย่างน้อย 1 รายการไม่ควรมีขนาดเกินกว่าที่แอตทริบิวต์ระบุไว้

แหล่งข้อมูลเพิ่มเติม

• ดูเอกสารอ้างอิง Glance