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

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

หากต้องการอนุญาตให้ผู้ใช้กำหนดค่าการตั้งค่าของวิดเจ็ต ให้สร้างวิดเจ็ต การกำหนดค่า 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 สิ่งสำคัญที่ควรคำนึงถึงเมื่อใช้กิจกรรม

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

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

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

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

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

1. รับรหัสวิดเจ็ตแอปจาก 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>