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

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

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

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

ประกาศกิจกรรมการกำหนดค่าเป็นกิจกรรมปกติในไฟล์ Android Manifest โฮสต์วิดเจ็ตแอปจะเปิดใช้ด้วยการดำเนินการ 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 สิ่งต่อไปนี้

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

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

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

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

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

  1. รับรหัส App Widget จาก 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>