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

วิดเจ็ตแอปกำหนดค่าได้ เช่น วิดเจ็ตนาฬิกาช่วยให้ผู้ใช้กำหนดค่าเขตเวลาที่จะแสดงได้

หากต้องการให้ผู้ใช้กำหนดการตั้งค่าวิดเจ็ต ให้สร้างการกำหนดค่าวิดเจ็ต 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>

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

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

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

โปรดคำนึงถึง 2 สิ่งต่อไปนี้เมื่อใช้กิจกรรม

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

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

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

เมื่อวิดเจ็ตใช้กิจกรรมการกําหนดค่า กิจกรรมดังกล่าวจะมีหน้าที่อัปเดตวิดเจ็ตเมื่อการกําหนดค่าเสร็จสมบูรณ์ โดยขอการอัปเดตจาก AppWidgetManager โดยตรง

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

1. รับรหัสวิดเจ็ตแอปจาก Intent ที่เปิดใช้งานกิจกรรม

   Kotlin

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

   Java

   Intent intent = getIntent();
   Bundle extras = intent.getExtras();
   int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
   if (extras != null) {
       appWidgetId = extras.getInt(
               AppWidgetManager.EXTRA_APPWIDGET_ID,
               AppWidgetManager.INVALID_APPWIDGET_ID);
   }
   

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

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

   Kotlin

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

   Java

   int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(Activity.RESULT_CANCELED, resultValue);
   

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

4. เมื่อกําหนดค่าเสร็จแล้ว ให้รับอินสแตนซ์ของ AppWidgetManager โดยเรียกใช้ getInstance(Context)

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)
   

   Java

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
   

5. อัปเดตวิดเจ็ตที่มีเลย์เอาต์ RemoteViews โดยเรียกใช้ updateAppWidget(int,RemoteViews)

   Kotlin

   val views = RemoteViews(context.packageName, R.layout.example_appwidget)
   appWidgetManager.updateAppWidget(appWidgetId, views)
   

   Java

   RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
   appWidgetManager.updateAppWidget(appWidgetId, views);
   

6. สร้าง Intent ของผลลัพธ์ ตั้งค่า Intent นั้นด้วยผลลัพธ์ของกิจกรรม และสิ้นสุดกิจกรรม

   Kotlin

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

   Java

   Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(RESULT_OK, resultValue);
   finish();
   

ดูตัวอย่างได้จากคลาสตัวอย่าง ListWidgetConfigureActivity.kt ใน GitHub

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

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

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

หากต้องการให้ผู้ใช้กําหนดค่าวิดเจ็ตที่มีอยู่อีกครั้ง ให้ระบุ Flag reconfigurable ในแอตทริบิวต์ widgetFeatures ของ appwidget-provider ดูข้อมูลเพิ่มเติมได้ที่คู่มือการประกาศไฟล์AppWidgetProviderInfo.xml เช่น

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

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

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

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

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

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