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

หน้าจอหลักของ 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() เพื่อแก้ไขกลุ่มของวิดเจ็ต ทั้ง 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 ดูแอตทริบิวต์การปรับขนาดวิดเจ็ต

  ตรวจสอบว่าวิดเจ็ตมีการแสดงผลด้วย 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