อนุญาตให้ผู้ใช้กำหนดค่าวิดเจ็ตแอป

ออกแบบวิดเจ็ตเพื่อให้ผู้ใช้กำหนดค่าลักษณะเฉพาะได้ เช่น วิดเจ็ตนาฬิกาช่วยให้ผู้ใช้กำหนดค่าเขตเวลาที่จะแสดงได้

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

ประกาศกิจกรรมการกำหนดค่า

ประกาศกิจกรรมการกำหนดค่าเป็นกิจกรรมปกติในไฟล์ Manifest ของ Android โฮสต์วิดเจ็ตแอปจะเปิดใช้ด้วยการดำเนินการ ACTION_APPWIDGET_CONFIGURE ดังนั้นกิจกรรมจึงต้องยอมรับ Intent นี้ เช่น

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

ประกาศกิจกรรมในไฟล์ AppWidgetProviderInfo.xml ด้วยแอตทริบิวต์ android:configure ดูข้อมูลเพิ่มเติมเกี่ยวกับการประกาศไฟล์นี้ ตัวอย่างวิธีประกาศกิจกรรมการกำหนดค่ามีดังนี้

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

มีการประกาศกิจกรรมด้วยเนมสเปซที่สมบูรณ์ในตัวเอง เนื่องจาก Launcher อ้างอิงจากภายนอกขอบเขตแพ็กเกจ

เพียงเท่านี้คุณก็พร้อมเริ่มกิจกรรมการกำหนดค่าแล้ว จากนั้นคุณต้อง ใช้งานกิจกรรมจริง

ใช้กิจกรรมการกำหนดค่า

มี 2 สิ่งสำคัญที่ควรทราบเมื่อคุณใช้กิจกรรม

• โฮสต์วิดเจ็ตแอปจะเรียกกิจกรรมการกำหนดค่า และกิจกรรมการกำหนดค่า ต้องแสดงผลลัพธ์เสมอ ผลลัพธ์ต้องมีวิดเจ็ตแอป ID ที่ส่งผ่านโดย Intent ที่เปิดกิจกรรมซึ่งบันทึกไว้ในส่วนพิเศษของ Intent เป็น EXTRA_APPWIDGET_ID
  • ระบบจะไม่ส่งACTION_APPWIDGET_UPDATEการออกอากาศ เมื่อเปิดใช้กิจกรรมการกำหนดค่า ซึ่งหมายความว่าจะไม่เรียกใช้ การอัปเดตวิดเจ็ตในตอนแรกเมื่อสร้างวิดเจ็ต กิจกรรมการกำหนดค่ามีหน้าที่รับผิดชอบในการขออัปเดตจาก GlanceAppWidget เมื่อสร้างวิดเจ็ตเป็นครั้งแรก อย่างไรก็ตาม ระบบจะทริกเกอร์การอัปเดตโดยอัตโนมัติสำหรับรอบถัดๆ ไป

ดูข้อมูลโค้ดในส่วนต่อไปนี้เพื่อดูตัวอย่างวิธีแสดงผลลัพธ์จาก การกำหนดค่าและอัปเดตวิดเจ็ต Glance

อัปเดตวิดเจ็ตจากกิจกรรมการกำหนดค่า

เมื่อวิดเจ็ตใช้กิจกรรมการกำหนดค่า กิจกรรมนั้นมีหน้าที่อัปเดตวิดเจ็ตเมื่อการกำหนดค่าเสร็จสมบูรณ์ โดยทำได้โดย ทริกเกอร์การอัปเดตด้วยตนเองจากอินสแตนซ์ GlanceAppWidget โดยตรง

สรุปขั้นตอนการอัปเดตวิดเจ็ตอย่างถูกต้องและปิด กิจกรรมการกำหนดค่ามีดังนี้

1. รับรหัส App Widget จาก Intent ที่เปิดใช้กิจกรรม

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

2. ตั้งค่าผลลัพธ์ของกิจกรรมเป็น RESULT_CANCELED

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

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

3. กำหนดค่าวิดเจ็ตตามค่ากำหนดของผู้ใช้ เช่น เขียนตัวเลือกไปยัง Datastore แบบถาวรหรือฐานข้อมูลในเครื่อง

4. เมื่อกำหนดค่าเสร็จแล้ว ให้ดึงข้อมูล GlanceId ที่สอดคล้องกับ รหัสวิดเจ็ตแพลตฟอร์ม

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. อัปเดตเนื้อหาวิดเจ็ตโดยเรียกใช้updateฟังก์ชันระงับในอินสแตนซ์ GlanceAppWidget

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. สร้างความตั้งใจที่จะกลับมา ตั้งค่าด้วยผลลัพธ์ของกิจกรรม และทำกิจกรรมให้เสร็จสมบูรณ์

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

ตัวเลือกการกำหนดค่าวิดเจ็ต

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

เปิดให้ผู้ใช้กำหนดค่าวิดเจ็ตที่วางไว้ใหม่

หากต้องการอนุญาตให้ผู้ใช้กำหนดค่าเครื่องมือที่มีอยู่อีกครั้ง ให้ระบุแฟล็ก reconfigurable ในแอตทริบิวต์ widgetFeatures ของ appwidget-provider เช่น

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

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

ใช้การกำหนดค่าเริ่มต้นของวิดเจ็ต

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

ตัวอย่างวิธีทํากิจกรรมการกําหนดค่าเป็นทั้ง กําหนดค่าใหม่ได้และไม่บังคับมีดังนี้

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>