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

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

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

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

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

<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 ประการที่ควรคำนึงถึงเมื่อดำเนินกิจกรรม ดังนี้

  • โฮสต์วิดเจ็ตแอปเรียกใช้กิจกรรมการกำหนดค่าและการกำหนดค่า activity ต้องแสดงผลลัพธ์เสมอ ผลการค้นหาต้องมีวิดเจ็ตแอป รหัสที่ส่งมาจาก Intent ที่เริ่มกิจกรรม ซึ่งบันทึกไว้ใน Intent ค่าใช้จ่ายเพิ่มเติมเป็น 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. สร้างความตั้งใจในการคืนสินค้า ตั้งค่าพร้อมผลลัพธ์กิจกรรม และ ทำกิจกรรมให้เสร็จ

    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 เป็นต้น

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

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

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

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

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

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

วันที่ ปุ่มปรากฏที่มุมขวาล่าง
รูปที่ 1 ปุ่มกำหนดค่าใหม่ของวิดเจ็ต

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

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

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

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