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

หน้าจอหลักของ 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 ที่ต้องการ

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