允許使用者設定應用程式小工具

應用程式小工具可進行設定。舉例來說，時鐘小工具可讓使用者設定要顯示的時區。

如果您想讓使用者調整小工具設定，請建立小工具設定 Activity。視您指定的設定選項而定，應用程式小工具主機會在建立小工具或之後自動啟動這個活動。

宣告設定活動

在 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>

由於啟動器會從套件範圍外參照活動，因此系統會使用完整的命名空間宣告該活動。

這就是開始設定活動所需的一切。接下來，您需要實作實際活動。

實作設定活動

實作活動時，請牢記兩個重點：

• 應用程式小工具主機會呼叫設定活動，而且設定活動一律必須傳回結果。結果必須包含啟動活動的意圖傳遞的應用程式小工具 ID (儲存在意圖額外項目中為 EXTRA_APPWIDGET_ID)。
• 啟動設定活動時，系統不會傳送 ACTION_APPWIDGET_UPDATE 廣播，也就是說，建立小工具時不會呼叫 onUpdate() 方法。設定活動在首次建立小工具時，必須負責向 AppWidgetManager 要求更新。不過，系統會呼叫 onUpdate() 進行後續更新，但只會第一次略過。

如需瞭解如何從設定傳回結果並更新小工具的範例，請參閱下一節的程式碼片段。

從設定活動中更新小工具

如果小工具使用設定活動，則在設定完成時，活動應負責更新小工具。您可以直接透過 AppWidgetManager 要求更新。

以下摘要說明正確更新小工具並關閉設定活動的程序：

1. 從啟動活動的意圖取得應用程式小工具 ID：

   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. 設定完成後，請呼叫 getInstance(Context) 來取得 AppWidgetManager 的例項：

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)
   

   Java

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
   

5. 呼叫 updateAppWidget(int,RemoteViews)，以 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();
   

如需範例，請參閱 GitHub 上的 ListWidgetConfigureActivity.kt 範例類別。

小工具設定選項

根據預設，應用程式小工具主機只會在使用者將小工具新增至主畫面後，立即啟動設定活動一次。不過，您可以指定相關選項，讓使用者能重新設定現有的小工具，或藉由提供預設的小工具設定來略過初始小工具設定。

允許使用者重新設定放置的小工具

如要允許使用者重新設定現有的小工具，請在 appwidget-provider 的 widgetFeatures 屬性中指定 reconfigurable 標記。詳情請參閱宣告 AppWidgetProviderInfo.xml 檔案指南。舉例來說：

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

使用者只要按住小工具，然後輕觸「重新設定」按鈕 (如圖 1 所示的 1)，即可重新設定小工具。

使用小工具的預設設定

您可以讓使用者略過初始設定步驟，打造更流暢的小工具體驗。如要執行此操作，請在 widgetFeatures 欄位中同時指定 configuration_optional 和 reconfigurable 標記。這樣一來，就不會在使用者新增小工具後啟動設定活動。如上所述，使用者之後仍可重新設定小工具。舉例來說，時鐘小工具可以略過初始設定，並預設顯示裝置時區。

以下範例說明如何將設定活動標示為可重新設定和選用：

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