可設定應用程式小工具。例如,時鐘小工具可讓使用者設定要顯示的時區。
如要讓使用者調整小工具設定,請建立小工具設定 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
要求更新。
以下摘要說明正確更新小工具及關閉設定活動的程序:
從啟動活動的意圖取得應用程式小工具 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); }
將活動結果設為
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);
根據使用者的偏好設定設定小工具。
設定完成後,請呼叫
getInstance(Context)
來取得AppWidgetManager
的例項:Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
呼叫
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);
建立回傳意圖,使用活動結果設定它,然後完成活動:
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>
允許使用者固定小工具
在搭載 Android 8.0 (API 級別 26) 以上版本的裝置上,可讓使用者建立固定捷徑的啟動器也能將小工具固定在主畫面上。與固定捷徑類似,這些固定的小工具可讓使用者存取應用程式中的特定工作,並且可以直接從應用程式新增至主畫面,如以下影片所示。
在應用程式中完成下列步驟,即可建立要求,讓系統將小工具固定至支援的啟動器:
呼叫
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); }