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

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

如要允許使用者調整小工具設定，請建立小工具 「設定」圖示 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()，而且只會略過 一切都是從 0 開始

請參閱下一節的程式碼片段範例，瞭解如何傳回 然後更新小工具

從設定活動中更新小工具

當小工具使用設定活動時， 設定完成後，要更新小工具的活動。您可以這麼做 直接從 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. 使用 呼叫 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敬上 查看範例

小工具設定選項

根據預設，應用程式小工具主機只會啟動設定活動一次。 。不過， 可指定相關選項，讓使用者重新設定現有的小工具或 提供預設的小工具設定，藉此略過初始小工具設定。

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

如要讓使用者重新設定現有的小工具，請指定 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>