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

可設定應用程式小工具。例如,時鐘小工具可讓使用者設定要顯示的時區。

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

宣告設定活動

在 Android 資訊清單檔案中將設定活動宣告為一般活動。應用程式小工具主機會透過 ACTION_APPWIDGET_CONFIGURE 動作啟動應用程式,因此活動需要接受此意圖。例如:

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

使用 android:configure 屬性在 AppWidgetProviderInfo.xml 檔案中宣告活動。如要進一步瞭解如何宣告這個檔案,請參閱本文。以下範例說明如何宣告設定活動:

<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-providerwidgetFeatures 屬性中指定 reconfigurable 標記。詳情請參閱宣告 AppWidgetProviderInfo.xml 檔案指南。例如:

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

如要重新設定小工具,使用者可以按住小工具,並輕觸「重新設定」按鈕 (圖 1 中標示「1」)。

按鈕會顯示在右下角
圖 1 小工具的「重新設定」按鈕。

使用小工具的預設設定

您可以讓使用者略過初始設定步驟,提供更順暢的小工具體驗。方法是在 widgetFeatures 欄位中指定 configuration_optionalreconfigurable 標記。這樣就無須在使用者新增小工具後啟動設定活動。如前所述,使用者之後仍可重新設定小工具。舉例來說,時鐘小工具可以略過初始設定,預設顯示裝置時區。

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

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

允許使用者固定小工具

在搭載 Android 8.0 (API 級別 26) 以上版本的裝置上,可讓使用者建立固定捷徑的啟動器也能將小工具固定在主畫面上。與固定捷徑類似,這些固定的小工具可讓使用者存取應用程式中的特定工作,而且可以直接從應用程式新增至主畫面。舉例來說,當使用者在天氣應用程式中新增城市時,您可以提示使用者在其主畫面中新增該城市的天氣小工具。

在應用程式中完成下列步驟,即可建立要求,讓系統將小工具固定至支援的啟動器:

  1. 請務必在應用程式的資訊清單檔案中宣告小工具

  2. 呼叫 requestPinAppWidget() 方法,如以下程式碼片段所示:

Kotlin

val appWidgetManager = AppWidgetManager.getInstance(context)
val myProvider = ComponentName(context, ExampleAppWidgetProvider::class.java)

if (appWidgetManager.isRequestPinAppWidgetSupported()) {
    // Create the PendingIntent object only if your app needs to be notified
    // when the user chooses to pin the widget. Note that if the pinning
    // operation fails, your app isn't notified. This callback receives the ID
    // of the newly pinned widget (EXTRA_APPWIDGET_ID).
    val successCallback = PendingIntent.getBroadcast(
            /* context = */ context,
            /* requestCode = */ 0,
            /* intent = */ Intent(...),
            /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT)

    appWidgetManager.requestPinAppWidget(myProvider, null, successCallback)
}

Java

AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
ComponentName myProvider = new ComponentName(context, ExampleAppWidgetProvider.class);

if (appWidgetManager.isRequestPinAppWidgetSupported()) {
    // Create the PendingIntent object only if your app needs to be notified
    // when the user chooses to pin the widget. Note that if the pinning
    // operation fails, your app isn't notified. This callback receives the ID
    // of the newly pinned widget (EXTRA_APPWIDGET_ID).
    PendingIntent successCallback = PendingIntent.getBroadcast(
            /* context = */ context,
            /* requestCode = */ 0,
            /* intent = */ new Intent(...),
            /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT);

    appWidgetManager.requestPinAppWidget(myProvider, null, successCallback);
}