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

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

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

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

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

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

โปรดคำนึงถึง 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 ซึ่งจะข้ามการเริ่มกิจกรรมการกําหนดค่าหลังจากที่ผู้ใช้เพิ่มวิดเจ็ต ดังที่ได้กล่าวไปก่อนหน้านี้ ผู้ใช้จะยังคงกําหนดค่าวิดเจ็ตอีกครั้งได้หลังจากนั้น ตัวอย่างเช่น วิดเจ็ตนาฬิกาสามารถข้ามการกำหนดค่าเริ่มต้นไปได้ และ แสดงเขตเวลาของอุปกรณ์โดยค่าเริ่มต้น

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

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