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

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

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

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

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

Android 12

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

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

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

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

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