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

หน้าจอหลักของ 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ที่เฉพาะเจาะจง

การเชื่อมโยง API ยังช่วยให้โฮสต์สามารถระบุ UI ที่กำหนดเองสำหรับการเชื่อมโยงได้ด้วย หากต้องการใช้กระบวนการนี้ แอปของคุณต้องประกาศสิทธิ์ BIND_APPWIDGET ในไฟล์ Manifest ของโฮสต์

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

แต่นี่เป็นเพียงขั้นตอนแรก ในรันไทม์ ผู้ใช้ต้องให้สิทธิ์แก่แอปของคุณอย่างชัดแจ้ง เพื่อให้แอปเพิ่มวิดเจ็ตลงในโฮสต์ได้ หากต้องการทดสอบว่าแอปมีสิทธิ์เพิ่มวิดเจ็ตหรือไม่ ให้ใช้วิธีการ bindAppWidgetIdIfAllowed() หาก bindAppWidgetIdIfAllowed() แสดงผล false แอปของคุณต้องแสดงกล่องโต้ตอบที่แจ้งให้ผู้ใช้ให้สิทธิ์ "อนุญาต" สำหรับการเพิ่มวิดเจ็ตปัจจุบัน หรือ "อนุญาตเสมอ" เพื่อครอบคลุมการเพิ่มวิดเจ็ตในอนาคตทั้งหมด

ข้อมูลโค้ดนี้แสดงตัวอย่างวิธีแสดงกล่องโต้ตอบ

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.provider)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)
Host.kt

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

ความรับผิดชอบของโฮสต์

คุณระบุการตั้งค่าการกำหนดค่าจำนวนหนึ่งสำหรับวิดเจ็ตได้โดยใช้AppWidgetProviderInfoข้อมูลเมตา คุณเรียกตัวเลือกการกำหนดค่าเหล่านี้ ซึ่งจะกล่าวถึงโดยละเอียดในส่วนต่อไปนี้ได้จากออบเจ็กต์ AppWidgetProviderInfo ที่เชื่อมโยงกับผู้ให้บริการวิดเจ็ต

โฮสต์ทุกคนมีหน้าที่รับผิดชอบดังต่อไปนี้

• เมื่อเพิ่มวิดเจ็ต ให้จัดสรรรหัสวิดเจ็ตตามที่อธิบายไว้ก่อนหน้านี้ เมื่อนำวิดเจ็ตออกจากโฮสต์ ให้เรียกใช้ deleteAppWidgetId() เพื่อยกเลิกการจัดสรรรหัสวิดเจ็ต

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

• วิดเจ็ตจะระบุความกว้างและความสูงเริ่มต้นในAppWidgetProviderInfo ข้อมูลเมตา ค่าเหล่านี้จะกำหนดในเซลล์ โดยเริ่มตั้งแต่ Android 12 หากมีการระบุ targetCellWidth และ targetCellHeight หรือใน dps หากมีการระบุเฉพาะ minWidth และ minHeight ดูแอตทริบิวต์การกำหนดขนาดวิดเจ็ต

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

เคล็ดลับเกี่ยวกับแนวทางของคุณ

นอกเหนือจากข้อกำหนดที่ระบุไว้ในส่วนก่อนหน้าแล้ว โปรดคำนึงถึงเคล็ดลับต่อไปนี้ด้วย

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

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

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

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

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