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

หน้าจอหลักของ 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 วิธีนี้เรียกใช้เมธอด onAppWidgetOptionsChanged() โทรกลับไปยัง AppWidgetProvider

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

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

นอกจากนี้ การเชื่อมโยง 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 โปรดดู แอตทริบิวต์การปรับขนาดวิดเจ็ต

    ตรวจสอบว่าวิดเจ็ตมีการแสดงผลด้วย DPI อย่างน้อยเท่านี้ สำหรับ ตัวอย่างเช่น หลายรายมีโฮสต์ให้จัดไอคอนและวิดเจ็ตให้อยู่ในเส้นตาราง ในสถานการณ์นี้ โฮสต์จะเพิ่มวิดเจ็ตโดยใช้จำนวนเซลล์ขั้นต่ำที่ตรงกับข้อจำกัด 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