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

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

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

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

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

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

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

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

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

การผูกวิดเจ็ต

เมื่อผู้ใช้เพิ่มวิดเจ็ตลงในโฮสต์ จะเกิดกระบวนการที่เรียกว่า การผูก การผูกหมายถึงการเชื่อมโยงรหัสวิดเจ็ตแอปหนึ่งๆ กับโฮสต์หนึ่งๆ และ 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) หรือ dp หากระบุเฉพาะ minWidth และ minHeight ดู แอตทริบิวต์การปรับขนาดวิดเจ็ต

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

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

กำหนดแนวทางตามเวอร์ชัน Android ที่กำหนดเป้าหมาย

Android 12

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

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

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

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

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